# audio-quality-check

Adopt this skill: https://proskills.md/skills/other/tenequm-skills-archive-audio-quality-check

Page: https://proskills.md/skills/other/tenequm-skills-archive-audio-quality-check
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: archive/audio-quality-check/SKILL.md
size: 6979
upstream: https://github.com/tenequm/skills/blob/main/archive/audio-quality-check/SKILL.md

````text
---
name: audio-quality-check
description: Analyzes audio recording quality - echo detection, loudness, speech intelligibility, SNR, and spectral analysis. Use when the user wants to check a recording's quality, detect echo or duplication, measure speech clarity, compare original vs processed audio, or diagnose why a recording sounds bad, including tracks from Blackbox or any call recording app.
metadata:
  internal: true
  version: "0.1.4"
  categories: "creative"
  topics: "audio, loudness, snr, speech-intelligibility, spectral-analysis"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/audio-quality-check
    emoji: "🎧"
    requires:
      bins:
        - ffmpeg
    install:
      - kind: brew
        formula: ffmpeg
        bins:
          - ffmpeg
          - ffprobe
---

# 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 ${CLAUDE_SKILL_DIR}/scripts/analyze_recording.py "/path/to/recording/directory"
```

Modes for focused analysis:
```bash
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)
```

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 |
````

## File: README.md
upstream: https://github.com/tenequm/skills/blob/main/README.md

````text
# Skills

Agent skills for founders and developers, published to [ClawHub](https://clawhub.ai/tenequm/skills).

Each skill is a folder under `skills/<name>/` with a `SKILL.md` plus optional `references/`. Retired skills live in `archive/` and are no longer published.

## Table of Contents

- [Install](#install)
- [Skill Catalog](#skill-catalog)
- [Releases](#releases)
- [Contributing](#contributing)
- [License](#license)

## Install

```bash
# From ClawHub
clawhub install @tenequm/<skill-name>

