Auphonic Audio Optimization

Optimize audio files using the Auphonic API. Uploads a file, processes it with a user-selected preset (leveling, noise reduction, loudness normalization, etc.), and downloads the optimized result.

Process

Step 1: Determine Working Directory

Ask the user which directory contains the audio file they want to optimize. This will be used as the --project-dir argument. If the user's request already includes a path or enough context to infer it, confirm rather than re-asking.

Step 2: Select Preset

Check if a default preset is already saved:

python3 .claude/skills/auphonic-optimize/scripts/list_presets.py --show-saved

If a default exists: The script prints {"status": "ok", "uuid": "...", "name": "..."}. Confirm with the user: "Using preset {name}. Want to use a different one?" If they confirm or don't object, proceed to Step 3.
If no default: The script prints {"status": "no_default"}. Continue below to fetch and select.

Fetch available presets from Auphonic:

python3 .claude/skills/auphonic-optimize/scripts/list_presets.py

The script returns a JSON array of presets:

[
  {"uuid": "ceigtvDv8jH6NaK52Z5eXH", "name": "My Podcast Preset", "created": "2026-01-15", "is_multitrack": false},
  {"uuid": "9KN6czHvcrVeYWex5aQz59", "name": "Video Audio Cleanup", "created": "2026-02-01", "is_multitrack": false}
]

Present the presets in a numbered list and ask the user to pick one. Then save their choice as the default:

python3 .claude/skills/auphonic-optimize/scripts/list_presets.py --save "{selected_uuid}"

This stores the preset in config.json so it's remembered for next time.

Step 3: Select Audio File

Ask the user which audio file to optimize. If they've already specified a file, confirm it. Otherwise, you can list audio files in the working directory to help them choose:

find {project_dir} -maxdepth 2 -type f \( -name "*.mp3" -o -name "*.wav" -o -name "*.m4a" -o -name "*.aac" -o -name "*.flac" -o -name "*.ogg" -o -name "*.opus" \) 2>/dev/null

Present any found files to the user and ask which one to optimize. If only one audio file exists, confirm it with the user.

Step 4: Optimize

Run the optimization script. The --file argument is a path relative to --project-dir:

python3 .claude/skills/auphonic-optimize/scripts/optimize_audio.py \
  --file "{relative_path_to_file}" \
  --project-dir "{project_dir}"

To use a specific preset (overriding the saved default):

python3 .claude/skills/auphonic-optimize/scripts/optimize_audio.py \
  --file "{relative_path_to_file}" \
  --project-dir "{project_dir}" \
  --preset "{preset_uuid}"

To set a custom production title:

python3 .claude/skills/auphonic-optimize/scripts/optimize_audio.py \
  --file "{relative_path_to_file}" \
  --project-dir "{project_dir}" \
  --title "My Custom Title"

To change the output directory (default is audio/optimized):

python3 .claude/skills/auphonic-optimize/scripts/optimize_audio.py \
  --file "{relative_path_to_file}" \
  --project-dir "{project_dir}" \
  --output-dir "audio/final"

The script will:

Upload the file to Auphonic and start processing
Poll for completion every 10 seconds (up to 10 minutes)
Download the optimized output file(s)
Update file_index.json with origin metadata
Print a JSON summary

Keep the user informed of progress — the script prints status updates to stderr during upload, processing, and download.

Step 5: Report Results

The script outputs a JSON summary:

{
  "status": "ok",
  "production_uuid": "X2bUTQ8z888YaKukkU6vfJ",
  "preset": "ceigtvDv8jH6NaK52Z5eXH",
  "input_file": "raw/recording.mp3",
  "output_files": [
    {"filename": "recording.mp3", "format": "mp3", "size": "12.4 MB", "path": "my-project/audio/optimized/recording.mp3"}
  ],
  "duration": "00:15:32.100",
  "warnings": null,
  "audio_stats": {
    "input_loudness": "-22.5 LUFS",
    "input_snr": "28.3 dB",
    "output_loudness": "-16.0 LUFS",
    "output_peak": "-1.0 dBTP",
    "cuts_filler": "12 cuts (2.1%)",
    "cuts_silence": "8 cuts (1.5%)"
  }
}

Summarize to the user:

Where the optimized file was saved
Before/after loudness levels (if available in audio_stats)
Any cuts applied (filler words, silence)
Any warnings from Auphonic
The Auphonic production UUID for reference

Switching Presets

If the user wants to switch to a different preset mid-session, re-run the preset listing and save:

python3 .claude/skills/auphonic-optimize/scripts/list_presets.py
python3 .claude/skills/auphonic-optimize/scripts/list_presets.py --save "{new_uuid}"

Examples

Basic optimization with saved preset:

python3 .claude/skills/auphonic-optimize/scripts/optimize_audio.py \
  --file "raw/voiceover-take-3.wav" \
  --project-dir "my-project"

With explicit preset and title:

python3 .claude/skills/auphonic-optimize/scripts/optimize_audio.py \
  --file "raw/interview-raw.mp3" \
  --project-dir "my-project" \
  --preset "9KN6czHvcrVeYWex5aQz59" \
  --title "Interview with Guest"

Output to a custom directory:

python3 .claude/skills/auphonic-optimize/scripts/optimize_audio.py \
  --file "raw/podcast-episode.mp3" \
  --project-dir "my-project" \
  --output-dir "audio/final"

Supported Audio Formats

Extension	Format
`.mp3`	MP3
`.wav`	WAV
`.m4a`	AAC / ALAC
`.aac`	AAC
`.flac`	FLAC
`.ogg`	Ogg Vorbis
`.opus`	Opus
`.wma`	WMA

Troubleshooting

Issue	Fix
"AUPHONIC_API_KEY not set"	Add `AUPHONIC_API_KEY=your_key` to `.env` at the repo root. Get your key from Auphonic Account Settings.
"No default preset saved"	Run `list_presets.py` to see available presets, then `list_presets.py --save UUID` to set one.
"Preset UUID not found"	The UUID doesn't match any preset in your Auphonic account. Run `list_presets.py` to see valid UUIDs.
"Production timed out"	Large files (>1 hour) may take longer. The script polls for up to 10 minutes. For very long files, check the Auphonic status page directly.
"Production failed"	Check the error message. Common causes: unsupported format, corrupted file, or account credit limit reached.
Wrong output format	Output format is determined by the Auphonic preset. Edit your preset at auphonic.com/engine/presets to change output formats.