StartupSFX - neoxic/ESCape32 GitHub Wiki

Starting with Rev14, the firmware supports customizable startup sound effects. This feature is intended for advanced users as it requires some knowledge of audio formats and sound processing. Moreover, it is the user's responsibility to check whether their audio data fits available flash memory. Update bootloader to the latest revision and enable bootloader write protection before flashing! Failure to do so may lead to bootloader corruption should you unintentionally flash beyond available flash memory capacity.

General steps

  1. Equalize, normalize and trim audio (adjust frequency response, maximize volume and remove silence).
  2. Convert audio to AU file format (8-bit linear PCM, mono).
  3. Combine your target firmware image with AU audio and flash it via regular firmware update.
  4. Enable startup sound by setting music to ~X (tilde before number) where X is volume (%) [0..100].

Tips:

Detailed steps

The following tutorial uses FFmpeg as a cross-platform command line tool. Any other sound processing software can be used instead.

Estimating sampling rate and duration

Calculate available flash memory by subtracting 4096 bytes (bootloader area) and your target firmware image size from the total flash memory size. See the corresponding MCU datasheet or refer to the following popular chips:

  • STM32F051K6 - 32768 bytes (insufficient)
  • STM32F051K8 - 65536 bytes
  • STM32G071GB - 131072 bytes
  • STM32G431KB - 131072 bytes
  • AT32F421K8 - 65536 bytes
  • GD32E230K8 - 65536 bytes
  • GD32F305K8 - 65536 bytes

Let's assume you have 100000 bytes available for startup sound. The length of 8-bit audio data is L = R * T bytes where R is sampling rate (Hz) and T is duration (seconds). Therefore, choosing R = 10000 will allow for up to 10 seconds of audio. Lowering R can increase maximum duration while decreasing sound quality as a trade-off.

Equalizing audio

Adjust frequency response emphasizing the midrange:

ffmpeg -i input.wav -ac 1 -af "firequalizer=gain_entry='entry(0,-30);entry(250,-8);entry(1K,0);entry(4K,0);entry(16K,-4)'" output.wav

The first argument of each entry() item is frequency (Hz) and the second argument is gain (dB). Feel free to experiment.

Normalizing audio

Detect maximum volume (replace /dev/null with NUL on Windows):

ffmpeg -i input.wav -ac 1 -af volumedetect -f null /dev/null

Output example:

...
[Parsed_volumedetect_0 @ 0x600000fe0420] max_volume: -1.2 dB
...

Apply the opposite volume gain (1.2dB in this case) to normalize to 0dB:

ffmpeg -i input.wav -ac 1 -af volume=1.2dB output.wav

Trimming audio

Remove silence at the beginning and end of an audio file:

ffmpeg -i input.wav -ac 1 -af silenceremove=1:0:-50dB:0:0:-1:0:-50dB:detection=peak output.wav

Converting audio to AU file format

Convert an audio file to AU file format, 8-bit linear PCM, mono (10kHz sampling rate for example):

ffmpeg -i input.wav -map_metadata -1 -c:a pcm_s8 -ac 1 -ar 10K output.au

The above command also prevents any metadata from migrating over to the output file to save space.

Combining firmware image with AU audio

Append an AU audio file to your target firmware image (ESCAPE1 for example):

cat ESCAPE1-rev14.0.bin output.au > firmware.bin

On Windows:

copy /b ESCAPE1-rev14.0.bin + output.au firmware.bin

Make sure the combined image will fit in your MCU's flash memory.

Step-by-step procedure

Replace input.wav with your audio filename and ESCAPE1-rev14.0.bin with your target firmware image filename.

On UNIX:

$ ffmpeg -i input.wav -ac 1 -af "firequalizer=gain_entry='entry(0,-30);entry(250,-8);entry(1K,0);entry(4K,0);entry(16K,-4)'" step1.wav
$ ffmpeg -i step1.wav -ac 1 -af volumedetect -f null /dev/null 2>&1 | grep max_volume
[Parsed_volumedetect_0 @ 0x600001f0aec0] max_volume: -1.2 dB
$ ffmpeg -i step1.wav -ac 1 -af volume=1.2dB step2.wav
$ ffmpeg -i step2.wav -ac 1 -af silenceremove=1:0:-50dB:0:0:-1:0:-50dB:detection=peak step3.wav
$ ffmpeg -i step3.wav -map_metadata -1 -c:a pcm_s8 -ac 1 -ar 10K output.au
$ cat ESCAPE1-rev14.0.bin output.au > firmware.bin

On Windows:

> ffmpeg -i input.wav -ac 1 -af "firequalizer=gain_entry='entry(0,-30);entry(250,-8);entry(1K,0);entry(4K,0);entry(16K,-4)'" step1.wav
> ffmpeg -i step1.wav -ac 1 -af volumedetect -f null NUL
...
[Parsed_volumedetect_0 @ 0x600001f0aec0] max_volume: -1.2 dB
...
> ffmpeg -i step1.wav -ac 1 -af volume=1.2dB step2.wav
> ffmpeg -i step2.wav -ac 1 -af silenceremove=1:0:-50dB:0:0:-1:0:-50dB:detection=peak step3.wav
> ffmpeg -i step3.wav -map_metadata -1 -c:a pcm_s8 -ac 1 -ar 10K output.au
> copy /b ESCAPE1-rev14.0.bin + output.au firmware.bin

Final steps

  • Update bootloader to the latest revision and enable bootloader write protection. (IMPORTANT!!!)
  • Flash the combined firmware image firmware.bin via regular firmware update.
  • Enable startup sound by setting music to a special value ~X (tilde before number) where X is volume (%) [0..100].