feat: Add per-segment language detection and dual output files

- Add whatlang for real-time language detection per segment - Generate .asr.json (basic) and .asrx.json (with language labels) - Add auto-save progress with configurable interval - Add resume functionality for interrupted transcriptions - Add Music/Empty detection and statistics - Update progress display with unified format - Add comprehensive Chinese README with usage documentation
2026-03-11 18:17:55 +08:00
parent f9653eef58
commit d6af9546ea
4 changed files with 1022 additions and 175 deletions
--- a/README.md
+++ b/README.md
@@ -4,21 +4,25 @@

 ## 功能特性

- **高效音頻提取**：利用 FFmpeg 直接從影片或音頻檔案中提取並重採樣為 Whisper 所需的格式 (16kHz, Mono, f32)。
- **精準轉寫**：基於 OpenAI Whisper 模型，提供高精度的語音轉文字功能。
- **時間碼支援**：自動產生精確到毫秒的逐字稿時間戳。
- **語言自動檢測**：若未指定語言，可自動偵測輸入音頻的語言。
- **優化進度顯示**：在轉寫過程中提供即時的處理進度、耗時與預估剩餘時間。
+- **高效音頻提取**：利用 FFmpeg 直接從影片或音頻檔案中提取並重採樣為 Whisper 所需的格式 (16kHz, Mono, f32)
+- **精準轉寫**：基於 OpenAI Whisper 模型，提供高精度的語音轉文字功能
+- **時間碼支援**：自動產生精確到毫秒的逐字稿時間戳，格式為 `HH:MM:SS.mmm(fXX)` (25fps)
+- **語言自動檢測**：若未指定語言，可自動偵測輸入音頻的語言
+- **優化進度顯示**：在轉寫過程中提供即時的處理進度、耗時與預估剩餘時間
+- **自動存檔**：支援定期自動存檔，避免長時間轉寫因意外中斷而遺失進度
+- **中斷續處理**：支援從上次中斷點繼續處理
+- **語言分段檢測**：自動檢測每段文字的語言類型，生成帶語言標籤的逐字稿
+- **特殊內容識別**：自動識別 Music (音樂) 和 Empty (空文字) 分段

 ## 前置需求

 在編譯與執行前，請確保系統已安裝以下環境：

