Audio Processing CLI Documentation Parser
Transform the audio_processor CLAUDE.md file into actionable knowledge for working with an advanced audio splitting tool that uses silence detection and FLAC optimization.
What This Skill Does
Parses and understands the architecture, parameters, and workflow of an audio processing tool that:
Splits monologue recordings by detecting 25-second silence gapsOptimizes output to 16kHz mono FLAC format for speech transcriptionProvides interactive CLI with Typer and Rich formattingManages processed files automatically with safe workflowsStep-by-Step Instructions
1. Identify Core Processing Parameters
Extract and document the critical silence detection settings:
**min_silence_len**: 25000ms (25 seconds) chunk boundary threshold**silence_thresh**: -40dB amplitude threshold**keep_silence**: 1000ms preserved at boundaries**min_chunk_duration**: 5000ms minimum chunk size**Critical Rule**: Chunk boundary placed at START of silence (end of previous chunk); next chunk starts at END of silence2. Map Project Architecture
Document the file structure and purpose:
`audio_splitter.py`: Core processing with PyDub silence detection`audio_splitter_cli.py`: Main CLI with Typer (recommended interface)`run.py`: Simple batch processor entry point`main.py`: Basic minimal entry point`input/`: Source audio files (excludes `input/processed/`)`output/`: Organized subdirectories with chunks and metadata3. Document Development Commands
Provide executable command patterns:
```bash
CLI with interactive configuration
uv run python audio_splitter_cli.py process --interactive
FLAC optimization
uv run python audio_splitter_cli.py optimize input.wav --output optimized.flac
Alternative interfaces
uv run python run.py # Batch processor
uv run python main.py # Basic entry
```
4. Extract Dependency Categories
Organize dependencies by function:
**Core**: Librosa (analysis), SoundFile (I/O), NumPy (operations), FFmpeg (FLAC conversion)**CLI**: Typer (framework), Rich (terminal UI), Pydantic (validation), PyYAML (config)**Monitoring**: tqdm (progress), psutil (memory)5. Document FLAC Optimization Strategy
Detail the speech transcription optimization:
16kHz sample rate (optimal speech intelligibility for LLMs)Mono conversion (50% size reduction)16-bit depth (quality preservation)Compression level 8 (excellent compression without overhead)Result: 90-95% size reduction from originals6. Explain Processing Workflow
Break down the 7-step process:
1. File discovery (scan input, exclude processed)
2. Audio loading (Librosa with timing/size reporting)
3. Silence analysis (advanced signal processing)
4. Chunk filtering (remove <5 second chunks)
5. FLAC optimization (FFmpeg conversion)
6. Export (organized subdirectories with metadata)
7. File management (move to `input/processed/`, optional with `--no-move`)
7. Document Output Structure
Explain the organized output format:
```
output/
├── audio_file1/
│ ├── metadata/ (processing_metadata.json, chunks.csv, processing_report.txt)
│ ├── audio_file1_full_16k.flac (complete optimized)
│ └── audio_file1_chunk01_16k.flac (individual splits)
```
8. Clarify CLI Features
Document Typer-based interface capabilities:
**Interactive configuration**: Step-by-step parameter setup with visual tables**Subcommands**: `process`, `config`, `optimize`, `analyze`**UX enhancements**: Rich formatting, type-safe Pydantic validation, dry-run mode**Configuration**: YAML/JSON support with command-line overrides9. Note Important Processing Details
Highlight critical behaviors:
**Chunk count**: Session summary excludes full optimized file (reports actual splits only)**File management**: Automatic move to `processed/` after success (prevents data loss)**Subsequent runs**: Auto-skip files in `processed` subdirectory10. Apply Git Commit Strategy
When committing changes to this project:
Omit Claude signatures and "Generated with Claude Code" attributionWrite concise, descriptive messages (what changed and why)Follow existing project commit conventionsUsage Examples
**Parse architecture for a new contributor:**
Extract core parameters → silence detection rule → file structure → CLI commands**Prepare for audio processing task:**
Review FLAC optimization strategy → understand 16kHz/mono rationale → check output structure**Debug processing workflow:**
Map 7-step workflow → identify chunk filtering logic → review file management behaviorConstraints
**Source specificity**: This documentation is tailored to the audio_processor project; parameters and architecture are project-specific**CLI focus**: Emphasizes Typer-based `audio_splitter_cli.py` as recommended interface**FLAC optimization**: Hard-coded for speech transcription use case (16kHz mono)**Silence rule**: Critical 25-second boundary placement logic is non-configurableNotes
The project uses `uv` for dependency management (not pip)FFmpeg is a system dependency (not a Python package)Rich formatting and progress bars require terminal supportConfiguration validation via Pydantic prevents invalid parameter combinations