ona

參考與幫助

CLI 指南

從終端機執行 Sona 的離線批次轉錄，管理預設模型，產生 shell 補全腳本，並啟動無外介面本機服務。

向 AI 提问

当前部署尚未启用受保护的文档问答。

sona 透過桌面主程式提供離線轉錄指令。安裝包不會把 sona 寫入 shell PATH，因此需要直接執行已安裝的應用二進位檔案並附帶 CLI 子指令。從原始碼建構時，也可以用 Cargo 執行同一組命令。

CLI 範圍刻意保持精簡：單檔和目錄離線轉錄、預設模型清單/下載/刪除、無外介面 (headless) HTTP API 服務啟動。它不包含即時錄音、LLM 潤色或 LLM 翻譯。

執行方式

  • Windows：在安裝目錄執行 Sona.exe transcribe ...
  • macOS：執行 /Applications/Sona.app/Contents/MacOS/Sona transcribe ...
  • Linux 安裝包：從安裝位置執行 Sona 主程式並附帶 CLI 子指令
  • AppImage：執行掛載後的 AppImage 可執行檔並附帶 CLI 子指令
  • 原始碼：cargo run --manifest-path src-tauri/Cargo.toml -- transcribe ./sample.mp4 --config ./sona-cli.toml

常用指令

轉錄檔案

sona transcribe ./sample.mp4 \
  --config ./sona-cli.toml \
  --output ./sample.srt

不指定 --output 時，轉錄結果會以 JSON 寫入 stdout。指定 --output 時，格式會從副檔名推斷，除非同時傳入 --format。已有輸出檔案預設受保護；只有明確傳入 --force 時才會覆寫。

轉錄目錄

sona transcribe \
  --input-dir ./media \
  --output-dir ./transcripts \
  --format srt \
  --recursive \
  --jobs 1 \
  --config ./sona-cli.toml

目錄模式會為每個受支援媒體檔案在 --output-dir 中寫出一個轉錄檔案。預設只掃描目錄直屬檔案；加入 --recursive 後會包含子目錄，並保留相對輸出路徑。轉錄正文寫入檔案，stdout 會輸出 JSON 成功/失敗彙總。

也可以傳入多個輸入檔案或 glob 萬用模式。它們會使用與目錄模式相同的批次輸出規劃，並要求傳入 --output-dir：

