docs(engine-manual): 更新字幕引擎开发文档

- 添加了命令行参数指定的详细说明 - 增加了字幕引擎打包和运行的步骤说明 - 修复了一些文档中的错误和拼写问题
2026-02-04 04:14:42 +08:00 · 2025-07-11 13:25:52 +08:00
parent 6920957152
commit 7f8766b13e
4 changed files with 167 additions and 4 deletions
--- a/README.md
+++ b/README.md
@@ -152,7 +152,7 @@ pyinstaller ./main-gummy.spec
 pyinstaller ./main-vosk.spec
 ```

-注意 `main-vosk.spec` 文件中 `vsok` 库的路径可能不正确，需要根据实际状况配置。
+注意 `main-vosk.spec` 文件中 `vosk` 库的路径可能不正确，需要根据实际状况配置。

 ```
 # Windows
--- a/docs/engine-manual/en.md
+++ b/docs/engine-manual/en.md
@@ -151,6 +151,51 @@ Data receiver code is as follows:
 ...
 ```

+## Usage of Caption Engine
+
+### Command Line Parameter Specification
+
+The custom caption engine settings are specified via command line parameters. Common required parameters are as follows:
+
+```python
+import argparse
+
+...
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='Convert system audio stream to text')
+    parser.add_argument('-s', '--source_language', default='en', help='Source language code')
+    parser.add_argument('-t', '--target_language', default='zh', help='Target language code')
+    parser.add_argument('-a', '--audio_type', default=0, help='Audio stream source: 0 for output audio stream, 1 for input audio stream')
+    parser.add_argument('-c', '--chunk_rate', default=20, help='The number of audio stream chunks collected per second.')
+    parser.add_argument('-k', '--api_key', default='', help='API KEY for Gummy model')
+    args = parser.parse_args()
+    convert_audio_to_text(
+        args.source_language,
+        args.target_language,
+        int(args.audio_type),
+        int(args.chunk_rate),
+        args.api_key
+    )
+```
+
+For example, to specify Japanese as source language, Chinese as target language, capture system audio output, and collect 0.1s audio chunks, use the following command:
+
+```bash
+python main-gummy.py -s ja -t zh -a 0 -c 10 -k <your-api-key>
+```
+
+### Packaging
+
+After development and testing, package the caption engine into an executable file using `pyinstaller`. If errors occur, check for missing dependencies.
+
+### Execution
+
+With a working caption engine, specify its path and runtime parameters in the caption software window to launch it.
+
+![](../img/02_en.png)
+
+
 ## Reference Code

 The `main-gummy.py` file under the `caption-engine` folder in this project serves as the entry point for the default caption engine. The `src\main\utils\engine.ts` file contains the server-side code for acquiring and processing data from the caption engine. You can read and understand the implementation details and the complete execution process of the caption engine as needed.
--- a/docs/engine-manual/ja.md
+++ b/docs/engine-manual/ja.md
@@ -125,4 +125,77 @@ sys.stdout.reconfigure(line_buffering=True)
 ...
 ```

