audio-quality-check

音声録音品質アナライザー

通話録音の包括的な音声品質分析に対応しています。デュアルトラックの M4A ファイル（システム音声＋マイク）、シングルトラック録音、AEC 処理済みファイルを扱えます。

クイックスタート

録音ディレクトリに対して、同梱の分析スクリプトを実行します。

python ${CLAUDE_SKILL_DIR}/scripts/analyze_recording.py "/path/to/recording/directory"

分析対象を絞り込むモード：

python ${CLAUDE_SKILL_DIR}/scripts/analyze_recording.py /path --tracks   # track info only
python ${CLAUDE_SKILL_DIR}/scripts/analyze_recording.py /path --echo     # echo detection only
python ${CLAUDE_SKILL_DIR}/scripts/analyze_recording.py /path --quality  # quality metrics (skip echo)

Blackbox の録音では、通常、ディレクトリは次の場所にあります。 ~/Library/Application Support/Blackbox/Recordings/<timestamp-id>/

依存関係

システム：ffmpeg、ffprobe（brew install ffmpeg）
Python：numpy、soundfile、scipy、pyloudnorm、pesq、pystoi、librosa

Python の依存関係をすべてインストールするには：pip3 install numpy soundfile scipy pyloudnorm pesq pystoi librosa

各指標が示す内容

EBU R128 ラウドネス（pyloudnorm）

• 内容：LUFS（ラウドネス単位・フルスケール）で表す聴感上のラウドネス
• 目標値：音声では -16～-24 LUFS
• 注意点：AEC／後処理済みトラックが元のトラックより大幅に大きい場合、正規化せずに処理によって増幅されていることを示します。

エコー検出 - 自己相関

• 内容：さまざまな時間オフセットで信号とそれ自体を相関させ、単一トラック内の遅延した信号コピーを検出します。
• 読み取り方：20～100ms の範囲で相関値が 0.3 を超えるピークは、信号の重複を示します。ラグは重複した信号の遅延時間を示します。
• 重要なポイント：複数の時間区間で同じラグに一貫したピークが見られる場合、規則的な重複が発生しています（たとえば、Krisp のような仮想オーディオプロセッサーが約 53ms 遅れたコピーを加えている場合）。
• 通常値：0.15 未満のピークは通常、音声のピッチ高調波であり、問題ありません。一貫したラグで 0.3 を超えるピークはエコーを示します。

トラック間相関

• 内容：一方のトラックの音声がもう一方にどの程度含まれているかを測定します（たとえば、システム音声がマイクトラックに漏れ込んでいる場合）。
• 読み取り方：0 に近い値は漏れがないことを示します。0.1 を超える値は、マイクがシステム音声を拾っていることを示します。
• コヒーレンス：同じテストを周波数領域で行う方法です。音声のエコーでは、音声帯域（300～3400Hz）のコヒーレンスが最も重要です。

PESQ - 音声品質（参照信号と劣化信号が必要）

• 内容：ITU-T P.862 規格です。劣化した信号と参照信号を比較し、MOS（平均オピニオン評点）を算出します。
• 尺度：1.0（悪い）～4.5（優れている）。NB は狭帯域（電話品質）、WB は広帯域を表します。
• 用途：AEC 処理済みのマイク音声と元のマイク音声を比較し、処理が改善につながっているか、悪化させているかを確認します。
• しきい値：4.0 以上は優れている、3.0 以上は良好、2.5～3.0 は普通、2.5 未満は不良です。

STOI - 音声了解度（参照信号と劣化信号が必要）

• 内容：短時間客観了解度です。処理後も音声がどの程度理解できるかを測定します。
• 尺度：0.0～1.0
• しきい値：0.8 超は良好、0.6 超は普通、0.6 未満は不良です。
• 重要なポイント：元の音声と処理済み音声の間で STOI が大幅に低下している場合、処理によって了解度が低下しています。

スペクトル分析（librosa）

• セントロイド：振幅で重み付けした平均周波数です。値が高いほど、音声は明るく、耳障りになります。
• ロールオフ（85%）：スペクトルエネルギーの 85% が含まれる周波数です。値が低いほど、低音が強くなります。
• ゼロ交差率：信号がゼロを横切る頻度です。値が高いほど、信号のノイズが多くなります。音声では通常 0.05～0.20 で、0.30 を超える値は大きなノイズを示します。

SNR - 信号対雑音比

• 内容：音声エネルギーと背景ノイズエネルギーの比率です（エネルギーベースの VAD によって推定）。
• しきい値：20dB 超は優れている、15dB 超は良好、10dB 超は普通、10dB 未満は不良です。
• 注記：これは背景ノイズを測定するもので、エコーではありません。SNR が優れていても、録音にエコーの問題がある場合があります。

1 分ごとのエネルギー

• 内容：録音の 1 分ごとの RMS エネルギーと音声帯域エネルギーです。
• 用途：無音になった区間（マイクが途切れた）、予期せず大きくなった区間（クリッピングのリスク）、または話者が発話していた時間を特定する手がかりとなる活動パターンを見つけます。

手動分析の手順

スクリプトが提供する範囲を超えた分析が必要な場合は、次の方法が役立ちます。

デュアルトラック M4A から個別のトラックを抽出する

ffmpeg -y -i audio.m4a -map 0:0 -ac 1 -ar 16000 /tmp/system.wav
ffmpeg -y -i audio.m4a -map 0:1 -ac 1 -ar 16000 /tmp/mic.wav

sox で音量をすばやく確認

sox audio.wav -n stat 2>&1

エコーが発生している時間帯を確認（Python）

import numpy as np
import soundfile as sf
from scipy import signal

data, sr = sf.read('/tmp/system.wav')
# Analyze 5 seconds starting at 2 minutes
start = 120 * sr
seg = data[start:start + 5*sr]
seg_norm = seg / (np.max(np.abs(seg)) + 1e-10)
autocorr = np.correlate(seg_norm, seg_norm, mode='full')
mid = len(seg_norm) - 1
autocorr = autocorr / autocorr[mid]
# Check 20-100ms range for echo peaks
min_lag = int(0.020 * sr)
max_lag = int(0.100 * sr)
region = autocorr[mid + min_lag:mid + max_lag]
peaks, props = signal.find_peaks(region, height=0.1)
for i, p in enumerate(peaks[:5]):
    lag_ms = (p + min_lag) / sr * 1000
    print(f"  Peak at {lag_ms:.1f}ms, r={props['peak_heights'][i]:.3f}")

よくある問題とその原因

症状	考えられる原因	確認する項目
スピーカーの音がわずかに二重に聞こえる／エコーがかかる	仮想オーディオプロセッサ（Krisp）がシステム音声に遅延した音声を加えている	自己相関：40～60ms の位置に一貫したピークがある
マイクのトラックにリモートスピーカーの音声が入っている	音響エコー（スピーカーからマイクへの回り込み）	トラック間の相関が 0.1 を超えている
AEC 処理済みファイルの音質が悪化する	DTLN-aec による信号品質の劣化	処理前と処理後を比較した PESQ／STOI
AEC 処理済みファイルの音量が大きすぎる	処理後に音量の正規化が行われていない	音量：処理後が -10 LUFS を超えている
録音にヒスノイズ／ノイズが入っている	SNR の低さ、ノイズの多いマイク、または AGC によるアーティファクト	SNR が 15dB 未満、高いゼロ交差率
録音の途中に音量の小さい区間がある	マイクが一時的に切断された、またはデバイスが変更された	分ごとのエネルギー：RMS が急激に低下している