CLI ガイド

Sona は、デスクトップアプリの実行ファイルを通じて、オフライン文字起こし用の CLI コマンドを提供しています。パッケージ版インストーラーでインストールした場合、sona がシェルの PATH に自動追加されないことがあるため、インストール済みアプリのバイナリを直接指定して CLI サブコマンドを実行してください。ソースからビルドする場合は、Cargo から同じコマンドを実行できます。

CLI の範囲は意図的に絞られています。現在含まれるのは、単一ファイルとディレクトリのオフライン文字起こし、プリセットモデルの一覧表示 / ダウンロード / 削除、ヘッドレス HTTP API サーバー起動です。Live Record、LLM Polish、Translate は CLI には含まれません。

実行方法

• 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 は既定で読みやすい表形式で出力します。install_path を含む完全な機械可読形式が必要なスクリプトでは --json を使ってください。 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 の設定キー

serve の設定キー

パラメータ

グローバル

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

Sona のバージョンを表示するには -V または --version を使います。詳しい診断ログを出すには、サブコマンドの前に -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）に出力されます。models list の表または JSON 出力や、--output を付けない transcribe の JSON 出力など、コマンド本体の結果は標準出力（stdout）に出るため、他のツールへパイプできます。

高度なラッパーやテストでは、SONA_FORCE_CLI=1 を設定すると、認識済みの CLI サブコマンドなしで実行ファイルが起動された場合でも CLI モードを強制できます。

shell 補完スクリプトは sona completions <shell> で生成できます。対応シェルは bash、zsh、fish、powershell、elvish で、スクリプトは stdout に出力されます。

transcribe

models list

models download

models delete

serve

Clap が自動生成する詳細なヘルプを見るには、sona <command> --help を実行してください。

デスクトップアプリの通常のワークフローを使いたい場合は、はじめに または Batch Import に戻ってください。