Single-machine subtitle automation pipeline

video-subtitle

video-subtitle 是單機字幕自動化工具,負責把 video input(影片輸入)轉成可審查的 transcript(逐字稿)、translated SRT(翻譯字幕)、quality report(品質報告)與 optional burn-in output(可選燒錄輸出)。這份 showcase(展示頁)說明它如何流動、誰會操作,以及哪些資料不能進入公開 repo(儲存庫)。

Subtitle Pipeline Consolestatic preview
ASRWhisper runner(語音辨識)
SRTParser + validator(字幕檢核)
QATranscript + translation checks(品質檢查)
BurnFFmpeg burner(影片燒錄)
Transcribe
ready
Translate
guarded
Review
manual
Project intent(專案定位)

靜態展示,不讀取 live media(即時媒體)或 private data(私密資料)

頁面只描述 repo(儲存庫)內的 architecture(架構)、workflow(工作流程)與 verification(驗證方式)。它不會掃描本機影片、不會讀取 `.env`、不會呼叫 OpenAI API(OpenAI 介面)或 Whisper runtime(Whisper 執行環境)。

Operator(操作者)

一眼看懂要跑哪段

從 video intake(影片匯入)到 burn(燒錄)分成清楚節點,讓人工審查能停在 transcript(逐字稿)或 SRT(字幕檔)。

Reviewer(審查者)

把品質檢查前置

QA(品質檢查)不只是最後報告,而是 transcript、translation(翻譯)與 SRT validation(字幕驗證)的連續防線。

Maintainer(維護者)

對齊 repo 結構

圖中的每個責任區都對應到 `src/subtitle_pipeline/`、`tests/` 與 `docs/operations/`,方便追修。

Dynamic Pipeline(水管線路圖)

從影片到可發布字幕的六段水管

點選任一節點可看到 input(輸入)、owner(責任邊界)與 output(輸出)。動態線路只呈現資料流向,不代表頁面會執行 pipeline(管線)。

Input(輸入)
Video file path、`configs/*.yaml`、job workspace(工作區)
Owner(責任)
`src/subtitle_pipeline/cli.py` 與 `commands.py` 負責啟動流程。
Output(輸出)
建立可追蹤的 workspace(工作區),不把影片內容寫入 repo。
System Architecture(系統架構)

CLI(命令列介面)控制流程,domain modules(領域模組)各自守住邊界

這張圖把實際 code paths(程式路徑)放進 architecture map(架構地圖),讓 reviewer(審查者)可以從展示頁一路追到檔案。

Config(設定)`src/subtitle_pipeline/config.py`、`configs/production.yaml`、`.env.example` 定義非秘密設定。
CLI Entry(入口)`src/subtitle_pipeline/cli.py`、`commands.py` 包裝 run、transcribe、translate、burn。
Storage(儲存)`storage/workspace.py` 與 `job_state.py` 管理 workspace output(工作區輸出)。
Pipeline Orchestrator(管線編排) `src/subtitle_pipeline/pipeline.py` 串接 ASR(語音辨識)、QA(品質檢查)、translation(翻譯)、validation(驗證)與 report(報告)。它只描述工作流,不把 private video(私密影片)帶進 git(版本控管)。
Transcribe(轉錄)`transcribe/whisper_runner.py` 封裝 Whisper runtime(Whisper 執行環境)。
Translate + QA(翻譯與檢查)`translate/`、`qa/`、`subtitle/` 對 prompt、chunks(分段)、SRT(字幕檔)做檢核。
Docs + Tests(文件與測試)`docs/operations/` 說明流程;`tests/` 覆蓋 validator(驗證器)、rerun(重跑)、status(狀態)。
User Architecture(使用者架構)

操作者、審查者、發布者分工清楚

User architecture(使用者架構)描述人如何進出流程,而不是只描述 code(程式碼)。這能避免把字幕工具誤看成黑箱自動化。

Operator(操作者)

啟動 pipeline(管線)

提供影片路徑、設定檔與目標 workspace(工作區),負責確保輸入檔案留在本機邊界內。

Reviewer(審查者)

檢查 transcript / SRT

查看 report(報告)、可疑 segments(片段)與 glossary(詞彙表)命中情況,決定是否 rerun(重跑)。

Publisher(發布者)

取用輸出成果

只拿 approved SRT(核准字幕)、burned video(燒錄影片)或 QA summary(品質摘要),不把 raw media(原始媒體)推回 repo。

Verification Panel(驗證面板)

用 repo 內驗證流程確認文件與程式仍對齊

本頁只是一份 static showcase(靜態展示),實際品質仍由 scripts(腳本)、tests(測試)與人工預覽共同把關。

.\scripts\verify.ps1
python -m pytest
python -m http.server 8767 --bind 127.0.0.1
確認 `docs/showcase/index.html` 具備 system architecture(系統架構)、user architecture(使用者架構)與 dynamic pipeline(動態水管)。
確認 showcase(展示頁)不呼叫 API(介面)、不讀取 `.env`、不存取本機影片或字幕輸出。
桌面與手機寬度都要可讀,pipeline(管線)在小螢幕改為垂直節點。
Private Data Boundary(私密資料邊界)

展示 repo 能力,不展示真實影片內容

video-subtitle 的高風險資料是 raw video(原始影片)、audio(音訊)、transcript(逐字稿)、translated subtitle(翻譯字幕)、API key(介面金鑰)與 workspace output(工作區輸出)。這些不能被 HTML showcase(HTML 展示頁)讀取,也不能被 commit(提交)。

Never commit(禁止提交)

真實影片、音訊、逐字稿、字幕成品、`workspace/` output(輸出)與 `.env`。

Allowed examples(允許範例)

`examples/*.yaml`、`.env.example`、prompt templates(提示詞樣板)與人工撰寫的 docs(文件)。

Review rule(審查規則)

PR(合併請求)只能呈現 architecture(架構)與 anonymized behavior(匿名化行為),不能夾帶客戶或個人影片內容。