Working with MP3 Files

What the VS1053 can decode

The Touch Board’s VS1053B chip decodes:

Stick with MP3 unless you have a specific reason not to.

Recommended encoding settings

These settings work reliably across all tested files:

Avoid:

• Variable bit rate (VBR) — some VBR files cause stuttering on the VS1053
• Sample rates above 44100 Hz — not supported
• Very high bit rates (320 kbps) — no quality benefit and slower SD reads

Exporting from Audacity

Audacity is free and exports perfectly-formatted MP3 files:

1. Open your audio file in Audacity
2. File → Export → Export as MP3
3. In the options dialog:
   • Bit rate mode: Constant
   • Quality: 128 kbps
   • Variable speed: off
4. Name the file TRACK000 (Audacity adds .mp3 automatically)
5. Click Save, click OK on the ID3 tags dialog

Loop-compatible (gapless) encoding

If you want a sound to loop seamlessly without a gap at the join, you need gapless MP3 encoding. Most MP3 encoders add silence padding. Use LAME with the --nogap flag:

# Command line — encode multiple files gaplessly
lame --nogap file1.wav TRACK000.mp3
lame --nogap file2.wav TRACK001.mp3

Or use Audacity: trim silence at the start and end, then export at 44100 Hz. In code, use MP3player.setLoopPlayback(true) or re-trigger the track on release.

File size and SD card capacity

At 128 kbps:

• 1 minute of audio ≈ 960 KB ≈ 1 MB
• 12 tracks × 30 seconds = ~72 MB — comfortably fits on any card

Even a 1GB card holds over 2 hours of audio at 128 kbps. Card size is not a constraint for typical projects.

Batch preparation

For projects with many tracks, automate the preparation. Python + ffmpeg:

import os
import subprocess

source_dir = 'raw_audio'
output_dir = 'sd_card'
os.makedirs(output_dir, exist_ok=True)

files = sorted(os.listdir(source_dir))
for i, filename in enumerate(files):
    src  = os.path.join(source_dir, filename)
    dest = os.path.join(output_dir, f'TRACK{i:03d}.mp3')
    subprocess.run([
        'ffmpeg', '-i', src,
        '-codec:a', 'libmp3lame',
        '-b:a', '128k',
        '-ar', '44100',
        '-y', dest
    ])
    print(f'{filename} → TRACK{i:03d}.mp3')

Install ffmpeg: brew install ffmpeg (macOS) or sudo apt install ffmpeg (Linux).

Volume normalisation

Inconsistent recording levels mean some tracks are quiet, others loud. Normalise before encoding:

# ffmpeg loudness normalisation to -16 LUFS (broadcast standard)
ffmpeg -i input.wav -af loudnorm=I=-16:LRA=11:TP=-1.5 output.mp3

Or in Audacity: Effect → Loudness Normalization → -16 LUFS.

Stereo vs mono

The VS1053 outputs stereo audio. Stereo files use ~twice the SD bandwidth of mono. For most touch instrument sounds (single notes, short clips), mono is indistinguishable through a phone speaker and halves the file size. For ambient soundscapes or music with panning, keep stereo.

In Audacity: Tracks → Mix → Mix Stereo Down to Mono before exporting if you want mono.

Key takeaways

• Use 128 kbps CBR MP3 at 44100 Hz — the most reliable combination for the VS1053
• Avoid VBR encoding — it can cause stuttering
• Audacity’s Export as MP3 → Constant → 128 kbps is the simplest route
• Use ffmpeg for batch conversion of many files
• Normalise loudness to -16 LUFS for consistent playback volume
• Mono is fine for single-note sounds; saves file size and SD bandwidth