fun-asr

Fun-ASR：音声の文字起こし

Alibaba Cloud DashScope の Fun-ASR 非リアルタイム音声認識モデルを使用して、音声ファイルを文字起こしします。話者ダイアライゼーション、多言語認識、複数の出力形式（プレーンテキスト、JSON、SRT 字幕）に対応しています。

ワークフロー

Audio → S3 → Fun-ASR async → Poll → Save file → Agent reads

要件

環境変数

これらの変数は、~/.wmyskills/.env（スキル間で共有）または scripts/.env（こちらが優先）に設定してください。テンプレートとして scripts/.env.example を使用してください。変数を ~/.wmyskills/.env に追加するときは、既存のファイルを上書きしないでください。

変数	必須	説明
DASHSCOPE_API_KEY	はい	Alibaba Cloud DashScope API キー（または BAILIAN_APIKEY を使用）
BAILIAN_APIKEY	はい*	DASHSCOPE_API_KEY の代替（Bailian/DashScope）
S3_ENDPOINT	はい	S3 互換ストレージのエンドポイント URL
S3_BUCKET	はい	音声アップロード用の S3 バケット名
S3_REGION	いいえ	S3 リージョン（デフォルト：us-east-1）
S3_PREFIX	いいえ	アップロード用のキー接頭辞（デフォルト：asr-uploads）
AWS_ACCESS_KEY_ID	いいえ*	AWS アクセスキー（IAM／デフォルトの認証情報チェーンを使用しない場合に必要）
AWS_SECRET_ACCESS_KEY	いいえ*	AWS シークレットキー（IAM／デフォルトの認証情報チェーンを使用しない場合に必要）

スクリプトは ~/.wmyskills/.env と scripts/.env から .env を自動的に読み込みます（スクリプトのディレクトリが優先されます）。

Python の依存関係

pip install boto3 requests python-dotenv

オプション：ffmpeg

以下の処理には ffmpeg／ffprobe が必要です。

• 音声チャンネル数の検出
• マルチチャンネル音声のモノラルへの変換（話者ダイアライゼーションに必要）

ffmpeg がない場合、スクリプトはモノラルへの変換をスキップし、元のファイルを使用します。

使用方法

python fun_asr_cli.py <audio-file> [options]

script/ ディレクトリから実行するか、fun_asr_cli.py のフルパスを指定してください。

位置引数

引数	説明
file	音声ファイルのパス（aac、wav、mp3、m4a、flac、ogg など）

オプション

オプション	デフォルト	説明
--model	fun-asr	ASR モデル：fun-asr、paraformer-v2、paraformer-v1、fun-asr-mtl、paraformer-mtl-v1
--no-diarization	（有効）	話者ダイアライゼーションを無効にします
--language	zh	言語ヒント：zh、en、ja、ko、yue など
--channel-id	0	文字起こしする音声チャンネル（0 = 最初のチャンネル／モノラル）
--output	自動生成	出力ファイルのパスを指定します（デフォルト：~/.wmyskills/fun-asr/outputs/）
--format	text	出力形式：text、json、srt
--keep-s3	（オフ）	文字起こし後もアップロードしたファイルを S3 に保持します
--version	—	スクリプトのバージョンを表示して終了します

例

# Basic transcription (text format, Chinese)
python fun_asr_cli.py meeting.mp3

# JSON output with full metadata (timestamps, speaker IDs, confidence)
python fun_asr_cli.py interview.wav --format json

# SRT subtitle output
python fun_asr_cli.py lecture.mp3 --format srt

# Disable speaker diarization
python fun_asr_cli.py meeting.mp3 --no-diarization

# Specify language and model
python fun_asr_cli.py japanese_audio.mp3 --language ja --model paraformer-v2

# Custom output path
python fun_asr_cli.py audio.wav --output ~/Desktop/transcript.txt

出力形式

text（デフォルト）

話者ラベルとタイムスタンプを含むプレーンテキストです。形式は [Speaker N] HH:MM:SS - HH:MM:SS に続けてテキストが表示されます。

json

タイムスタンプ、話者 ID、信頼度スコア、API の生のレスポンスなど、すべてのメタデータを含む JSON です。

srt

標準の SRT 字幕形式です：NN \n HH:MM:SS,mmm --> HH:MM:SS,mmm \n [SN] text。

実行ルール

ユーザーが要求したコマンドを、依存関係、環境変数、設定を事前に確認せず、そのまま実行してください。問題がある場合は、スクリプトが明確なエラーを出して失敗します。その場合に限り、確認して修正してください。

エージェントへの指示

文字起こしの完了後

文字起こしの出力はファイルに保存されます。テキストの内容は標準出力には表示されません。標準出力に表示されるのは、結果ファイルの保存先を示す Output file: <path> の1行だけです。デフォルトの出力ディレクトリは ~/.wmyskills/fun-asr/outputs/ です。

文字起こしが成功すると、標準出力には Output file: <path> のみが出力されます。情報ログとエラーログは標準エラー出力に送られます。

成功した場合は、必ず結果をユーザーに提示してください。

1. 標準出力から Output file: のパスを解析します
2. ファイルの内容を読み取り、ユーザーに提示します
3. 音声の長さ、検出された話者数（ダイアライゼーションが有効な場合）、内容の簡潔な概要を含む短い要約を提示します

エラーのシナリオ

スクリプトは、プログラムで処理するための特定の終了コードを返します。

• コード 2 — 設定エラー：環境変数が不足しています。無効な引数（不明なフラグ、無効なモデル名など）に対して argparse が使用するコードでもあります。
• コード 3 — ファイルエラー：ファイルが見つからない、大きすぎる、または制限を超えています。
• コード 4 — API／ネットワークエラー：送信またはポーリングに失敗しました。
• コード 6 — タスク失敗：ASR API がエラーを返しました。エラーメッセージを確認してください。
• コード 7 — タイムアウト：文字起こしに 30 分以上かかりました。

重要なルール

• 有効な音声が検出されない場合：API が ASR_RESPONSE_HAVE_NO_WORDS または SUCCESS_WITH_NO_VALID_FRAGMENT を返した場合、音声には検出可能な人間の発話が含まれていません（無音、小さすぎる音量、または純粋なノイズ）。**直ちに停止し、その旨をユーザーに報告してください。自動的に再試行したり、モデルを切り替えたり、音声パラメーターを変更したりしないでください。**再試行するのは、ユーザーから明示的に依頼された場合のみです。
• 話者ダイアライゼーションには、2 時間以下のモノラル音声が必要です。スクリプトは ffmpeg を使ってマルチチャンネル音声を自動変換します。ファイルが 2 時間を超える場合、ダイアライゼーションは自動的に無効になります。
• ダイアライゼーションの料金：スクリプトはダイアライゼーションの有無にかかわらず、音声の秒数に応じて課金します。有効にしても追加料金はかかりません。
• S3 のクリーンアップ：一時ファイルは、--keep-s3 を指定しない限り、文字起こしの完了後に S3 から自動的に削除されます。
• 料金：Fun-ASR の料金は、音声 1 秒あたり CNY 0.00022 です。スクリプトは開始前に料金を見積もり、完了時に実際の料金を報告します。