audio-quality-check

分类: 数据与AI | 上传者: tenequm | 下载: 0 | 版本: v1.0（最新）

分析录音质量 - 回声检测、响度、语音清晰度、SNR、频谱分析。当用户想要检查录音质量、检测音频文件中的回声或重复、测量语音清晰度、比较原始音频与处理后的音频、诊断录音听起来不好的原因或分析来自 Blackbox 或任何通话录音应用程序的音轨时使用。触发音频质量、录音分析、回声检测、检查录音、声音质量、分析音频、语音质量、PESQ、STOI、响度、SNR、音频诊断、录音声音不良、录音中的回声、音频重复。

更新日志: Source: GitHub https://github.com/tenequm/skills

目录结构

当前层级: tree/main/skills/audio-quality-check/

📁 evals/
- 📄 evals.json 1.6 KB
📁 scripts/
- 📄 analyze_recording.py 20.9 KB
📄 LICENSE.txt 8.9 KB
📄 SKILL.md 6.7 KB

SKILL.md

---
name: audio-quality-check
description: Analyze audio recording quality - echo detection, loudness, speech intelligibility, SNR, spectral analysis. Use when the user wants to check a recording's quality, detect echo or duplication in audio files, measure speech clarity, compare original vs processed audio, diagnose why a recording sounds bad, or analyze audio tracks from Blackbox or any call recording app. Triggers on audio quality, recording analysis, echo detection, check recording, sound quality, analyze audio, speech quality, PESQ, STOI, loudness, SNR, audio diagnostics, recording sounds bad, echo in recording, audio duplication.
metadata:
  version: "0.1.0"
---

# Audio Recording Quality Analyzer

Comprehensive audio quality analysis for call recordings. Handles dual-track M4A files (system audio + mic), single-track recordings, and AEC-processed files.

## Quick Start

Run the bundled analysis script on a recording directory:

```bash
python <skill-path>/scripts/analyze_recording.py "/path/to/recording/directory"
```

Modes for focused analysis:
```bash
python <skill-path>/scripts/analyze_recording.py /path --tracks   # track info only
python <skill-path>/scripts/analyze_recording.py /path --echo     # echo detection only
python <skill-path>/scripts/analyze_recording.py /path --quality  # quality metrics (skip echo)
```

For Blackbox recordings, the directory is typically:
`~/Library/Application Support/Blackbox/Recordings/<timestamp-id>/`

## Dependencies

System: `ffmpeg`, `ffprobe` (brew install ffmpeg)
Python: `numpy`, `soundfile`, `scipy`, `pyloudnorm`, `pesq`, `pystoi`, `librosa`

Install all Python deps: `pip3 install numpy soundfile scipy pyloudnorm pesq pystoi librosa`

## What Each Metric Tells You

### EBU R128 Loudness (pyloudnorm)
- **What**: Perceptual loudness in LUFS (Loudness Units Full Scale)
- **Target**: -16 to -24 LUFS for speech
- **Watch for**: AEC/post-processed tracks being significantly louder than originals (indicates the processing is amplifying without normalizing)

### Echo Detection - Autocorrelation
- **What**: Detects delayed copies of the signal within a single track by correlating the signal with itself at various time offsets
- **How to read**: Peaks in the 20-100ms range with correlation > 0.3 indicate signal duplication. The lag tells you the delay of the duplicate copy
- **Key insight**: If you see a consistent peak at the same lag across multiple time segments, that's a systematic duplication (e.g., a virtual audio processor like Krisp introducing a delayed copy at ~53ms)
- **Normal values**: Peaks below 0.15 are typically speech pitch harmonics (harmless). Peaks above 0.3 at consistent lags are echo

### Cross-Track Correlation
- **What**: Measures how much one track's content appears in another (e.g., system audio bleeding into the mic track)
- **How to read**: Values near 0 mean no bleed. Values above 0.1 indicate the mic is picking up system audio
- **Coherence**: Frequency-domain version of the same test. Voice-band coherence (300-3400Hz) is most relevant for speech echo

### PESQ - Speech Quality (requires reference + degraded)
- **What**: ITU-T P.862 standard. Gives a MOS (Mean Opinion Score) comparing a degraded signal against a reference
- **Scale**: 1.0 (bad) to 4.5 (excellent). NB = narrowband (phone quality), WB = wideband
- **Use for**: Comparing AEC-processed mic vs original mic to see if processing helps or hurts
- **Thresholds**: 4.0+ excellent, 3.0+ good, 2.5-3.0 fair, <2.5 poor

### STOI - Speech Intelligibility (requires reference + degraded)
- **What**: Short-Time Objective Intelligibility. Measures how understandable speech remains after processing
- **Scale**: 0.0 to 1.0
- **Thresholds**: >0.8 good, >0.6 fair, <0.6 poor
- **Key insight**: If STOI drops significantly between original and processed, the processing is degrading intelligibility

### Spectral Analysis (librosa)
- **Centroid**: Average frequency weighted by amplitude. Higher = brighter/harsher audio
- **Rolloff (85%)**: Frequency below which 85% of spectral energy sits. Lower = more bass-heavy
- **Zero-crossing rate**: How often the signal crosses zero. Higher = noisier signal. Speech is typically 0.05-0.20; values above 0.30 suggest significant noise

### SNR - Signal-to-Noise Ratio
- **What**: Ratio of speech energy to background noise energy (estimated via energy-based VAD)
- **Thresholds**: >20dB excellent, >15dB good, >10dB fair, <10dB poor
- **Note**: This measures background noise, not echo. A recording can have excellent SNR but still have echo problems

### Per-Minute Energy
- **What**: RMS energy and voice-band energy per minute of recording
- **Use for**: Spotting segments that went silent (mic cut out), got unexpectedly loud (clipping risk), or had activity patterns that help identify when speakers were active

## Manual Analysis Recipes

When you need analysis beyond what the script provides, these patterns are useful.

### Extract individual tracks from dual-track M4A
```bash
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
```

### Quick loudness check with sox
```bash
sox audio.wav -n stat 2>&1
```

### Check specific time range for echo (Python)
```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}")
```

## Common Issues and What Causes Them

| Symptom | Likely cause | What to check |
|---------|-------------|---------------|
| Speakers sound slightly doubled/echoed | Virtual audio processor (Krisp) creating delayed copy in system audio | Autocorrelation: consistent peak at 40-60ms |
| Mic track has remote speakers' voices | Acoustic echo (speakers to mic) | Cross-track correlation > 0.1 |
| AEC-processed file sounds worse | DTLN-aec degrading signal quality | PESQ/STOI comparing original vs processed |
| AEC-processed file is too loud | Missing loudness normalization after processing | Loudness: processed > -10 LUFS |
| Recording has hiss/noise | Low SNR, noisy mic, or AGC artifacts | SNR < 15dB, high zero-crossing rate |
| Quiet segments mid-recording | Mic cut out or device changed | Per-minute energy: sudden RMS drop |

登录后下载/点赞/收藏 ❤ 19 | ★ 0

audio-quality-check

目录结构

SKILL.md

举报内容

提示