audio-analyzer

オーディオアナライザー

オーディオファイルを分析するための包括的なツールキットです。テンポ、調、周波数成分、ラウドネス指標などの詳細な情報を抽出し、プロフェッショナルな可視化を生成します。

クイックスタート

from scripts.audio_analyzer import AudioAnalyzer

# Analyze an audio file
analyzer = AudioAnalyzer("song.mp3")
analyzer.analyze()

# Get all analysis results
results = analyzer.get_results()
print(f"BPM: {results['tempo']['bpm']}")
print(f"Key: {results['key']['key']} {results['key']['mode']}")

# Generate visualizations
analyzer.plot_waveform("waveform.png")
analyzer.plot_spectrogram("spectrogram.png")

# Full report
analyzer.save_report("analysis_report.json")

機能

• テンポ／BPM 検出：信頼度スコア付きの正確なビートトラッキング
• 調の検出：調とモード（メジャー／マイナー）を特定
• 周波数分析：スペクトル、主要周波数、周波数帯域
• ラウドネス指標：RMS、ピーク、LUFS、ダイナミックレンジ
• 波形の可視化：マルチチャンネルの波形プロット
• スペクトログラム：カスタマイズ可能な時間周波数の可視化
• クロマグラム：ハーモニー分析向けのピッチクラスの可視化
• ビートグリッド：波形に重ねて表示するビートマーカー
• エクスポート形式：JSON レポート、PNG／SVG の可視化

API リファレンス

初期化

# From file
analyzer = AudioAnalyzer("audio.mp3")

# With custom sample rate
analyzer = AudioAnalyzer("audio.wav", sr=44100)

分析メソッド

# Run full analysis
analyzer.analyze()

# Individual analyses
analyzer.analyze_tempo()      # BPM and beat positions
analyzer.analyze_key()        # Musical key detection
analyzer.analyze_loudness()   # RMS, peak, LUFS
analyzer.analyze_frequency()  # Spectrum analysis
analyzer.analyze_dynamics()   # Dynamic range

結果へのアクセス

# Get all results as dict
results = analyzer.get_results()

# Individual results
tempo = analyzer.get_tempo()        # {'bpm': 120, 'confidence': 0.85, 'beats': [...]}
key = analyzer.get_key()            # {'key': 'C', 'mode': 'major', 'confidence': 0.72}
loudness = analyzer.get_loudness()  # {'rms_db': -14.2, 'peak_db': -0.5, 'lufs': -14.0}
freq = analyzer.get_frequency()     # {'dominant_freq': 440, 'spectrum': [...]}

可視化メソッド

# Waveform
analyzer.plot_waveform(
    output="waveform.png",
    figsize=(12, 4),
    color="#1f77b4",
    show_rms=True
)

# Spectrogram
analyzer.plot_spectrogram(
    output="spectrogram.png",
    figsize=(12, 6),
    cmap="magma",           # viridis, plasma, inferno, magma
    freq_scale="log",       # linear, log, mel
    max_freq=8000           # Hz
)

# Chromagram (pitch classes)
analyzer.plot_chromagram(
    output="chromagram.png",
    figsize=(12, 4)
)

# Onset strength / beat grid
analyzer.plot_beats(
    output="beats.png",
    figsize=(12, 4),
    show_strength=True
)

# Combined dashboard
analyzer.plot_dashboard(
    output="dashboard.png",
    figsize=(14, 10)
)

エクスポート

# JSON report with all analysis
analyzer.save_report("report.json")

# Summary text
summary = analyzer.get_summary()
print(summary)

分析の詳細

テンポ検出

ビートトラッキングアルゴリズムを使用して、次の項目を検出します。

• BPM：1 分あたりのビート数（テンポ）
• ビート位置：検出されたビートのタイムスタンプ
• 信頼度：信頼性スコア（0～1）

tempo = analyzer.get_tempo()
# {
#     'bpm': 128.0,
#     'confidence': 0.89,
#     'beats': [0.0, 0.469, 0.938, 1.406, ...],  # seconds
#     'beat_count': 256
# }

調の検出

ハーモニー成分を分析して、次の項目を特定します。

• 調：主音（C、C#、D など）
• モード：メジャーまたはマイナー
• 信頼度：検出の信頼度
• 調プロファイル：各調との相関

key = analyzer.get_key()
# {
#     'key': 'A',
#     'mode': 'minor',
#     'confidence': 0.76,
#     'profile': {'C': 0.12, 'C#': 0.08, ...}
# }

ラウドネス指標

包括的なラウドネス分析を行います。