# Or straight from this repository
npx skills add tenequm/skills@<skill-name>
```

## Skill Catalog

<!-- GENERATED_SKILLS_TABLE_START -->
| Skill | Version | ClawHub | Description |
|-------|---------|---------|-------------|
| `acpx-faq` | 0.11.0 | [page](https://clawhub.ai/tenequm/skills/acpx-faq) | Run coding agents (codex, claude, agy) through the acpx ACP CLI - one-shot dispatch into named sessions you can watch live. Use before launching or prompting a subagent, or when a command fails, a session is missing, or a prompt is lost. |
| `chrome-extension-wxt` | 2.1.1 | [page](https://clawhub.ai/tenequm/skills/chrome-extension-wxt) | Builds cross-browser extensions with WXT - entrypoints, content-script UI, storage, messaging, MV3 rules, testing, publishing. Use for Chrome or browser extension work, wxt.config.ts, Manifest V3, or WXT build and type errors. |
| `founder-playbook` | 0.1.7 | [page](https://clawhub.ai/tenequm/skills/founder-playbook) | Decision validation and thinking frameworks for founders. Use to pressure-test a decision, validate next steps, or sanity-check an approach - "should I", "help me think through", "what am I missing". Covers fundraising, customers, runway. |
| `ghostwriter` | 0.1.3 | [page](https://clawhub.ai/tenequm/skills/ghostwriter) | Write content by interviewing the user instead of drafting - extract their material through questions, then assemble the piece from their own words. Use when the user needs to write something for an audience or mentions "ghostwriter". |
| `go-dev` | 0.7.0 | [page](https://clawhub.ai/tenequm/skills/go-dev) | Opinionated Go setup with golangci-lint v2, gofumpt, gotestsum, golang-migrate, and just. Use when starting a Go project, configuring lint, format, test, coverage or CI, writing a Justfile, wiring migrations, or leaving a Makefile workflow. |
| `grill-me` | 0.1.4 | [page](https://clawhub.ai/tenequm/skills/grill-me) | Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me". |
| `i-have-adhd` | 0.1.1 | [page](https://clawhub.ai/tenequm/skills/i-have-adhd) | Shape output for a reader with ADHD: lead with the next action, number multi-step work, restate state, suppress tangents, make wins visible. Use when the user types /i-have-adhd or asks for ADHD mode; stays on until "stop adhd mode". |
| `lance-format` | 0.22.0 | [page](https://clawhub.ai/tenequm/skills/lance-format) | Deep reference for Lance v15 columnar format, its Rust crates, and pylance - file encodings, table format, indexes, schema evolution, time travel. Use when building on the Lance crates or reading .lance datasets, not the LanceDB product. |
| `mcp-best-practices` | 1.3.1 | [page](https://clawhub.ai/tenequm/skills/mcp-best-practices) | Build, harden, and debug production MCP servers with the TypeScript SDK. Use when writing or reviewing an MCP server - transports, tool schemas, errors, OAuth, token bloat, SDK migrations, MCP Apps, Registry. Assumes a server already exists. |
| `okf-project-knowledge-base` | 0.3.1 | [page](https://clawhub.ai/tenequm/skills/okf-project-knowledge-base) | Durable project knowledge as Git-native OKF bundles (docs/knowledge/, one concept per file, with provenance and trust tiers). Use to record a decision, finding, or rule that must outlive the session. Not session state or agent instructions. |
| `polish-new` | 0.1.3 | [page](https://clawhub.ai/tenequm/skills/polish-new) | Pre-release code review that converges - parallel review agents sized to the diff, findings validated against evidence in a run ledger, fixes on approval, then re-reviews its own fixes until a round warrants no edits. Run on /polish-new. |
| `polish` | 3.1.1 | [page](https://clawhub.ai/tenequm/skills/polish) | Pre-release code review - lint and type checks, parallel review agents (cleanliness, design, efficiency, side-effect gating), findings validated, fixes on approval. Reviews a GitHub PR when given one. Run before committing, pushing, or on a PR. |
| `pre-compact` | 0.1.5 | [page](https://clawhub.ai/tenequm/skills/pre-compact) | Prepare the session for context compaction - write a handoff file a fresh session can continue from, propose updates to the project's durable docs, apply them on approval or with `auto`. Use before compacting or clearing context, or on "pre-compact". |
| `python-dev` | 0.3.1 | [page](https://clawhub.ai/tenequm/skills/python-dev) | Opinionated Python development setup with uv, ty, ruff, pytest, lefthook, and just. Use when creating a new Python project, writing or fixing pyproject.toml, or configuring linting, formatting, type checking, testing, git hooks, or CI. |
| `reset-context-contamination` | 0.1.5 | [page](https://clawhub.ai/tenequm/skills/reset-context-contamination) | Discards this thread's accumulated drafts and framings and re-derives the task from a clean problem statement. Use when the user says the thread is contaminated, the conversation is going in circles, or that they want a fresh take. |
| `rust-dev` | 0.9.0 | [page](https://clawhub.ai/tenequm/skills/rust-dev) | Day-1 guide to building well in Rust - ownership, errors as values, String vs &str, Box/Rc/Arc, anyhow vs thiserror, and a crate shortlist (tokio, serde, axum, sqlx). Use when starting a Rust project, fighting the borrow checker, or picking crates. |
| `skills-best-practices` | 0.9.1 | [page](https://clawhub.ai/tenequm/skills/skills-best-practices) | Opinionated best practices for building Agent Skills - SKILL.md structure, frontmatter, description writing, progressive disclosure, testing, distribution. Use when creating or reviewing a skill, or debugging why one will not trigger. |
| `standard-readme` | 0.1.6 | [page](https://clawhub.ai/tenequm/skills/standard-readme) | Writes or audits READMEs against the Standard Readme spec. Use whenever the user asks to create, rewrite, improve, audit, or fix a README, or asks about README quality or structure - even if they never mention "standard readme". |
| `swift-dev` | 0.3.1 | [page](https://clawhub.ai/tenequm/skills/swift-dev) | Native iOS and macOS apps in Swift 6 - SwiftUI, AppKit, SwiftData, concurrency, Swift Testing, XcodeGen, CallKit and audio, App Intents, devices, TestFlight, code signing, notarization. Use for any iPhone or Mac app, helper or CLI work. |
| `typescript-dev` | 0.5.0 | [page](https://clawhub.ai/tenequm/skills/typescript-dev) | Full-stack TypeScript with Vite 8, React 19, Tailwind v4, shadcn/ui, Biome, Vitest, and Hono 4. Use when setting up or working in a TypeScript project - components, styling, build and HMR, tests, lint/CI, or a Hono API with type-safe RPC. |
| `update-skill` | 0.10.0 | [page](https://clawhub.ai/tenequm/skills/update-skill) | Thorough on-demand refresh of one skill in a skills repo - researches usage, upstream, and docs in parallel, gates twice for approval, bumps version, updates CHANGELOG, validates, commits, watches CI. Use to check a skill's freshness. |
<!-- GENERATED_SKILLS_TABLE_END -->

## Releases

Every push to `main` publishes the skills whose `metadata.version` changed since the last `skills-*` tag to ClawHub, then cuts a GitHub release with per-skill notes. A changed skill without a version bump fails the release. Preview a release with `just release-plan`.

## Contributing

Issues and pull requests are welcome. Before opening a PR:

- bump `metadata.vers
````
