Building an Explicit Content Filter for Rockbox

The Problem

I run Rockbox on a modded iPod Classic 7th Gen (iFlash adapter, 250GB SD). Great firmware, but it has zero concept of explicit content. No parental controls, no filtering, no visual indicator. If you’re at work or around family, you’re rolling the dice on every shuffle.

Streaming services solved this years ago. Why can’t a local music player?

The Solution

I built rockbox-explicit-filter, an automated system that:

1. Scans your music library and looks up every track against the Deezer and YouTube Music APIs (zero API keys needed)
2. Tags each file with explicit=yes or explicit=no in the comment metadata field
3. Adds filtered database views to Rockbox so you can browse as “Clean Library”, “Full Library”, or “Explicit Only”
4. Shows a red “Explicit” badge on the Now Playing screen for tagged tracks

Clean tracks get full-width scrolling titles. Explicit tracks have a narrower title to make room for the badge. It’s seamless.

Technical Highlights

• Zero-config API lookups: Deezer’s search API returns an explicit_lyrics boolean with no authentication. YouTube Music serves as a fallback/validation source.
• Non-destructive tagging: Only the comment and grouping metadata fields are modified. Audio data, artist, title, album art, and ReplayGain are all untouched. Safe for Lidarr/Sonarr/Plex users.
• Rockbox WPS integration: Uses %iC (comment tag) with %ss() substring extraction for conditional display. The %ik (grouping) tag doesn’t actually work on iPod 6G targets, a finding I documented for the community.
• Incremental processing: Re-run the tagger as your library grows. Already-tagged files are skipped automatically.

What I Learned

The biggest challenge wasn’t the API integration or the Python scripting. It was understanding Rockbox’s WPS (While Playing Screen) theme engine. The documentation is sparse, behavior varies by target device, and some tags that should work simply don’t. Finding that %ik fails on iPod Classic while %iC with %ss() works perfectly took real debugging on hardware.

What’s Next

• M4A/OGG format support
• Universal theme patcher for any Rockbox WPS theme
• Auto-skip mode for work/family environments
• Lyrics-based detection via Genius API

The project is open source and MIT licensed. If you run Rockbox, give it a try.

View on GitHub