split_audio_with_overlap.py ドキュメント
本ドキュメントは、Pythonプログラム split_audio_with_overlap.py の機能、使用方法、および内部処理について説明します。
概要
split_audio_with_overlap.py は、指定された音声ファイルを、指定された最大サイズとオーバーラップ時間に基づいて複数のチャンクに分割し、それぞれを個別の音声ファイルとして保存するスクリプトです。これにより、大容量の音声ファイルを管理しやすいサイズに分割したり、処理負荷を軽減したりすることが可能になります。
機能
音声ファイルの読み込み: 様々な形式の音声ファイル（
pydubがサポートする形式）を読み込みます。サイズベースの分割: 指定された最大サイズ（メガバイト）に基づき、各チャンクの長さを推定します。
オーバーラップ処理: 各チャンク間に指定された秒数のオーバーラップ（重複）を持たせ、分割境界での音切れを軽減します。
出力ディレクトリの自動作成: 分割されたファイルを保存するための専用ディレクトリを自動的に作成します。
出力形式とビットレートの指定: 出力ファイルの形式（例:
mp3,wav）とビットレートを任意に指定できます。コマンドライン引数での設定変更: 主要な設定値をコマンドライン引数で変更できます。
非標準ライブラリ
本プログラムは、以下の非標準ライブラリを使用しています。
pydub: 音声ファイルの操作（読み込み、書き出し、切り出しなど）を行うためのライブラリです。内部でffmpegまたはlibavを利用します。
インストール方法
本プログラムを実行するには、まず以下のライブラリと外部ツールをインストールする必要があります。
pydubのインストールpipを使用してインストールできます。pip install pydub
ffmpegのインストールpydubがmp3などの様々な音声形式を処理するために、内部でffmpegを利用します。お使いのオペレーティングシステムに応じた方法でffmpegをインストールし、システムパスが通っていることを確認してください。macOS:
brew install ffmpeg
Ubuntu/Debian:
sudo apt update sudo apt install ffmpeg
Windows:
ffmpegの公式サイトからバイナリをダウンロードし、実行ファイルへのパスを環境変数Pathに追加してください。
使用方法
基本的な使い方は、入力音声ファイルを指定してスクリプトを実行することです。
python split_audio_with_overlap.py <input_audio_file> [output_format] [bitrate] [max_size_mb] [overlap_sec]
使用例
デフォルト設定で音声ファイルを分割する
audio.wavをデフォルト設定（出力形式:mp3, ビットレート:128k, 最大サイズ:150MB, オーバーラップ:60秒）で分割します。python split_audio_with_overlap.py audio.wav
出力形式を
wavに指定して分割するaudio.mp3をwav形式で分割します。その他の設定はデフォルトが適用されます。python split_audio_with_overlap.py audio.mp3 wav
出力形式とビットレートを指定して分割する
long_audio.flacをmp3形式、192kビットレートで分割します。python split_audio_with_overlap.py long_audio.flac mp3 192k
すべての設定をコマンドラインで指定する
podcast.oggをmp3形式、160kビットレート、最大チャンクサイズ100MB、オーバーラップ30秒で分割します。python split_audio_with_overlap.py podcast.ogg mp3 160k 100 30
引数
プログラムは以下のコマンドライン引数をサポートします。引数は指定された順序で処理されます。
<input_audio_file>(必須)型: 文字列
説明: 分割する元の音声ファイルのパスです。
[output_format](オプション)型: 文字列
説明: 出力するチャンクファイルの形式です（例:
mp3,wav,flac）。省略した場合、デフォルト値のmp3が使用されます。デフォルト値:
mp3
[bitrate](オプション)型: 文字列
説明: 出力ファイルのビットレートです（例:
128k,192k,256k）。省略した場合、デフォルト値の128kが使用されます。デフォルト値:
128k
[max_size_mb](オプション)型: 浮動小数点数
説明: 各チャンクの最大サイズをメガバイト (MB) 単位で指定します。省略した場合、デフォルト値の
150が使用されます。デフォルト値:
150
[overlap_sec](オプション)型: 浮動小数点数
説明: 各チャンクのオーバーラップ時間（秒）を指定します。省略した場合、デフォルト値の
60が使用されます。デフォルト値:
60
設定
プログラムの冒頭で、以下の設定変数が定義されています。これらの設定は、コマンドライン引数によって上書きされない限り適用されます。
output_dirデフォルト値:
"split_fixed"説明: 分割された音声チャンクを保存するサブディレクトリの名前です。このディレクトリは、入力ファイルと同じ階層に作成されます。コマンドライン引数では変更できません。
output_formatデフォルト値:
"mp3"説明: 出力ファイルの形式です。コマンドライン引数の2番目で上書き可能です。
bitrateデフォルト値:
"128k"説明: 出力ファイルのビットレートです。コマンドライン引数の3番目で上書き可能です。
max_size_mbデフォルト値:
150説明: 各チャンクの最大サイズ（MB）です。コマンドライン引数の4番目で上書き可能です。
overlap_secデフォルト値:
60説明: 各チャンク間のオーバーラップ時間（秒）です。コマンドライン引数の5番目で上書き可能です。
入出力仕様
入力
ファイル: 必須として1つの音声ファイルパスを受け取ります。
形式:
pydubがサポートする任意の音声形式（例:.mp3,.wav,.flac,.oggなど）。
出力
出力ディレクトリ:
入力ファイルが存在するディレクトリ内に、
output_dir変数（デフォルトはsplit_fixed）で指定された名前のサブディレクトリが作成されます。例: 入力ファイルが
/path/to/my_audio.mp3の場合、出力ディレクトリは/path/to/split_fixed/となります。
出力ファイル:
分割された各チャンクは、上記の出力ディレクトリ内に保存されます。
ファイル名の命名規則は
<元のファイル名の本体>_<チャンク番号3桁>. <出力形式>です。チャンク番号は
000から始まり、001,002と続きます。例:
my_audio_000.mp3,my_audio_001.mp3, ...
形式:
output_format引数（または設定）で指定された形式（例:mp3,wav）。ビットレート:
bitrate引数（または設定）で指定されたビットレート。
処理フロー
split_audio_with_overlap.py は以下のステップで処理を実行します。
初期設定と引数処理:
プログラム冒頭でデフォルトの設定値を定義します。
コマンドライン引数を解析し、指定された値でデフォルト設定を上書きします。
引数が不足している場合や、指定された入力ファイルが存在しない場合はエラーメッセージを表示し、終了します。
音声ファイルの読み込み:
入力ファイルパスから拡張子を抽出し、
pydub.AudioSegment.from_file()を使用して音声ファイルを読み込みます。音声ファイルの合計長さ（秒）を計算します。
処理情報の出力:
現在の出力設定（出力ディレクトリ、フォーマット、ビットレート、オーバーラップ長、最大サイズ、音声長さ）をコンソールに出力します。
出力ディレクトリの準備:
入力ファイルが存在するディレクトリのパスを取得し、その中に
output_dir(デフォルトsplit_fixed) を結合して出力ディレクトリのパスを構築します。出力ディレクトリが存在しない場合は、
os.makedirs(exist_ok=True)を使用して作成します。
チャンク長の見積もり:
指定されたビットレート (
bitrate) をキロビット毎秒 (kbps) からバイト毎秒 (bytes_per_sec) に変換します。指定された最大サイズ (
max_size_mb) をバイト単位 (max_bytes) に変換します。max_bytesをbytes_per_secで割ることで、各チャンクの最大許容時間 (max_chunk_sec) を秒単位で推定します。次のチャンクの開始位置を決定するためのステップ幅 (
step) を、max_chunk_secからoverlap_secを引くことで計算します。これらの推定値をコンソールに出力します。
分割処理ループ:
start_secが音声ファイルの総長duration_secを超えるまでループを繰り返します。チャンクの終了時刻の決定: 現在の
start_secにmax_chunk_secを加えることで、チャンクの仮の終了時刻end_secを計算します。ただし、音声ファイルの総長を超えないように調整します。音声の切り出し:
start_secとend_secをミリ秒に変換し、AudioSegmentオブジェクトから該当する範囲の音声を切り出します。ファイル保存:
入力ファイルの本体名と現在のチャンクインデックス (3桁ゼロ埋め) を組み合わせて出力ファイル名を生成します。
出力ディレクトリとファイル名を結合し、完全な出力パスを作成します。
切り出したチャンクを、指定されたフォーマットとビットレートでファイルにエクスポートします。
保存されたファイルパスとチャンクの長さをコンソールに出力します。
次のチャンクへ移動:
start_secにstepを加算し、次のチャンクの開始位置を設定します。チャンクインデックスもインクリメントします。
完了メッセージ:
すべての分割処理が完了した後、完了メッセージを表示します。
ユーザーが
ENTERキーを押すまでプログラムの終了を待機します。
エラー処理
本プログラムは以下のエラー処理を行います。
引数不足:
コマンドライン引数が
input_audio_fileひとつのみでない場合（つまりsys.argvの長さが2未満の場合）、正しい使い方を表示してプログラムを終了します。
ファイルの不在:
指定された
input_fileが存在しない場合、エラーメッセージを表示してプログラムを終了します。
上記以外のファイルI/Oエラーや、pydub 内部でのエラー（例: ffmpeg が見つからない、サポートされていない形式など）が発生した場合、それぞれのライブラリやOSの機構によってエラーが報告されます。