-データ受信側のコードは
+データ受信側のコード
+
+```typescript
+// src\main\utils\engine.ts
+...
+    this.process.stdout.on('data', (data) => {
+      const lines = data.toString().split('\n');
+      lines.forEach((line: string) => {
+        if (line.trim()) {
+          try {
+            const caption = JSON.parse(line);
+            addCaptionLog(caption);
+          } catch (e) {
+            controlWindow.sendErrorMessage('字幕エンジンの出力をJSONオブジェクトとして解析できません:' + e)
+            console.error('[ERROR] JSON解析エラー:', e);
+          }
+        }
+      });
+    });
+
+    this.process.stderr.on('data', (data) => {
+      controlWindow.sendErrorMessage('字幕エンジンエラー:' + data)
+      console.error(`[ERROR] サブプロセスエラー: ${data}`);
+    });
+...
+```
+
+## 字幕エンジンの使用方法
+
+### コマンドライン引数の指定
+
+カスタム字幕エンジンの設定はコマンドライン引数で指定します。主な必要なパラメータは以下の通りです：
+
+```python
+import argparse
+
+...
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='システムのオーディオストリームをテキストに変換')
+    parser.add_argument('-s', '--source_language', default='en', help='ソース言語コード')
+    parser.add_argument('-t', '--target_language', default='zh', help='ターゲット言語コード')
+    parser.add_argument('-a', '--audio_type', default=0, help='オーディオストリームソース: 0は出力音声、1は入力音声')
+    parser.add_argument('-c', '--chunk_rate', default=20, help='1秒間に収集するオーディオチャンク数')
+    parser.add_argument('-k', '--api_key', default='', help='GummyモデルのAPIキー')
+    args = parser.parse_args()
+    convert_audio_to_text(
+        args.source_language,
+        args.target_language,
+        int(args.audio_type),
+        int(args.chunk_rate),
+        args.api_key
+    )
+```
+
+例：原文を日本語、翻訳を中国語に指定し、システム音声出力を取得、0.1秒のオーディオデータを収集する場合：
+
+```bash
+python main-gummy.py -s ja -t zh -a 0 -c 10 -k <your-api-key>
+```
+
+### パッケージ化
+
+開発とテスト完了後、`pyinstaller`を使用して実行可能ファイルにパッケージ化します。エラーが発生した場合、依存ライブラリの不足を確認してください。
+
+### 実行
+
+利用可能な字幕エンジンが準備できたら、字幕ソフトウェアのウィンドウでエンジンのパスと実行パラメータを指定して起動します。
+
+![](../img/02_ja.png)
+
+## 参考コード
+
+本プロジェクトの`caption-engine`フォルダにある`main-gummy.py`ファイルはデフォルトの字幕エンジンのエントリーコードです。`src\main\utils\engine.ts`はサーバー側で字幕エンジンのデータを取得・処理するコードです。必要に応じて字幕エンジンの実装詳細と完全な実行プロセスを理解するために参照してください。
--- a/docs/engine-manual/zh.md
+++ b/docs/engine-manual/zh.md
@@ -32,7 +32,7 @@
 import sys
 import argparse

-# 引入系统音频获取勒
+# 引入系统音频获取类
 if sys.platform == 'win32':
    from sysaudio.win import AudioStream
 elif sys.platform == 'darwin':
@@ -100,7 +100,7 @@ export interface CaptionItem {
 }
 ```

-**注意必须确保咱们一起每输出一次字幕 JSON 数据就得刷新缓冲区，确保 electron 主进程每次接收到的字符串都可以被解释为 JSON 对象。**
+**注意必须确保每输出一次字幕 JSON 数据就得刷新缓冲区，确保 electron 主进程每次接收到的字符串都可以被解释为 JSON 对象。**

 如果使用 python 语言，可以参考以下方式将数据传递给主程序：

@@ -151,6 +151,51 @@ sys.stdout.reconfigure(line_buffering=True)
 ...
 ```

+## 字幕引擎的使用
+
+### 命令行参数的指定
+
+自定义字幕引擎的设置提供命令行参数指定，因此需要设置好字幕引擎的参数，常见的需要的参数如下：
+
+```python
+import argparse
+
+...
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='Convert system audio stream to text')
+    parser.add_argument('-s', '--source_language', default='en', help='Source language code')
+    parser.add_argument('-t', '--target_language', default='zh', help='Target language code')
+    parser.add_argument('-a', '--audio_type', default=0, help='Audio stream source: 0 for output audio stream, 1 for input audio stream')
+    parser.add_argument('-c', '--chunk_rate', default=20, help='The number of audio stream chunks collected per second.')
+    parser.add_argument('-k', '--api_key', default='', help='API KEY for Gummy model')
+    args = parser.parse_args()
+    convert_audio_to_text(
+        args.source_language,
+        args.target_language,
+        int(args.audio_type),
+        int(args.chunk_rate),
+        args.api_key
+    )
+```
+
+比如对应上面的字幕引擎，我想指定原文为日语，翻译为中文，获取系统音频输出的字幕，每次截取 0.1s 的音频数据，那么命令行参数如下：
+
+```bash
+python main-gummy.py -s ja -t zh -a 0 -c 10 -k <your-api-key>
+```
+
+### 打包
+
+在完成字幕引擎的开发和测试后，需要将字幕引擎打包成可执行文件。一般使用 `pyinstaller` 进行打包。如果打包好的字幕引擎文件执行报错，可能是打包漏掉了某些依赖库，请检查是否缺少了依赖库。
+
+### 运行
+
+有了可以使用的字幕引擎，就可以在字幕软件窗口中通过指定字幕引擎的路径和字幕引擎的运行指令（参数）来启动字幕引擎了。
+
+![](../img/02_zh.png)
+
+
 ## 参考代码

 本项目 `caption-engine` 文件夹下的 `main-gummy.py` 文件为默认字幕引擎的入口代码。`src\main\utils\engine.ts` 为服务端获取字幕引擎数据和进行处理的代码。可以根据需要阅读了解字幕引擎的实现细节和完整运行过程。