Troubleshooting

Run bx-audio doctor first. Then find your error here.

Start with:

bx-audio doctor

It checks Java, java.desktop, MP3, FFmpeg, the sound card, the examples, the MiniServer and the speech setup, and says what to do about each problem. Set BX_AUDIO_DEBUG=1 to see the full stack trace of an error instead of one line.

MP3

"MP3 ... needs ..." or MP3 calls fail. MP3 reading uses JLayer and writing uses jump3r, two jars in the module's libs/ folder, and writing needs the JDK's java.desktop module. Use a full JDK, not a stripped JRE. Without them WAV and FLAC still work.

"sample rate ... audioResample". MP3 has a fixed list of sample rates: 8, 11.025, 12, 16, 22.05, 24, 32, 44.1 and 48 kHz. Resample before saving: audioSave( audioResample( audio, 44100 ), "x.mp3" ).

FFmpeg

"... needs FFmpeg, which was not found." OGG, Opus, AAC, M4A, video files and audioMux need FFmpeg. Run bx-audio ffmpeg install to download one, or install FFmpeg so it is on the PATH, or set the ffmpeg setting. If autoInstall is false, the module never downloads it for you.

"The configured FFmpeg ... was not found or does not run." The ffmpeg setting or BX_AUDIO_FFMPEG points to something that is not FFmpeg. Fix or clear it. A configured path never falls back silently to another FFmpeg.

"FFmpeg failed: ..." The message after it is FFmpeg's own. The usual causes are a missing encoder (an old or minimal FFmpeg without libvorbis, libopus or aac; bx-audio ffmpeg lists the encoders it has) and a file that is not media.

There is no download for this computer. Downloads exist for Linux and macOS on amd64 and arm64 and Windows on amd64. Install FFmpeg yourself on other systems.

The download failed its check. Every FFmpeg, speech engine and voice file is checked against a size and checksum. A mismatch deletes the file and stops: run the command again, and if it persists, your network may be rewriting downloads.

Speech

"The text to speech engine is not installed." autoInstall is false, or you passed autoInstall=false. Run bx-audio install engine and bx-audio install joe.

"The voice [x] is not offered: ..." The voice is in the collection but not offered. The message says why, and Voices lists them all.

"Unknown voice [x]". Use a name from bx-audio voices. A short name must be unique: ljspeech comes in two qualities, so use en_US-ljspeech-medium.

The first call takes a long time. It is downloading about 210 MB. Pass onProgress to audioSpeak to show it, or run bx-audio install engine joe ahead of time.

Speech sounds slightly different on another machine. The model runs the same, but it is floating point on a native library, so tiny differences are possible. Everything else in the module is bit for bit repeatable.

Playing sound

"There is no audio output device to play to." The computer has no sound card or the JVM cannot see one (a server, a container, a CI machine). Use audioMixer( output="memory" ) and render( seconds ) to get the audio, or output="null" to keep time without sound.

Nothing is heard but there is no error. The system output may be muted or set to another device. bx-audio play file.wav is the simplest test.

Time stretch and pitch

Stretched music sounds rough or echoey. Keep changes within about 25 percent. For larger changes, cut or loop the music instead (audioLoopify).

A shifted voice sounds like someone else. Pitch shifting moves the formants of a voice with the pitch. Keep it within a few semitones.

Files and paths

Relative paths. The command line resolves paths against the folder you run it in. In scripts, they follow BoxLang's own rules for the working directory.

"... positional and named arguments". BoxLang does not allow both in one call. Use all positional or all named arguments.

Storage

The disk is filling up. bx-audio where shows what the module keeps and bx-audio clean voices --yes frees it, see Storage.

Still stuck

Open an issue at github.com/ortus-boxlang/bx-audio with the output of bx-audio doctor and bx-audio version.