cURL とオープンソースによる音声言語の自動検出
whisper.cpp でローカルに提供する多言語 Whisper モデルを使い、音声から直接言語を検出します。cURL で録音を HTTP エンドポイントに送信すると、言語の候補と、録音との照合に使える文字起こしが返されます。ソフトウェアとモデルをダウンロードすれば、アカウントやクラウド API なしで、手元のコンピューター上で推論を実行できます。
システム要件
Linux 環境で Bash、POSIX シェル(sh)、C++17 コンパイラー、Make、CMake、cURL、FFmpeg、Python 3、および一般的な tar、gzip、dirname、grep、mktemp、rm コマンドを使用します。不足しているツールは、最初にディストリビューションのパッケージマネージャーでインストールしてください。Python は標準ライブラリだけで JSON レスポンスを読み取ります。
この CPU 向けの手順では whisper.cpp を v1.8.7 に固定し、Bash 5.2、GCC 14.2、Make 4.4、CMake 3.31、cURL 8.14、FFmpeg 7.1、Python 3.12 を備えた
Debian 13 環境を対象とします。ほかのプラットフォームや古いツールチェーンは対象外です。多言語モデル tiny はディスク上で約 75 MiB を使用します。ソースとビルド用に追加のディスク容量を、推論用に数百メガバイトの空きメモリーを確保してください。
インストール
新しい作業ディレクトリで、固定したリリースをダウンロードし、サーバーをビルドして、多言語モデルをダウンロードします。英語専用の tiny.en モデルではなく、tiny を選択してください。丸括弧は、シェルオプションとディレクトリ変更をサブシェル内に限定します。
(
set -e
for tool in curl tar gzip cmake make c++ ffmpeg python3 sh dirname grep mktemp rm; do
command -v "$tool" >/dev/null || { printf 'Missing tool: %s\n' "$tool" >&2; exit 1; }
done
if [ -e whisper-v1.8.7.tar.gz ] || [ -e whisper.cpp-1.8.7 ]; then
printf 'Use a fresh directory; existing download or source found.\n' >&2
exit 1
fi
curl -q --fail --location --output whisper-v1.8.7.tar.gz \
https://github.com/ggml-org/whisper.cpp/archive/refs/tags/v1.8.7.tar.gz
tar -xzf whisper-v1.8.7.tar.gz
cd whisper.cpp-1.8.7
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
-DGGML_METAL=OFF -DWHISPER_BUILD_SERVER=ON
cmake --build build --config Release --target whisper-server -j 4
sh ./models/download-ggml-model.sh tiny
)
文字起こしサーバーの設定
インストールが成功したら、同じ作業ディレクトリから HTTP サーバーを起動します。
(
cd whisper.cpp-1.8.7 &&
./build/bin/whisper-server --model models/ggml-tiny.bin \
--host 127.0.0.1 --port 8080 --language auto --no-gpu
)
待ち受け開始のメッセージが表示されるまで待ち、このターミナルは開いたままにします。このサンプルサーバーには認証がないため、バインド先はループバックのままにし、信頼できるローカルの録音を使ってください。作業が終わったら Ctrl+C で停止します。
cURL による音声の文字起こし
別のターミナルで、input.mp3 という名前の発話録音を含むディレクトリで作業します。単一言語の明瞭な発話で始まる、信頼できる抜粋を使ってください。これをモノラル、16 kHz、16 ビット PCM WAV に変換します。このブロックは変換前に既存の audio.wav を検出すると処理を拒否し、-n も FFmpeg による上書きを防ぎます。録音ごとに新しいディレクトリを選んでください。FFmpeg 7.1 は上書きの拒否を報告しても終了ステータスとしてゼロを返すことがあるため、明示的な確認が重要です。
(
if [ -e audio.wav ]; then
printf 'Existing audio.wav; use a fresh directory.\n' >&2
exit 1
fi
ffmpeg -nostdin -n -i input.mp3 -vn -ar 16000 -ac 1 -c:a pcm_s16le audio.wav
)
アップロード前に audio.wav を再生し、意図した発話が含まれることを確認してください。FFmpeg は破損した録音の一部を復元し、成功を返すことがあります。変換できただけでは、入力が破損していなかったとは判断できません。
言語の検出
以下を read_language.py として audio.wav と同じディレクトリに保存します。音声から推定された言語を読み取り、確認用に文字起こしを出力するスクリプトです。空のテキストと、括弧で囲まれた非発話マーカーだけで構成されたテキストを拒否します。[BLANK_AUDIO] が繰り返される結果も対象です。
import json
import re
import sys
def read_language(path):
with open(path, encoding="utf-8") as handle:
data = json.load(handle)
if not isinstance(data, dict):
raise ValueError("Expected a JSON object")
language = data.get("language")
text = data.get("text")
if not isinstance(language, str) or not language.strip():
raise ValueError("Response has no detected language")
if not isinstance(text, str) or not re.sub(r"\[[^\]]*\]", "", text).strip():
raise ValueError("No speech transcript; language result is inconclusive")
return language.strip(), " ".join(text.split())
def main():
if len(sys.argv) != 2:
raise ValueError("Usage: python3 read_language.py response.json")
language, text = read_language(sys.argv[1])
print(f"Language candidate: {language}")
print(f"Transcript: {text}")
if __name__ == "__main__":
try:
main()
except (OSError, ValueError) as error:
print(f"Cannot read language result: {error}", file=sys.stderr)
sys.exit(1)
変換が成功し、読み取りスクリプトを保存したら、次のリクエストブロックを貼り付けます。リクエストごとに専用の一時レスポンスファイルを作成し、cURL が成功した場合だけ読み取ります。失敗した場合も含め、ブロックの終了時にファイルを削除するため、以前のレスポンスが今回のリクエストの結果になることはありません。リクエストの制限時間は、アップロードと推論を含めて合計 60 秒です。CPU がビジー状態の場合や録音が長い場合は、この時間を超えることがあります。必要に応じて、意図的に制限時間を延ばしてください。
(
set -e
response=$(mktemp ./language-response.XXXXXX)
trap 'rm -f "$response"' EXIT
curl -q --fail --silent --show-error --max-time 60 \
http://127.0.0.1:8080/inference \
--form 'file=@audio.wav;type=audio/wav' \
--form 'language=auto' \
--form 'response_format=verbose_json' \
--form 'no_language_probabilities=true' \
--output "$response" &&
python3 read_language.py "$response"
)
language=auto は言語検出を要求します。サーバーの
verbose_json レスポンスには
language と text が含まれますが、通常の json には言語が含まれません。翻訳は無効になっており、no_language_probabilities=true は任意の追加検出処理をスキップします。
英語の発話では Language candidate: english が想定されます。スペイン語の場合、サーバーが使う名前は spanish です。これらは ISO コードではなく言語名です。出力された文字起こしを、実際に聞こえる内容と比較してください。マーカーの確認は、あくまで簡易的な妥当性確認です。Whisper は実際にはない単語を生成することがあり、文字起こしが空でなくても、発話の存在や言語の正しさを確認できたことにはなりません。
パフォーマンスの最適化
読み込み済みのモデルを再利用できるよう、リクエスト間もサーバーを起動したままにしてください。tiny はローカルでの実験用ダウンロードを小さく抑えますが、文字起こしに大きな誤りが含まれることがあります。言語候補を使ってほかの処理を振り分ける前に、内容が既知の録音で確認してください。
このバージョンでは、自動言語検出はオフセットゼロから始まり、録音の冒頭の約 30 秒を使用します。後続の各区間を再分類するわけではありません。そのため、冒頭に長い無音があると、後で発話があっても誤解を招く言語が返されることがあります。発話で始まる抜粋を使い、言語が切り替わる場合は、抜粋を分けて評価してください。ファイル単位の単一の結果は、発話されたすべての言語を示すタイムラインではありません。
エラー処理
インストールが失敗した場合は、途中まで作成されたファイルを調べ、不足している前提要件を解消してから、新しい作業ディレクトリで再試行してください。既存のダウンロードと展開済みソースは、意図的に変更せず残します。変換が失敗した場合は、途中まで作成された audio.wav があれば、削除したり別のディレクトリを選んだりする前に確認してください。
cURL は HTTP エラー、接続失敗、タイムアウト時にゼロ以外の終了ステータスを返します。その場合、リクエストブロックは読み取りスクリプトを実行せず、一時レスポンスを削除します。正常に変換された audio.wav は保持し、失敗の原因を解消した後、リクエストブロックだけを再実行してください。無効な JSON、フィールドの欠落、空またはマーカーのみの文字起こし、読み取り不能なファイルがあると、読み取りスクリプトはステータス 1 で終了します。
起動が失敗した場合は、モデルのパスと、ポート 8080 がすでに使用中でないかを確認してください。アップロードが失敗した場合は、ローカルサーバーのターミナルを調べ、WAV 変換の成功を確認します。無音、音楽、非常に短い発話から推測された言語を、信頼できる分類として扱わないでください。
ファイル処理ワークフローでホスト型の文字起こしを利用する場合は、当社の Speech Robot を参照してください。