-1. **Rust 環境**：請安裝 [Rustup](https://rustup.rs/)。
-2. **FFmpeg**：系統必須安裝 FFmpeg 開發庫。
+1. **Rust 環境**：請安裝 [Rustup](https://rustup.rs/)
+2. **FFmpeg**：系統必須安裝 FFmpeg 開發庫
   - macOS: `brew install ffmpeg`
   - Ubuntu/Debian: `sudo apt install libavcodec-dev libavformat-dev libavutil-dev libswresample-dev`
-3. **Whisper 模型**：請準備 Whisper 的 `.bin` 模型檔案 (例如 `ggml-base.bin`)，並放置於 `models/` 目錄中。
+3. **Whisper 模型**：請準備 Whisper 的 `.bin` 模型檔案，並放置於 `models/` 目錄中

 ## 編譯與安裝

@@ -33,7 +37,7 @@ cargo build --release

 ## 使用方式

-執行程式時，需指定輸入檔案路徑及模型路徑：
+### 基本使用

 ```bash
 ./target/release/rust-scribe <input_file> --model models/<your-model.bin>
@@ -41,33 +45,148 @@ cargo build --release

 ### 參數說明

- `<input_file>`: 欲轉寫的影片或音頻檔案路徑 (位置參數)。
- `-m, --model <MODEL_PATH>`: Whisper 模型檔案路徑 (必填)。
- `-l, --language <LANG>`: 指定轉寫語言 (例如 `zh`, `en`)。若不指定，系統將自動偵測 (選填)。
- `-v, --verbose`: 開啟詳細轉寫進度輸出 (選填)。
+| 參數 | 說明 | 必填 |
+|------|------|------|
+| `<input_file>` | 欲轉寫的影片或音頻檔案路徑 | ✅ |
+| `-m, --model <MODEL_PATH>` | Whisper 模型檔案路徑 | ✅ |
+| `-l, --language <LANG>` | 指定轉寫語言 (例如 `zh`, `en`)。若不指定將自動偵測 | ❌ |
+| `-v, --verbose` | 開啟詳細轉寫進度輸出 | ❌ |
+| `--save-interval <N>` | 每 N 個分段自動存檔一次 (預設: 100) | ❌ |
+| `--max-duration <秒>` | 限制處理的最大時長（用於測試） | ❌ |

-**使用範例**：
+### 使用範例

 ```bash
-# 指定使用 base 模型，自動檢測語言
-cargo run --release -- video.mp4 --model models/ggml-base.bin
+# 基本使用，自動檢測語言，每 10 個分段存檔
+cargo run --release -- video.mp4 --model models/ggml-base.bin --save-interval 10

-# 指定使用中文進行轉寫
+# 指定中文轉寫
 cargo run --release -- lecture.mkv --model models/ggml-base.bin --language zh
+
+# 限制處理前 60 秒（用於測試）
+cargo run --release -- video.mp4 --model models/ggml-base.bin --max-duration 60
 ```

+## 輸出檔案
+
+程式會生成兩個輸出檔案：
+
+### 1. `.asr.json` - 基本逐字稿
+包含基本的轉寫結果：
+```json
+{
+  "input_file": "video.mp4",
+  "language": "English",
+  "segments": [
+    {
+      "start": "00:00:05.120(f03)",
+      "end": "00:00:08.560(f14)",
+      "text": "Hello everyone",
+      "language": "English"
+    }
+  ]
+}
+```
+
+### 2. `.asrx.json` - 帶語言檢測的逐字稿
+包含每段文字的語言檢測結果：
+```json
+{
+  "input_file": "video.mp4",
+  "segments": [
+    {
+      "start": "00:00:05.120(f03)",
+      "end": "00:00:08.560(f14)",
+      "text": "Hello everyone",
+      "language": "English",
+      "confidence": 0.98
+    },
+    {
+      "start": "00:00:10.000(f00)",
+      "end": "00:00:13.000(f00)",
+      "text": "[Music]",
+      "language": "Music",
+      "confidence": 1.0
+    }
+  ]
+}
+```
+
+## 進度顯示說明
+
+轉寫過程中會顯示即時進度：
+
+```
+═══════════════════════════════════════════════════════════
+🎙️  Transcribing (this may take a few minutes)...
+💡  Auto-saving every 10 segments
+📋 Legend:
+   P = Processed (已處理分段數)
+   A = ASR saved (.asr.json 已存檔數)
+   X = Lang detect saved (.asrx.json 已存檔數)
+═══════════════════════════════════════════════════════════
+
+🔄 Progress: [71:05/114:39] 62.0% | Elapsed: 03:04 | Remaining: 01:54 | P:1112 A:1110 X:1110 | English:500 Unknown:52 Music:58
+```
+
+### 進度列格式說明
+
+- **時間進度**：`[已處理時間/總時長] 完成百分比`
+- **時間統計**：`Elapsed: 已耗時 | Remaining: 預估剩餘時間`
+- **分段統計**：`P:已處理數 A:ASR存檔數 X:語言檢測存檔數`
+- **語言統計**：各語言類型的分段數量（依序顯示）
+
+### 特殊類型標籤
+
+- **Music**：音樂或背景音效段落
+- **Empty**：空文字或純空白段落
+- **Unknown**：語言識別置信度低於 0.5 的段落
+
+## 中斷續處理
+
+程式支援中斷後繼續處理：
+
+1. 當程式偵測到已存在的輸出檔案時，會詢問是否繼續
+2. 選擇 `[C] Continue` 會從上次中斷點繼續
+3. 選擇 `[R] Restart` 會刪除舊檔案重新開始
+
+兩個檔案（`.asr.json` 和 `.asrx.json`）會同步處理。
+
+## 語言檢測說明
+
+使用 [whatlang](https://github.com/greyblake/whatlang-rs) 函式庫進行語言檢測：
+
+- **置信度 ≥ 0.5**：顯示檢測到的語言名稱
+- **置信度 < 0.5**：標註為 "Unknown"
+- **Music**：自動識別包含 [Music] 或 (music) 標記的段落
+- **Empty**：空文字或純空白段落
+
 ## 專案結構

 ```
 rust-scribe/
 ├── src/
-│   └── main.rs           # 核心邏輯 (音頻處理、Whisper 轉寫、CLI 介面)
-├── models/               # 存放 Whisper 模型檔案
-├── Cargo.toml            # 專案依賴與配置
+│   └── main.rs           # 核心邏輯
+├── models/               # Whisper 模型檔案
+├── Cargo.toml            # 專案配置
+├── Cargo.lock            # 依賴鎖定
+├── README.md             # 使用文檔
+├── AGENTS.md             # 開發者規範
 └── .cargo/
-    └── config.toml       # Cargo 編譯配置
+    └── config.toml       # Cargo 配置
 ```

 ## 開發者規範

 請參閱 `AGENTS.md` 了解詳細的代碼風格、編譯與測試指南。
+
+## 許可證
+
+MIT License
+
+## 致謝
+
+- [Whisper.cpp](https://github.com/ggerganov/whisper.cpp) - OpenAI Whisper 的 C++ 實現
+- [FFmpeg](https://ffmpeg.org/) - 音頻處理函式庫
+- [whisper-rs](https://github.com/tazz4843/whisper-rs) - Whisper.cpp 的 Rust 綁定
+- [whatlang](https://github.com/greyblake/whatlang-rs) - 自然語言檢測函式庫