cURL とオープンソースツールによる音声エンコーディング
cURL で音声をダウンロードし、FFmpeg でエンコードします。このチュートリアルでは、実際の MP3 サンプルからローカルの M4A ファイルを作成し、そのワークフローを AAC、M4A、MP3、Opus 出力用の Bash スクリプトにまとめます。結果のアップロードには独自の API 仕様を持つ受信側が必要なため、この例では扱いません。
環境のセットアップ
Linux を使用し、PATH に Bash、cURL、FFmpeg、ffprobe を用意してください。FFmpeg のビルドには aac、libmp3lame、libopus エンコーダーが必要です。ディストリビューションで保守されているパッケージをインストールしてください。FFmpeg のダウンロードページにパッケージ提供元へのリンクがあります。これらの例は Bash 5.3.15、cURL 8.22.0、FFmpeg/ffprobe 9.0.1 でテスト済みです。また、FFmpeg/ffprobe 6.1.1 でも別途実行して互換性を確認しています。これはテストに使用したバージョンの情報であり、古いパッチリリースのインストールを推奨するものではありません。
インストール済みのツールとエンコーダーを確認します。
bash --version &&
curl --version &&
ffmpeg -version &&
ffprobe -version &&
ffmpeg -hide_banner -encoders
入力には、暗号化されていない、欠落のない 44.1 kHz または 48 kHz のモノラルまたはステレオ録音を使用してください。これらの例は、整数および浮動小数点サンプルを含む MP3 と PCM WAV の入力を対象としています。サラウンドのチャンネルマッピングは定義せず、サンプルレートも強制しません。出力コーデックで必要な場合、FFmpeg がリサンプリングすることがあります。処理する権限のある音声を使用してください。
FFmpeg と cURL による基本的な音声エンコーディング
audio-example がまだ存在しないディレクトリで、次のコードを Bash に貼り付けてください。MDN Web Audio のサンプルから
viper.mp3 をダウンロードし、最初の音声ストリームを AAC にエンコードして
M4A コンテナに格納します。参照先を固定したこのサンプルには、44.1 kHz のステレオ音声が約 41 秒収録されています。
(
set -euo pipefail
mkdir -- audio-example || exit 1
trap 'status=$?; if [ "$status" -ne 0 ]; then
rm -f -- audio-example/input.mp3 audio-example/output.m4a audio-example/ffmpeg-errors.log
rmdir -- audio-example 2>/dev/null || true
fi' EXIT
curl -fsSL --retry 3 --connect-timeout 10 --max-time 60 \
--proto '=https' --proto-redir '=https' \
-o audio-example/input.mp3 \
https://raw.githubusercontent.com/mdn/webaudio-examples/5af6b7a1545ad572c2dd2ce0443eeb26ab7c3e61/audio-analyser/viper.mp3 || exit 1
if ! ffmpeg -nostdin -v error -n -xerror -i audio-example/input.mp3 -map 0:a:0 \
-c:a aac -b:a 192k -f ipod audio-example/output.m4a \
2>audio-example/ffmpeg-errors.log || [ -s audio-example/ffmpeg-errors.log ]; then
cat -- audio-example/ffmpeg-errors.log >&2
exit 1
fi
rm -f -- audio-example/ffmpeg-errors.log
)
成功すると、audio-example にダウンロードした MP3 と
output.m4a が格納されます。ダウンロードまたはエンコードに失敗すると、今回の実行で作成したファイルを削除します。ディレクトリがすでに存在する場合は、何も書き込まずに停止します。丸括弧によってシェルオプションの適用範囲をサブシェル内に限定しているため、貼り付けても作業中のシェルの設定は変わりません。この例は、管理下にあるディレクトリで、並列ではなく順番に実行してください。
-map 0:a:0 オプションは最初の音声ストリームを選択します。-n は既存の出力の置き換えを拒否し、-nostdin は対話入力を無効にします。ビットレートはエンコーダーの目標値であり、ファイルサイズや知覚品質を保証するものではありません。MP3 を再エンコードしても、元の圧縮ですでに失われた細部は復元できません。
音声エンコーディングスクリプトの作成
次のコードを現在のディレクトリに encode_audio.sh として保存してください。形式の引数は、エンコーダーとコンテナの両方を選択します。ファイル名の拡張子を変えるだけでは音声は変換されません。各マルチプレクサーについては、FFmpeg の形式ドキュメントで説明されています。
| 引数 | 音声コーデック | コンテナ | 出力ファイル名 |
|---|---|---|---|
aac | AAC | ADTS | output.aac |
m4a | AAC | MPEG-4 audio | output.m4a |
mp3 | libmp3lame による MP3 | MP3 | output.mp3 |
opus | libopus による Opus | Ogg | output.opus |
#!/bin/bash
set -euo pipefail
if [ "$#" -ne 3 ]; then
echo "Usage: $0 <input_url> <output_format> <output_bitrate>" >&2
exit 1
fi
INPUT_URL=$1
OUTPUT_FORMAT=$2
BITRATE=$3
case "$OUTPUT_FORMAT" in
aac) CODEC=aac; CONTAINER=adts ;;
m4a) CODEC=aac; CONTAINER=ipod ;;
mp3) CODEC=libmp3lame; CONTAINER=mp3 ;;
opus) CODEC=libopus; CONTAINER=ogg ;;
*) echo "Unsupported output format: $OUTPUT_FORMAT" >&2; exit 1 ;;
esac
if [[ ! "$BITRATE" =~ ^[1-9][0-9]*k$ ]]; then
echo "Bitrate must be a positive integer followed by k, such as 192k" >&2
exit 1
fi
WORK_DIR=$(mktemp -d ./audio-encode.XXXXXX)
INPUT_FILE="$WORK_DIR/input.audio"
OUTPUT_FILE="$WORK_DIR/output.$OUTPUT_FORMAT"
ERROR_LOG="$WORK_DIR/ffmpeg-errors.log"
# Delete the download; retain the output only after successful encoding.
trap 'status=$?; rm -f -- "$INPUT_FILE" "$ERROR_LOG";
if [ "$status" -ne 0 ]; then rm -f -- "$OUTPUT_FILE"; fi
rmdir -- "$WORK_DIR" 2>/dev/null || true' EXIT
echo "Downloading input file…"
if ! curl -fsSL --retry 3 --connect-timeout 10 --max-time 60 \
--proto '=http,https' --proto-redir '=http,https' \
-o "$INPUT_FILE" -- "$INPUT_URL"; then
echo "Error: Failed to download input file" >&2
exit 1
fi
echo "Encoding to ${OUTPUT_FORMAT} format…"
if ! ffmpeg -nostdin -v error -n -xerror -i "$INPUT_FILE" -map 0:a:0 -vn \
-c:a "$CODEC" -b:a "$BITRATE" -f "$CONTAINER" "$OUTPUT_FILE" \
2>"$ERROR_LOG" || [ -s "$ERROR_LOG" ]; then
cat -- "$ERROR_LOG" >&2
echo "Error: Failed to encode audio" >&2
exit 1
fi
echo "Successfully encoded to: ${OUTPUT_FILE}"
保存したスクリプトを Bash で実行します。実行権限は不要です。
bash ./encode_audio.sh \
https://raw.githubusercontent.com/mdn/webaudio-examples/5af6b7a1545ad572c2dd2ce0443eeb26ab7c3e61/audio-analyser/viper.mp3 \
opus 128k
成功すると、./audio-encode.A1b2C3/output.opus のようなパスが出力されます。実行するたびに新しい作業ディレクトリを作成するため、同じ URL で再実行しても以前の結果は保持されます。スクリプトはダウンロードしたファイルを削除します。また、ダウンロードまたはエンコードに失敗した場合は、不完全な出力と空の作業ディレクトリも削除します。引数エラーはファイルの作成前に発生します。このクリーンアップは通常のコマンドの失敗を対象としています。プロセスの強制終了やマシンのシャットダウンでは、一時ファイルが残ることがあります。
128k は、毎秒 128,000 ビットを目標とする指定です。スクリプトは引数の表記を検証しますが、そのビットレートをサポートするかどうかは、選択したエンコーダーが判断します。エンコード前にダウンロードを完了するため、FFmpeg は入力ファイル内をシークできます。
音声ファイルのバッチ処理
次のコードを batch_encode.sh として、encode_audio.sh と同じディレクトリに保存し、そのディレクトリから実行してください。入力リストの各行には、URL、形式、ビットレートをスペースで区切って指定します。空行はスキップします。URL 内のスペースはパーセントエンコードしてください。コメントや追加のフィールドはサポートしていません。
#!/bin/bash
set -euo pipefail
if [ "$#" -ne 1 ]; then
echo "Usage: $0 <input_file_list.txt>" >&2
echo "File list format: <input_url> <output_format> <bitrate>" >&2
exit 1
fi
INPUT_LIST=$1
failed=0
while IFS=' ' read -r url format bitrate extra || [[ -n "$url" ]]; do
[[ -z "$url" ]] && continue
echo "Processing: ${url}"
if [[ -n "$extra" || -z "$format" || -z "$bitrate" ]]; then
echo "Invalid list entry: $url" >&2
failed=1
elif bash ./encode_audio.sh "$url" "$format" "$bitrate"; then
echo "Success: ${url}"
else
echo "Failed: ${url}" >&2
failed=1
fi
done < "${INPUT_LIST}" || exit $?
exit "$failed"
たとえば、次の二行を audio-list.txt として保存します。
https://raw.githubusercontent.com/mdn/webaudio-examples/5af6b7a1545ad572c2dd2ce0443eeb26ab7c3e61/audio-analyser/viper.mp3 m4a 192k
https://raw.githubusercontent.com/mdn/webaudio-examples/5af6b7a1545ad572c2dd2ce0443eeb26ab7c3e61/audio-analyser/viper.mp3 mp3 128k
bash ./batch_encode.sh audio-list.txt
バッチは順次実行され、ある行の処理が失敗しても、成功した出力は保持されます。無効な項目、ダウンロードの失敗、エンコードの失敗があっても処理を続け、いずれかの処理が失敗した場合は終了ステータス 1 で終了します。ステータス 0 は、処理したすべての行が成功したことを示します。空のリストでは何も処理しません。
セキュリティ上の注意点
信頼できる提供元の HTTPS URL を使用してください。cURL はデフォルトでサーバー証明書を検証します。この検証を回避するために -k を追加しないでください。スクリプトの
--proto と --proto-redir による制限は、リダイレクト先を含め、HTTP と HTTPS のみを許可します。ローカルのテストサーバー向けに HTTP も使用できますが、通信は暗号化されません。
これらのスクリプトはローカルでの変換例です。FFmpeg をサンドボックス化せず、ダウンロードサイズも制限しません。また、ユーザーが指定した任意の URL をサーバーが安全に取得できるようにするものでもありません。cURL のタイムアウトは転送の試行ごとに時間を制限しますが、再試行によってダウンロード全体の所要時間は長くなることがあります。入力と出力の全体を保存できるよう、十分なディスク容量を確保してください。
エラー処理と検証
基本例を実行したディレクトリで、次のコードを使って実際の出力を確認してください。
(
set -euo pipefail
VERIFY_LOG=$(mktemp ./audio-verify.XXXXXX)
trap 'rm -f -- "$VERIFY_LOG"' EXIT
ffprobe -v error -select_streams a:0 \
-show_entries stream=codec_name,sample_rate,channels:format=format_name,duration \
-of json audio-example/output.m4a || exit 1
if ! ffmpeg -nostdin -v error -xerror -i audio-example/output.m4a \
-map 0:a:0 -f null - 2>"$VERIFY_LOG" || [ -s "$VERIFY_LOG" ]; then
cat -- "$VERIFY_LOG" >&2
exit 1
fi
)
codec_name が aac、チャンネル数が二つ、長さが約 41 秒であることを確認します。ffprobe は M4A コンテナを mov,mp4,m4a,3gp,3g2,mj2 系列の一種として報告します。二つ目のコマンドは、別のファイルを保存せずに出力全体をデコードします。スクリプトの結果を確認する場合は、両方のコマンドで、その実行時に表示された正確なパスに置き換えてください。生の ADTS AAC にはエンコーダー遅延とパディングが含まれ、ffprobe はビットレートから長さを推定することがあります。その推定値を正確な長さとして扱わず、デコードした音声を元のタイムラインと照合してください。
-xerrorは、エラー時に停止するよう FFmpeg に要求します。FFmpeg 6.1.1 は、デコードの終盤でエラーを報告してもステータス 0 を返すことがあります。そのため、これらのコードでは error ログレベルの標準エラー出力も取得し、エラーログが空でなければ失敗として扱い、クリーンアップ前に診断情報を表示します。これで報告されたエラーは検出できますが、完全性の証明にはなりません。デコード可能な境界で途切れた録音でもエンコードやデコードに成功することがあり、破損したパケットの一部が通知なく破棄されることもあります。完全であるとわかっているソースと長さを比較し、最後まで聴いて確認してください。信頼できる配信元のチェックサムがあれば、それを使用してください。ファイルの存在、読み取り可能なヘッダー、終了ステータスがゼロであることだけでは、想定した音声がすべて取得できたとは確認できません。
404 などの cURL の HTTP エラーが発生すると、エンコード前にダウンロードが停止します。エンコーダーが利用できない場合、ファイルに音声ストリームがない場合、指定のビットレートをエンコーダーが拒否した場合は、変換が停止します。失敗を調査する際は、標準エラー出力の診断情報を保持してください。バッチがステータス 1 で終了した場合は、行ごとのメッセージで失敗を特定してください。完了済みの出力は引き続き利用できます。
まとめ
ホスト型のエンコーディングワークフローについては、🤖 /audio/encode の Robot ドキュメントを参照してください。そのアップロードと認証の仕様は、ここで紹介したローカルの cURL によるダウンロードと FFmpeg による変換とは別のものです。
