Python で Pydub と FFmpeg を使って WAV 音声を MP3 にエンコード
録音ファイル単体や複数の WAV ファイルを、Python スクリプトで MP3 に変換します。このスクリプトは成功したファイルを報告し、変換がひとつでも失敗すると失敗の終了ステータスを返します。以下の例では Pydub と FFmpeg を使い、元のファイルを変更せず、既存の出力の上書きも拒否します。
この手順では、Linux 上の Bash と、ローカルにあるモノラルまたはステレオの WAV 録音を使います。出力はそれぞれ 192 kbps、44.1 kHz の MP3 で、チャンネル数は元のファイルと同じです。Pydub はデコードした音声をメモリに保持するため、RAM に収まる録音を使い、順番に処理してください。これはローカル変換用のスクリプトであり、アップロードサービスやストリーミングエンコーダーではありません。
環境の準備
この例は Linux 上の Python 3.14.7、Pydub 0.25.1、audioop-lts 0.2.2、FFmpeg 9.0.1 でテストしています。コマンドでは仮想環境を明示的に指定するため、有効化する必要はありません。
FFmpeg のインストール
仮想環境をサポートする Python、FFmpeg、ffprobe をインストールします。Ubuntu では次を実行します。
sudo apt-get update &&
sudo apt-get install -y python3 python3-venv ffmpeg
ほかの Linux ディストリビューションには、それぞれ専用のパッケージがあります。FFmpeg のダウンロードページに各ディストリビューションのパッケージへのリンクがあります。使用するビルドにエンコーダー libmp3lameが含まれることを確認してください。
ffmpeg -version &&
ffprobe -version &&
ffmpeg -hide_banner -encoders
エンコーダー一覧で libmp3lame を探してください。Pydub をインストールしても FFmpeg はインストールされません。
Pydub のインストール
親ディレクトリから新しいディレクトリを作成します。audio-encoding がすでに存在する場合は、別の名前を選んでください。&& による連結で、既存のプロジェクトにインストールする前にセットアップが停止します。
mkdir audio-encoding &&
cd audio-encoding &&
python3 -m venv .venv &&
.venv/bin/python -m pip install 'pydub==0.25.1' 'audioop-lts==0.2.2; python_version >= "3.13"'
以降のコマンドは、このシェルの作業ディレクトリを audio-encoding に保ったまま実行します。Python では3.13 で audioop が削除されましたが、Pydub 0.25.1 は引き続きこれをインポートします。条件付き依存関係により、Python 3.13 以降では
audioop-ltsがインストールされます。Python 3.12 では標準ライブラリのモジュールを使います。音声再生パッケージは不要です。
変換スクリプトの保存
以下のスクリプト全体を encode_audio.py として保存してください。WAV はコンテナであり、サンプルには整数値も浮動小数点値も格納できます。このスクリプトは、まず FFmpeg で符号付き 16 ビット PCM にデコードし、その既知の表現を Pydub に渡します。これにより、拡張 WAV のすべてのサンプル型を区別できない
Pydub 0.25.1 の WAV 高速処理経路に依存せずに済みます。この MP3 変換処理では、より高いビット深度も 16 ビットに減らすため、元の WAV をマスターとして保持してください。
MP3 は出力先と同じ親ディレクトリ内の一時ディレクトリでエンコードします。出力先がすでに存在すると失敗するハードリンクを使い、エンコードが完了したファイルだけを出力先に配置します。ハードリンクをサポートするローカルファイルシステムを使ってください。別の入力が失敗しても、変換に成功したファイルは残ります。
import argparse
import os
from pathlib import Path
import shutil
import subprocess
import sys
from tempfile import TemporaryDirectory
from pydub import AudioSegment
from pydub.exceptions import CouldntDecodeError, CouldntEncodeError
def convert_one(source, output_dir, ffmpeg, fade_ms):
if source.suffix.lower() != '.wav' or not source.is_file():
raise ValueError('Expected an existing WAV file')
destination = output_dir / (source.stem + '.mp3')
if os.path.lexists(destination):
raise FileExistsError(f'Output already exists: {destination}')
with TemporaryDirectory(prefix='.encode-', dir=output_dir) as work:
decoded = Path(work) / 'decoded.wav'
encoded = Path(work) / 'encoded.mp3'
subprocess.run(
[ffmpeg, '-nostdin', '-hide_banner', '-v', 'error', '-xerror',
'-f', 'wav', '-i', str(source.resolve(strict=True)),
'-map', '0:a:0', '-c:a', 'pcm_s16le', '-ar', '44100', str(decoded)],
check=True, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
)
audio = AudioSegment.from_wav(decoded)
if audio.channels not in (1, 2) or len(audio) == 0:
raise ValueError('Expected nonempty mono or stereo audio')
if fade_ms > len(audio):
raise ValueError('The fade must not exceed the recording length')
if fade_ms:
audio = audio.fade_in(fade_ms).fade_out(fade_ms)
audio.export(encoded, format='mp3', codec='libmp3lame', bitrate='192k').close()
os.link(encoded, destination)
return destination
def main():
parser = argparse.ArgumentParser(description='Convert WAV recordings to MP3')
parser.add_argument('--out-dir', type=Path, required=True)
parser.add_argument('--fade-ms', type=int, default=0)
parser.add_argument('inputs', type=Path, nargs='+')
args = parser.parse_args()
if args.fade_ms < 0:
parser.error('--fade-ms must be zero or greater')
ffmpeg = shutil.which('ffmpeg')
if ffmpeg is None:
parser.error('ffmpeg is missing from PATH')
AudioSegment.converter = ffmpeg
try:
output_dir = args.out_dir.resolve()
output_dir.mkdir(parents=True, exist_ok=True)
except OSError as error:
parser.exit(2, f'Cannot prepare output directory: {error}\n')
failed = 0
for source in args.inputs:
try:
destination = convert_one(source, output_dir, ffmpeg, args.fade_ms)
except (OSError, ValueError, subprocess.CalledProcessError,
CouldntDecodeError, CouldntEncodeError) as error:
failed += 1
print(f'FAILED {source}: {error}', file=sys.stderr)
else:
print(f'OK {source} -> {destination}')
print(f'{len(args.inputs) - failed} converted, {failed} failed')
return 1 if failed else 0
if __name__ == '__main__':
sys.exit(main())
FFmpeg のオプション -xerrorは、デコードエラーが報告された場合に変換を失敗させます。これにより、FFmpeg が通常なら部分的に復元する可能性のある破損した入力も検出します。ただし、すべての録音が完全であることの証明にはなりません。重要な出力は試聴し、想定した録音時間と長さを比較してください。
録音の変換
手元の input.wav を使うか、長さが三秒のテスト音を作成してください。-n フラグは、既存のファイルの上書きを拒否します。
ffmpeg -nostdin -hide_banner -v error -n -f lavfi \
-i 'sine=frequency=440:sample_rate=44100:duration=3' -c:a pcm_s16le input.wav
audio-encoding から変換スクリプトを実行します。
.venv/bin/python encode_audio.py --out-dir mp3 -- input.wav
OK の行と 1 converted, 0 failed を表示し、終了ステータス 0 で終了します。出力ファイルは mp3/input.mp3 です。同じコマンドを再実行すると、出力がすでに存在するため失敗したことを報告し、終了ステータス 1 で終了します。最初の MP3 のバイト列は保持されます。新たにエンコードする場合は、別の出力ディレクトリを選んでください。
音声ファイルのバッチ処理
wav_files ディレクトリを作成して WAV 録音を配置し、同じスクリプトに渡します。
.venv/bin/python encode_audio.py --out-dir mp3-batch -- wav_files/*.wav
Bash はこのグロブを、ディレクトリ直下のファイルに対して再帰せずに展開します。小文字の .wav の名前に一致するため、大文字の .WAV のファイルは明示的に渡してください。一致するファイルがなければ、パターンがそのままスクリプトに渡り、入力が存在しないため失敗します。スペースを含む個々のパスは引用符で囲んでください。区切りの -- により、ハイフンで始まる入力名も指定できます。
各入力について、OK または FAILED の行を表示します。成功と失敗が混在するバッチでは、有効な MP3 を保持し、破損したファイルの後も処理を続け、終了ステータス 1 で終了します。a/interview.wav と b/interview.wav のようなふたつの入力は、同じ出力名に対応します。最初に成功した変換の出力がその名前を使い、次の変換は失敗として報告されます。完了したバッチを再実行した際に、黙ってファイルをスキップしたり置き換えたりせず失敗を報告するのも、このためです。
| 終了ステータス | 意味 |
|---|---|
0 | 指定したすべての入力の変換に成功 |
1 | 出力先がすでに存在する場合も含め、少なくともひとつの入力で失敗 |
2 | FFmpeg 実行ファイルの欠落や出力ディレクトリが使用不能など、引数またはセットアップのエラー |
意図的なフェードの追加
冒頭と末尾の 100 ミリ秒をフェードさせるには、新しい出力ディレクトリを使います。
.venv/bin/python encode_audio.py --out-dir mp3-faded --fade-ms 100 -- input.wav
このオプションがなければ、スクリプトはフェード、ゲイン、ノーマライズ、ダイナミックレンジ圧縮のいずれも適用しません。MP3 のビットレートを上げても、元の音声にない情報は復元されません。レベルを変更するかどうかは試聴してから判断してください。ピークノーマライズ後に音量を上げると、音声がクリッピングすることがあります。ゲインとフェードの操作については、Pydub APIを参照してください。
出力の確認
最初の MP3 を調べ、最後までデコードします。
ffprobe -v error -select_streams a:0 \
-show_entries stream=codec_name,sample_rate,channels,bit_rate:format=duration \
-of json mp3/input.mp3 &&
ffmpeg -nostdin -v error -xerror -i mp3/input.mp3 -f null -
テスト音では、codec_name が mp3、sample_rate が 44100 で、チャンネル数がひとつ、長さが三秒程度になるはずです。MP3 フレームのパディングにより、報告される長さが少し長くなる場合があります。デコードコマンドは、エラーメッセージなしで正常に終了するはずです。メタデータとデコード可否の確認は有用ですが、どちらも聴感上の音質を裏付けるものではありません。
よくある問題のトラブルシューティング
No module named 'audioop'または'pyaudioop': プロジェクト内で.venv/bin/python -m pipを使い、バージョンを固定したパッケージのインストールを再実行してください。条件付き依存関係のaudioop-ltsも含めてください。- FFmpeg または
Unknown encoder 'libmp3lame'が見つからない: セットアップ時の実行ファイルとエンコーダー一覧を確認してください。Python パッケージとシステムのエンコーダーは別々にインストールします。 - 入力が破損している、または存在しない:
FAILEDの行と、その前にある FFmpeg の診断メッセージを確認してください。デコードやエンコードに失敗した場合、新しい MP3 は出力先に配置されません。既存の出力先は変更されません。 - ハードリンクまたは権限のエラー: ハードリンクをサポートする、書き込み可能なローカル出力ディレクトリを使ってください。通常の失敗ではスクリプトが一時作業ディレクトリを削除します。ファイルシステムのエラーを回避するために出力先を置き換えることはありません。
元の録音を保持し、エンコード設定を変更する際は新しい出力ディレクトリを使ってください。ローカルの Python プロセス外で変換する必要がある場合は、当社の音声エンコーディングサービスをご検討ください。
