一个为 Echo-live/OBS 工作流打造的命令行控制台，专注于让无声系虚拟主播和需要批量发送字幕的创作者高效控制弹幕展示。它提供可视化的 CLI 体验、本地配置持久化、丰富的富文本格式，并支持打包为单文件可执行程序。
⚠️ 项目仍在积极开发中，行为可能随版本演化。本文档描述的是master分支当前实现。
- 即开即用的本地 WebSocket 服务器：在本机监听 Echo-live 广播端口，与 OBS 中的 Echo-live 无缝对接。
- 交互式命令行体验：基于 Rich 的彩色终端，提供命令提示与友好输出。
- 富文本格式与快速标记：支持 Markdown 强调语法与
@前缀快捷码，快速叠加粗体、斜体、颜色、字号、类名等效果。 - Typewriting 与自动停顿：按需生成打字机效果与自动插入停顿帧，让字幕播放更自然。
- 可配置的消息修饰：可自动为文本添加引号、括号，并为用户名套上【】以突出显示。
- 可编程的消息后缀：支持自动为文本追加自定义结尾字符（默认“喵”），并提供语义判断避免对无意义内容添尾。
- 退出保护：默认屏蔽
Ctrl+C等中断信号，避免误触；可通过命令即时切换。 - 批量脚本执行：通过
/source命令导入message_sample.txt等脚本文件，实现自动播报。 - 跨平台打包：使用 Nuitka 编译打包，可将工具封装为优化的单文件可执行程序。
-
在 OBS 中安装并配置最新的 Echo-live。
-
打开 Echo-live 的
config.js，设置 WebSocket：websocket_enable: true, websocket_url: 'ws://127.0.0.1:3000'
- 若 Echo-live 与本程序不在同一台设备，
websocket_url请改为服务器的 IP，且在 echo-client 的配置中把host改为0.0.0.0。
- 若 Echo-live 与本程序不在同一台设备，
-
安装并运行 echo-client：
pip install echo-client echo-client
或在源码仓库：
python -m pip install --upgrade pip pip install -r requirements.txt python -m echo_client.cli
首次启动会在工作目录生成 config.yaml。终端会打印监听地址、配置路径等提示。
- Echo-live 的 WebSocket 客户端连接到
ws://<host>:<port>（默认127.0.0.1:3000）。 - 建议在 OBS 中刷新浏览器源以触发连接。
- 连接后，终端会显示客户端 ID、显示名称、心跳次数、实时展示状态等事件。
配置保存于可执行文件或脚本所在目录的 config.yaml，字段说明如下：
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
command_prefix | str | / | 命令前缀。若要发送以 / 开头的消息，可输入 //文本 。 |
username | str | Someone | 推送给 Echo-live 的默认用户名，可交互命令 /ren 修改。 |
host | str | 127.0.0.1 | WebSocket 监听地址，跨设备使用请改为 0.0.0.0。 |
port | int | 3000 | WebSocket 监听端口。 |
typewriting | bool | true | 是否启用打字机同步。/typewrite（或 /tt）可切换。 |
typewriting_scheme | str | pinyin | 打字机模式，支持 pinyin（拼音）与 zhuyin（注音），/scheme（/ts 或 /tts）可切换。 |
autopause | bool | false | 自动插入停顿标记。/autopause（或 /ta）可切换。 |
autopausestr | str | ,，.。;；:：!！ | 触发停顿的字符集合。 |
autopausetime | int | 10 | 停顿时长单位，取决于打印速度。 |
print_speed | int | 10 | 默认打印速度（毫秒/字符），/speed <value>（或 /ps）可调整。 |
quote_style | str | en | 自动引号样式，可选 en（英文双引号）、cn（中文书名号）、jp（日式括号）、custom（使用下方自定义的左右符号）、none（禁用）。通过 /quote <style> 修改。 |
quote_custom_left | str | "" | 自定义左引号，仅在 quote_style 设置为 custom 时生效。 |
quote_custom_right | str | "" | 自定义右引号，仅在 quote_style 设置为 custom 时生效。 |
auto_parentheses | bool | false | 是否自动用圆括号包裹消息，可用 /paren 切换或 /paren once 仅对下一条生效。 |
username_brackets | bool | true | 是否使用 【】 包裹用户名，/brackets（或 /ub）可切换。 |
auto_suffix | bool | false | 是否自动为消息追加自定义结尾字符，/suffix 可切换或设置。 |
auto_suffix_value | str | 喵 | 自动追加的结尾字符，/suffix <字符> 可修改。 |
inhibit_ctrl_c | bool | true | 是否启用 Ctrl+C 退出保护，/nocc 可切换。 |
skip_mode | str | blank_text | 跳过对话的模式，可选：echo_next（发送 echo_next 停止输出）、blank_text（推送空白文本到 live 组）、hide_display（发送隐藏 live 指令）。 |
每次通过命令修改都会即时落盘。手动编辑文件后，可使用 /reload 命令热重载配置（不重启服务器），或使用 /reload warm 温重载（重启服务器）。
命令以 command_prefix 开头，可使用别名简写：
| 命令 | 别名 | 描述 |
|---|---|---|
/help [command] | /h, /? | 显示命令列表或查看某个命令的详细说明。 |
/quit | /q, /exit | 关闭服务器并退出程序。 |
/name <name> | /ren | 更新默认显示名称并保存配置。 |
/speed <ms> | /ps | 设置默认打印速度（毫秒/字符）。 |
/typewrite | /tt | 切换 Typewriting 效果。 |
/scheme | /ts | 在拼音与注音模式之间切换 Typewriting。 |
/autopause | /ta | 切换自动停顿。 |
/quote <style> [left] [right] | /quotes, /tq | 设置自动引号样式，style 可为 en/cn/jp/custom/none；custom 模式需额外提供左右引号，none 禁用自动引号。 |
| `/suffix [on | off | 文本…]` |
| `/nocc [on | off]` | /noc |
| `/paren [once | on | off]` |
/brackets | /ub, /tub | 切换是否用 【】 包裹用户名。 |
/skip | /cancel | 根据 skip_mode 配置跳过当前对话。支持三种模式：echo_next（停止输出）、blank_text（发送空白文本，默认）、hide_display（隐藏显示）。 |
/clear | /clr, /cls | 清空历史记录框。 |
/source <file> | /src, /load | 按行执行脚本文件中的指令。 |
| `/reload [hot | warm]` | /rl |
想发送以
/开头的纯文本，可输入//这是内容，程序会自动转换。 使用/help可查看命令列表，并随时了解各开关的当前状态。
echo-client 同时支持两套叠加格式：
-
Markdown：
**文本**或__文本__→ 粗体*文本*或_文本_→ 斜体`代码`→ 代码风格
-
快速格式化（Fast Formatting）：
片段 效果 @b/@i/@u/@s粗体 / 斜体 / 下划线 / 删除线 @[color]设置颜色，例如 @[#66ccff]@+/@-放大 / 缩小字号（多次叠加） @r恢复默认样式 @{emoji}插入表情或图片占位符 ID @<class>添加 CSS 类，自动加上 echo-text-前缀；@<:class>则原样保留\@输出字面量 @
更完整的示例请查看仓库中的 message_sample.txt，可在程序内运行：
/s message_sample.txt 默认会为消息自动添加一对双引号；使用
/quote none禁用，或选择cn/jp/custom样式（custom可配合quote_custom_left/right）改变配对符号，圆括号可另行叠加。
- 自动停顿（Autopause）：开启后，程序会在
autopausestr中的字符后插入一个 “pause” 事件，时长由autopausetime与打印速度共同决定。 - Typewriting：对中文使用
jieba分词，对每段文字生成拼音，配合 Echo-live 的打字机效果；也可切换为注音模式，以 Bopomofo 输出。
两项能力都可随时通过命令切换，并立即作用于接下来的消息。
使用 Nuitka 打包为优化的独立可执行文件：
python -m pip install --upgrade pip pip install -r pyrequirements.txt python -m nuitka --standalone --onefile --include-package-data=pypinyin --windows-icon-from-ico=realme_sheep_triangle.ico --assume-yes-for-downloads --output-filename=echo-client.exe --output-dir=dist --remove-output main.py构建完成的单文件位于 dist/echo-client.exe。可执行文件会在自身目录创建/更新 config.yaml，无需额外携带配置。
git clone https://github.com/xrh0905/echo-client.git cd echo-client python -m pip install --upgrade pip pip install -r pyrequirements.txt python -m echo_client.cli- 代码格式建议使用
ruff/pylint等工具（仓库默认提供pylint）。 - 提交 PR 或 issue 前请说明使用场景，尤其是 Echo-live 与 echo-client 的版本信息。
- 客户端无法连接：确认 Echo-live 的
websocket_url是否指向本机监听地址，并检查端口占用问题。 - 消息没有格式效果：确保 Echo-live 版本支持传入的字段；
@快捷码与 Markdown 可叠加使用。 - 打字机太慢/太快：通过
/ps <毫秒>即时调整打印速度，或修改config.yaml后重启。 - 想要批量发送：将指令写入文本文件后使用
/source your_file.txt（亦可使用别名/src）。
本项目基于以下优秀的开源项目和贡献者：
-
原始 echo-client 项目: 由 Rickyxrc 创建和开发。感谢原作者的创意和基础实现。
- 原始仓库: Rickyxrc/echo-client
-
Echo-Live 项目: 由 sheep-realms 开发的强大字幕展示系统，为本工具提供了核心的 WebSocket 广播协议和字幕渲染能力。
- 项目地址: sheep-realms/Echo-Live
- 官方文档: Echo-Live Documentation
感谢所有为这些项目做出贡献的开发者和社区成员！
欢迎通过 issue、讨论区或 PR 分享使用心得与改进建议！