• RMS dB：二乗平均平方根レベル
• ピーク dB：サンプルの最大レベル
• LUFS：統合ラウドネス（放送規格）
• ダイナミックレンジ：音量の大きいセクションと小さいセクションの差

loudness = analyzer.get_loudness()
# {
#     'rms_db': -14.2,
#     'peak_db': -0.3,
#     'lufs': -14.0,
#     'dynamic_range_db': 12.5,
#     'crest_factor': 8.2
# }

周波数分析

スペクトル分析では、次の項目を確認します。

• 主要周波数：最も強い周波数成分
• 周波数帯域：低音、中音、高音のエネルギー
• スペクトル重心：オーディオの「明るさ」
• スペクトルロールオフ：エネルギーの 85％を含む周波数

freq = analyzer.get_frequency()
# {
#     'dominant_freq': 440.0,
#     'spectral_centroid': 2150.3,
#     'spectral_rolloff': 4200.5,
#     'bands': {
#         'sub_bass': -28.5,      # 20-60 Hz
#         'bass': -18.2,          # 60-250 Hz
#         'low_mid': -12.1,       # 250-500 Hz
#         'mid': -10.8,           # 500-2000 Hz
#         'high_mid': -14.3,      # 2000-4000 Hz
#         'high': -22.1           # 4000-20000 Hz
#     }
# }

CLI の使用方法

# Full analysis with all visualizations
python audio_analyzer.py --input song.mp3 --output-dir ./analysis/

# Just tempo and key
python audio_analyzer.py --input song.mp3 --analyze tempo key --output report.json

# Generate specific visualization
python audio_analyzer.py --input song.mp3 --plot spectrogram --output spec.png

# Dashboard view
python audio_analyzer.py --input song.mp3 --dashboard --output dashboard.png

# Batch analyze directory
python audio_analyzer.py --input-dir ./songs/ --output-dir ./reports/

CLI 引数

引数	説明	デフォルト
--input	入力オーディオファイル	必須
--input-dir	オーディオファイルのディレクトリ	-
--output	出力ファイルのパス	-
--output-dir	出力ディレクトリ	.
--analyze	分析タイプ：tempo、key、loudness、frequency、all	all
--plot	プロットの種類：waveform、spectrogram、chromagram、beats、dashboard	-
--format	出力形式：json、txt	json
--sr	分析用のサンプルレート	22050

使用例

曲の分析

analyzer = AudioAnalyzer("track.mp3")
analyzer.analyze()

print(f"Tempo: {analyzer.get_tempo()['bpm']:.1f} BPM")
print(f"Key: {analyzer.get_key()['key']} {analyzer.get_key()['mode']}")
print(f"Loudness: {analyzer.get_loudness()['lufs']:.1f} LUFS")

analyzer.plot_dashboard("track_analysis.png")

ポッドキャストの品質チェック

analyzer = AudioAnalyzer("podcast.mp3")
analyzer.analyze_loudness()

loudness = analyzer.get_loudness()
if loudness['lufs'] > -16:
    print("Warning: Audio may be too loud for podcast standards")
elif loudness['lufs'] < -20:
    print("Warning: Audio may be too quiet")
else:
    print("Loudness is within podcast standards (-16 to -20 LUFS)")

一括分析

import os
from scripts.audio_analyzer import AudioAnalyzer

results = []
for filename in os.listdir("./songs"):
    if filename.endswith(('.mp3', '.wav', '.flac')):
        analyzer = AudioAnalyzer(f"./songs/{filename}")
        analyzer.analyze()
        results.append({
            'file': filename,
            'bpm': analyzer.get_tempo()['bpm'],
            'key': f"{analyzer.get_key()['key']} {analyzer.get_key()['mode']}",
            'lufs': analyzer.get_loudness()['lufs']
        })

# Sort by BPM for DJ set
results.sort(key=lambda x: x['bpm'])

対応形式

入力形式（librosa／soundfile 経由）：

• MP3
• WAV
• FLAC
• OGG
• M4A/AAC
• AIFF

出力形式：

• JSON（分析レポート）
• PNG（可視化）
• SVG（可視化）
• TXT（要約）

依存関係

librosa>=0.10.0
soundfile>=0.12.0
matplotlib>=3.7.0
numpy>=1.24.0
scipy>=1.10.0

制限事項

• 調の検出はメロディー成分のあるオーディオで最も効果を発揮します（ドラム／パーカッションでは精度が下がります）
• BPM 検出は、自由なテンポや複雑な拍子ではうまくいかない場合があります
• 非常に短いクリップ（5 秒未満）では、精度が低下する場合があります
• LUFS の計算は簡略化されており、ITU-R BS.1770-4 に完全準拠しているわけではありません