sona transcribe ./media/*.wav ./media/interview.mp4 --output-dir ./transcripts --format srt

列出、下載或刪除模型

sona models list --mode offline --type whisper
sona models list --language zh --installed
sona models list --json
sona models download sherpa-onnx-whisper-turbo
sona models delete sherpa-onnx-whisper-turbo

models list 預設輸出便於閱讀的表格。腳本需要完整機器可讀結構時使用 --json，其中仍包含 install_path。 當所選預設模型需要伴生模型時，models download 會自動下載所需模型，例如 silero-vad 或預設標點模型。 models delete 只會刪除指定模型，不會自動刪除伴生模型。

啟動 API 服務

sona serve --host 127.0.0.1 --port 14200 --api-key your_secure_key

HTTP API 端點和請求範例請參閱 HTTP API 指南。

設定檔

透過 --config 傳入 TOML 檔案。命令列參數會覆寫設定檔中的值。

最小 transcribe 範例：

models_dir = "C:/Users/you/AppData/Local/com.asoda.sona/models"
model_id = "sherpa-onnx-whisper-turbo"
vad_model_id = "silero-vad"
language = "auto"
threads = 4
enable_itn = false
vad_buffer_size = 5.0
gpu_acceleration = "auto"
hotwords = "Sona,offline ASR"
format = "srt"
quiet = false
jobs = 1

transcribe 設定鍵

參數 / 設定鍵必要性取值範圍預設值說明
models_dir可選檔案系統路徑可推斷時使用桌面應用模型目錄CLI 找不到桌面模型目錄時請明確傳入。
model_id必選，除非傳入 --model-id離線預設模型 ID無用 sona models list --mode offline 檢視可用 ID。
vad_model_id可選預設模型 ID需要時為 silero-vad所選模型需要 VAD 時使用；可覆寫預設伴生模型。
punctuation_model_id可選預設模型 ID需要時為 sherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8所選模型需要標點時使用；可覆寫預設伴生模型。
language可選auto 或模型語言代碼，如 zh、en、jaauto覆寫自動語言偵測。
threads可選大於 0 的整數4辨識執行緒數。
enable_itn可選true 或 falsefalse啟用逆文字歸一化。
hotwords可選逗號分隔片語無自訂 ASR 熱詞；目前支援 Transducer 和 Qwen3 模型。
quiet可選true 或 falsefalse設為 true 時隱藏轉錄進度；CLI --quiet 也會啟用。
jobs可選大於 0 的整數1目錄、多輸入或 glob 模式下最大併發檔案任務數；CLI --jobs 會覆寫。
vad_buffer_size可選大於 0 的數字5.0VAD 緩衝秒數。
gpu_acceleration可選auto、cpu、cuda、coreml、directmlauto使用 cpu 可明確關閉 GPU 加速。
format可選json、txt、srt、vtt、md寫入 stdout 或目錄模式時為 json，否則從 --output 推斷覆寫輸出副檔名推斷。

serve 設定鍵

參數 / 設定鍵必要性取值範圍預設值說明
host可選監聽地址0.0.0.0本機存取可用 127.0.0.1。
port可選TCP 連接埠 0 到 6553514200API 服務連接埠。
api_key可選字串空為空時請求不需要 Bearer 認證。
models_dir可選檔案系統路徑可推斷時使用桌面應用模型目錄用於解析已安裝模型。
ip_whitelist可選逗號分隔規則localhost支援 localhost、精確 IP、CIDR、*，以及 192.168.* 這類 IPv4 萬用字元。
max_streaming可選非負整數2最大併發流式 WebSocket 連線數。
max_concurrent可選非負整數2最大併發批次任務數。
max_queue_size可選非負整數1000 表示佇列基本不限。
max_upload_size_mb可選非負整數500 表示關閉上傳大小限制。
job_ttl_minutes可選非負整數600 表示關閉完成/失敗任務清理。
gpu_acceleration可選auto、cpu、cuda、coreml、directmlauto本機批次和流式任務的服務級預設值。
vad_model_id可選預設模型 IDsilero-vadAPI 服務任務的預設 VAD 伴生模型。
punctuation_model_id可選預設模型 IDsherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8API 服務任務的預設標點伴生模型。

參數

全域

sona
  -V, --version
  -v, --verbose
  -h, --help
  help

使用 -V 或 --version 列印 Sona 版本號。使用 -v 或 --verbose 放在子指令前啟用詳細診斷日誌。使用 -h、--help 或 help 列印指令說明：

sona --version
sona -V
sona -v models list
sona --verbose transcribe ./sample.mp4 --config ./sona-cli.toml
sona transcribe --help

詳細診斷日誌會寫入 stderr。指令結果仍寫入 stdout，包括 models list 的表格或 JSON 輸出，以及 transcribe 未指定 --output 時的輸出，因此仍可安全透過管線傳給其他工具。

進階包裝腳本和測試可以設定 SONA_FORCE_CLI=1，即使可執行檔啟動時沒有識別到 CLI 子指令，也強制進入 CLI 模式。

使用 sona completions <shell> 產生 shell 補全腳本。支援 bash、zsh、fish、powershell 和 elvish；腳本會寫入 stdout。

transcribe

參數 / 設定鍵必要性取值範圍預設值說明
<input>...必選，除非傳入 --input-dir本機音訊/影片檔案路徑或 glob 萬用模式無單一輸入保持單檔模式；多個輸入或 glob 模式會進入批次模式並要求 --output-dir。
--input-dir <dir>目錄模式必選目錄路徑無轉錄目錄中的受支援媒體檔案。
--config <path>可選TOML 檔案路徑無從設定檔載入預設值。
--output <path>可選檔案系統路徑stdout僅用於單檔模式。檔案已存在時會報錯，除非傳入 --force。
--output-dir <dir>與 --input-dir、多個輸入或 glob 同用時必選目錄路徑無為每個輸入檔案寫出一個轉錄檔案。計劃輸出已存在時會報錯，除非傳入 --force。
--recursive可選旗標關閉掃描子目錄並保留相對輸出路徑。
--jobs <n>可選大於 0 的整數jobs 設定或 1批次模式下最大併發檔案任務數。
--format <format>可選json、txt、srt、vtt、md寫入 stdout 或目錄模式時為 json，否則從 --output 推斷覆寫設定和輸出副檔名推斷。
--language <code>可選auto 或模型語言代碼auto覆寫設定。
--model-id <id>必選，除非設定了 model_id離線預設模型 ID無主轉錄模型。
--models-dir <path>可選檔案系統路徑可推斷時使用桌面應用模型目錄覆寫設定。
--vad-model-id <id>可選預設模型 ID需要時為 silero-vad覆寫預設 VAD 伴生模型。
--punctuation-model-id <id>可選預設模型 ID需要時為 sherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8覆寫預設標點伴生模型。
--threads <n>可選大於 0 的整數4覆寫設定。
--enable-itn可選旗標false與 --disable-itn 互斥。
--disable-itn可選旗標false覆寫 enable_itn = true；與 --enable-itn 互斥。
--hotwords <words>可選逗號分隔片語無覆寫 hotwords；目前支援 Transducer 和 Qwen3 模型。
--gpu-acceleration <provider>可選auto、cpu、cuda、coreml、directmlauto覆寫設定。
--vad-buffer <seconds>可選大於 0 的數字5.0vad_buffer_size 的 CLI 參數名。
--save-wav <path>可選檔案系統路徑無僅 CLI 參數；儲存中間重取樣 WAV。與 --input-dir 不相容。
--quiet可選旗標關閉隱藏轉錄進度，並覆寫 quiet = false。
--force可選旗標關閉允許覆寫已有輸出檔案。批次模式中規劃出的重複輸出仍會失敗。

models list

參數 / 設定鍵必要性取值範圍預設值說明
--models-dir <path>可選檔案系統路徑可推斷時使用桌面應用模型目錄用於偵測已安裝預設模型。
--mode <mode>可選streaming、offline所有模式按支援模式過濾。
--type <type>可選預設模型類型，如 whisper、vad、punctuation所有類型按模型類型過濾。
--language <code>可選語言代碼，如 zh、en、ja、yue所有語言依支援的語言代碼過濾。
--installed可選旗標關閉只顯示 models_dir 中已存在的模型。
--json可選旗標關閉輸出機器可讀 JSON，而不是預設表格。
輸出總是表格或 JSON表格寫入 stdout。

models download

參數 / 設定鍵必要性取值範圍預設值說明
<model_id>必選已知預設模型 ID無要下載的主模型。
--models-dir <path>可選檔案系統路徑可推斷時使用桌面應用模型目錄目標模型目錄。
--quiet可選旗標關閉隱藏單個下載進度。
伴生模型下載自動所需 VAD 和標點預設模型自動下載主模型時會同時下載必需伴生模型。

models delete

參數 / 設定鍵必要性取值範圍預設值說明
<model_id>必選已知預設模型 ID無要刪除的模型。
--models-dir <path>可選檔案系統路徑可推斷時使用桌面應用模型目錄目標模型目錄。
--yes可選旗標關閉跳過互動確認提示。
安裝路徑缺失否已知但未安裝的預設模型成功 no-op向 stderr 輸出提示並以狀態碼 0 退出。
伴生模型刪除否所需 VAD 和標點預設模型不刪除如果不再需要伴生模型，請明確刪除對應模型。

serve

參數 / 設定鍵必要性取值範圍預設值說明
--config <path>可選TOML 檔案路徑無從設定檔載入預設值。
--host <ip>可選監聽地址0.0.0.0覆寫設定。
--port <port>可選TCP 連接埠 0 到 6553514200覆寫設定。
--api-key <key>可選字串空為空時不啟用 Bearer 認證。
--models-dir <path>可選檔案系統路徑可推斷時使用桌面應用模型目錄覆寫設定。
--ip-whitelist <rules>可選逗號分隔規則localhost支援 localhost、精確 IP、CIDR、*，以及 192.168.* 這類 IPv4 萬用字元。
--max-streaming <n>可選非負整數2最大併發流式連線數。
--max-concurrent <n>可選非負整數2最大併發批次任務數。
--max-queue-size <n>可選非負整數1000 表示佇列基本不限。
--max-upload-size-mb <n>可選非負整數500 表示關閉上傳大小限制。
--job-ttl-minutes <n>可選非負整數600 表示關閉完成/失敗任務清理。
--gpu-acceleration <provider>可選auto、cpu、cuda、coreml、directmlautoHTTP API 請求不支援依個別請求覆寫 GPU 設定。
--vad-model-id <id>可選預設模型 IDsilero-vadAPI 服務任務的預設 VAD 伴生模型。
--punctuation-model-id <id>可選預設模型 IDsherpa-onnx-punct-ct-transformer-zh-en-vocab272727-2024-04-12-int8API 服務任務的預設標點伴生模型。

執行 sona <command> --help 可檢視 clap 產生的完整幫助文字。

上一頁

進階詞彙設定

下一頁

HTTP API 參考