Troubleshooting

Export problems

MP3 cannot be selected, or only MP3 export fails

MP3 output requires the LAME (libmp3lame) shared library. When it is not installed, the MP3 option is disabled in the GUI and only MP3 output fails in the CLI. Reading MP3 files and writing other formats are unaffected.

See Getting Started for installation instructions.

AAC exports fine, but HE-AAC or VBR fails

AAC export uses the OS-native encoder, which has coverage limits.

• The Windows OS-native encoder supports only AAC-LC CBR at 96/128/160/192 kbps and 44.1/48 kHz
• The macOS OS-native encoder does not support AAC-LC at 88.2/96 kHz

Settings outside those ranges require the libfdk-aac shared library. With --aac-encoder auto (the default) in the CLI, unsupported settings fall back to libfdk-aac automatically and error out when it is not installed.

An exported AAC file shows a longer duration than the source

The container is probably ADTS (.aac). Only M4A can carry accurate duration information (gapless metadata); ADTS has no way to express it, so some players show the file as longer by the encoder delay.

To keep the duration accurate, choose M4A (MP4) as the Container (--format m4a in the CLI).

The loop I set is missing from the exported file

Because MP3 and AAC are lossy formats, loop metadata and comments are not written. To carry a loop forward, use WAV / AIFF (loop metadata) or FLAC / OGG (loop comments).

If you are writing loops to FLAC or OGG but the importing tool does not recognize them, check that the comment key names in Start Key / End Key / Length Key match what that tool expects.

Tags added with --comment disappear

Tags added with --comment are preserved only for FLAC / Ogg Vorbis. They are discarded when writing WAV / AIFF / MP3 / AAC.

The overwrite confirmation appears every time

Enable Overwrite existing files to overwrite without confirmation. To make that the default, enable Overwrite existing files by default in Bounce under Preferences. In the CLI, add --force.

Loudness problems

Files do not reach the target LUFS, or a warning appears after applying

With True Peak Limiter off (the default), the gain is capped so the true peak stays within Max True Peak. On peaky material that can leave files short of the target loudness, and those files are reported as warnings after applying.

To reach the target anyway, enable True Peak Limiter — --op loudness ... limiter=on in the CLI. See Matching Loudness for choosing a Release to match your material.

The limiter makes the audio sound wrong

The Release setting may not match the material. Fast (30 ms) suits percussive material such as rapid clicks, reducing pumping and loudness loss, while Slow (300 ms) suits bass-heavy material, avoiding distortion.

The Loudness column stays at Loading...

The analysis is still running after loading. Until it finishes, the loudness timeline in the detail view also shows Loudness: Loading.... Values appear automatically when it completes.

Controls that will not respond

The detail view will not open, or playback is unavailable

Playback and the detail view are available only while exactly one file is selected. Narrow the selection to a single file.

Shortcuts and editing operations do nothing

While a dialog is open, the usual shortcuts and editing operations are temporarily disabled. During loading and bouncing, a progress dialog stays in front and no other operations are possible until it completes.

Space starts playback partway through the file

A selection range is still active on the waveform. While a selection exists, Space plays only the selection. Press Esc to clear it and playback returns to normal.

Editing problems

Trimming disabled my loop

When the loop range lies entirely outside the kept range, the loop is disabled. Undo restores it. A loop that overlaps the kept range is remapped onto the new timeline automatically.

The CLI behaves the same way: a loop specified before trim that falls entirely outside the trim range is discarded with a warning.

My fades look like they disappeared after trimming

They did not. Fade-in and fade-out always apply to the beginning and the end of what you currently hear, so after a trim they re-attach to the edges of the kept range. See Editing Waveforms.

The fade length will not go any higher

The maximum fade length is the file’s effective length. While a trim is active, the trimmed length is the maximum.

I want to see what I trimmed away

Enable Full Timeline for Trimmed Files in the View menu (Windows: Ctrl+Shift+T, macOS: Cmd+Shift+T). The whole source timeline is shown with the trimmed-away regions dimmed. Right-click a dimmed region to choose Clear Trim.

There is a click at the loop seam

Enable Snap loop boundaries to nearby zero crossings in General under Preferences, and loop boundaries snap to a nearby zero crossing when confirmed.

Loading problems

Dropped files are not added to the list

Files that are already in the list, and duplicates among the files selected at the same time, are not added again.

An AIFF file will not load

For AIFF-C (AIFC), the readable compression types are plain AIFF, NONE / twos / in16 / in24 / in32, sowt, and fl32. Compressed codecs and 64-bit float such as ulaw, ima4, and fl64 are not supported.

I removed a file from the list by mistake

Delete / Backspace removes only the list entry — the original audio file is not deleted. Just load it again.

CLI problems

A warning appears on Windows, or the executable is blocked

The Windows build of the CLI is not code-signed. SmartScreen, antivirus software, or your organization’s security policy may therefore show a warning or block it from running.

--out produces an error

--out cannot be used with multiple inputs; use --out-dir. --out and --out-dir also cannot be specified together.

When --out is used, the output format must be determined by --format, --same-format, or the output path extension. When --format and --out are used together and --out has an extension, the extension must match --format.

--same-format and --format cannot be used together

They are mutually exclusive. Use --same-format to preserve the input format, or --format to set it explicitly.

A job file reports an unknown key

Job file keys differ from the CLI option names in a few places.

type values are fixed to snake_case, and any undefined key is an error.

A path in my job file cannot be found

Relative paths in a job file are resolved from the job file’s own directory, not from the current working directory.

--sample-rate is rejected

Only these standard values are accepted.

8000, 11025, 16000, 22050, 32000, 44100, 48000, 88200, 96000, 176400, 192000

probe exits non-zero

When some files fail to decode or measure, the rest are still processed and the exit code becomes non-zero. Look for entries with an error key in the --json output to find which inputs failed.

a9a_cli probe assets/*.wav --json | jq '.[] | select(.error != null)'

This page was written with generative AI.