Introduction
For almost two decades, Rockbox has allowed users to modify the user interfaces of their music players. Over this time, functionality has evolved and matured into an intricate system of possibilities. The theming system today provides users with an incredible amount of freedom and control in a simple and performant manner.
Despite this however, the barrier for entry has historically been quite high. While places like the Rockbox Manual provided some explanations of core concepts, most people often resorted to learning from existing themes and experimentation through trial and error.
I myself began making themes in 2022. Learning from the fantastically documented Interpod series from Christian Soffke, and the bold, experimental FreshOS from Yuuiko. When working on my own theme designs, I sought to explore the boundaries and learn as much of the Theme Engine’s intricacies and quirks. Through this I refined many of the experiments of others and developed a clean, modern approach to building Rockbox themes.
Ultimately, my goal with this book is to break down the core methods of making Rockbox themes into simple and easy to understand concepts. Walking you through each one as we build a functioning theme together using the same process I do. By the end, you’ll have a beautiful theme, but also the knowledge and skills to go out and realise your own Rockbox Theme designs.
What you’ll need
Creating themes doesn’t require any specialist software. Really all you will need is a basic text editor, software to design and edit images in and a device to test on.
You can use any text editor you like, since our theme will be made from simple text files. I myself use GNOME’s default Text Editor for linux, I added syntax highlighting to their engine it uses which improves the readability of theme code. If you’re interested in adding syntax highlighting to other code editors please check out the repo I created for this.
I use Inkscape to design my themes, and we’ll be using it here in this book as it’s free and highly capable. However you can easily replace this with Affinity Designer, Adobe Illustrator or even UI Mockup tools like Figma.
We’ll be using GIMP for editing our assets, again being free with all the capabilities we need but easy to replace with a tool you may be more familiar with.
Lastly, while not strictly neccesary, I highly recommend checking out the Ui Simulator as an alternative to using a device to test on. It allows for must faster iteration and can provide detailed errors from the command line which can be helpful if you make a mistake.
Basic Terminology
There is no concrete terminology used when talking about themes, but there’s been some loose terms used over the years that I will attempt to frame here.
- Theming Engine:: A common term used to describe the internal system which manages the rendering of theme files.
- WPS: While Playing Screen. The name given to the music player part of a theme.
- SBS: Base Skin. The part of a theme handling menus and the quicksettings screen.
- FMS: FM Screen. The part of a theme that manages the FM Radio player.
- Tag or Theme Tag: The part of the markup system controlling content on screen.
- Viewport: Content sandboxes in themes. We’ll go into more detail on these next chapter.
Theme files
For each instance of the WPS, SBS and FMS mentioned above, a text file is used to code these part of the themes. Each file is saved with a corresponding file ending that Rockbox can read, for example a WPS theme file would be named ‘filename.wps’. These files live inside the .rockbox directory of your device, in a folder named ‘wps’.
To manage these files, and tell Rockbox what to load, there is another folder on your device called ’themes’. Inside here we find config files typically titled ‘themename.cfg’. This is what allows your theme to appear in the theme selection menu on your device, and ties together all the parts that make up your theme. It includes the location of WPS, SBS, FMS and icon files, as well as the default fonts, colours and other settings.
Font files are contained in a fonts folder in the .rockbox directory of your device. You don’t in fact need to create custom fonts for your theme, and can make use of any existing fonts in this folder that are installed as part of rockbox. Fonts are called by referring to their filename.
Assets, image files you load for the visuals of your theme, are stored in a folder named after your theme inside the wps folder. The name should be the exact same name used for the config file, and should be used across all theme files.
Images themselves are exclusively in the bmp format, however there is no need to worry about this yet as there will be an entire chapter dedicated to them.
What’s next?
Over the next chapters, we will start with a blank slate. Working from nothing, we will cover the core concepts of theme creation from scratch. Each concept will be followed by an Exercise chapter to help you gain confidence in writing themes. I highly recommend following along, if you can, to get a good feel for writing themes.
