dev builds
themes manual
device status forums
mailing lists
IRC bugs
dev guide

Search | Go
Wiki > Main > RockboxUtility > RockboxUtilityDevelopment

Development of Rockbox Utility


Open Tasks in the tracker

further enhancements

What? Status?
clean orphan files could be done by automatically performing an uninstallation before updating
install info cleanup possibility to wipe all files that are marked as outdated in the info window / all files that don't match a specific (read: the current) version)
Device detection Auto detection should probably display directly what was found; at least the highlighting should be more prominent (currently very faint on laptop LCD)
Accessibility Accessibility in rbutil needs improvement. Most of those isses are Qt issues. - (FS#10205)

Milestone 3: additions / ideas

Some of the following could be implemented with plugins. -- Qt supports plugins, but it hasn't figured out how to make use of that. Its also unclear which functionality should go into plugins.

What? How? Status?
Scrobbler submission basically a frontend for libscrobbler  
tagnavi_custom.config generator    
default configuration provide some reasonable defaults for config.cfg  
video conversion do it like WinFF  
local repository do we really want such a function? Offline mode does something similar  
Configfile editor A Editor for Rockbox config files  
Install/ uninstall Support for multiple devices would be nice (perhaps use some sort of (quasi-)unique device ID?)  
Translation Support for editing .lang files in a user friendly way
There's an online tool available at so having support for this in Rockbox Utility would only duplicate work
UI Rework see below  
Talkfile generation for database    

How To Compile

If you want to work on RockboxUtility clone the rockbox.git repository. RockboxUtility lives in the subfolder utils/rbutilqt. You can also use the script utils/common/ for building or creating a source tarball, however, this is intended for building releases and not suited if you intend to develop on RockboxUtility.

You have to have Qt Version 5.12 or higher installed. Building uses cmake. Building in-tree is not supported.
  • Create a build folder somewhere outside of the source tree and change to that. The recommended location for the build folder is in the rockbox source folder. Then you run the command cmake <path/to/utils-folder> followed by make in the build folder.

  • The complete path to the sources and build folders must not contain spaces!
  • To explicitly specify the build type append -DCMAKE_BUILD_TYPE=Release or -DCMAKE_BUILD_TYPE=Debug to the cmake call.
  • If your Qt installation is not in globally available (usually the case on Windows and MacOS, on Linux this typically only happens if you installed Qt separately from your distro packages) append -DCMAKE_PREFIX_PATH=<path/to/qt/base/folder> to the cmake call.
  • On Windows you need to use MinGW to build. While Rockbox Utility itself would compile with Visual Studio some of the libraries won't.
  • Build targets:
    • all (default target): builds Rockbox Utility and some other tools.
    • RockboxUtility: builds only Rockbox Utility
    • deploy_RockboxUtility: builds a deployable package (Windows: zip, MacOS: dmg, Linux: AppImage)
    • deploy: builds deployable packages for all tools.

How to Translate

Qt supports I18N and Rockbox Utility uses this. To translate RockboxUtility Qt's i18n tools are used.

Create a new translation

  • add a new file to the RBUTIL_TS_FILES line in utils/rbutilqt/CMakeLists.txt.
  • run =lupdate utils/rbutilqt/ -ts utils/rbutilqt/lang/rbutil_XX.ts
  • add the new file to utils/rbutilqt/rbutil-lang.qrc
  • update the newly created translation file as described below.

Updating an existing translation

  • get the Rockbox Utility source tree, run lupdate utils/rbutilqt -ts utils/rbutilqt/lang/rbutil_*.ts to update all existing translations with new strings (you can skip this if there are no new strings or you don't want to handle that case).
  • get the lang/rbutil_*.ts file you're interested in and edit it with Qt Linguist (you can also edit it manually -- it's an xml format).

Testing new translations

  • run lrelease to convert the *.ts file to the *.qm format that is used for I18N.
  • put the resulting *.qm file in the same folder as the executable. Rockbox Utility will then detect the new translation and allow you to use it.
  • or add the resulting *.qm file in rbutil-lang.qrc and the language file will be built into the binary.
  • and don't forget to post the *.ts file to the tracker so we can include it wink

Translation status

Note: this table is generated using the script and updated in the wiki manually. Do not edit the table manually, such changes will get lost on the next update with the script.
Translation status as of revision a490ff896f 2022-03-27 12:57:48 +0200
Language Language Code Translations Finished Unfinished Untranslated Updated Done
Czech cs 669 656 13 35 2021-12-15 21:04:28 +0100 95.0% #########+
German de 702 702 0 2 2022-03-27 12:57:48 +0200 99.7% #########+
Finnish fi 240 195 45 438 2021-12-15 21:04:28 +0100 35.4% ###+
French fr 650 637 13 54 2021-12-15 21:04:28 +0100 92.3% #########
Greek gr 344 284 60 360 2021-12-15 21:04:28 +0100 48.9% ####+
Hebrew he 474 415 59 230 2021-12-15 21:04:28 +0100 67.3% ######+
Italian it 378 321 57 326 2021-12-15 21:04:28 +0100 53.7% #####
Japanese ja 476 417 59 228 2021-12-15 21:04:28 +0100 67.6% ######+
Dutch nl 649 635 14 55 2021-12-15 21:04:28 +0100 92.2% #########
Polish pl 650 460 190 54 2021-12-15 21:04:28 +0100 92.3% #########
Portuguese pt 344 284 60 360 2021-12-15 21:04:28 +0100 48.9% ####+
Portuguese (Brasileiro) pt_BR 493 444 49 212 2021-12-15 21:04:28 +0100 69.9% ######+
Russian ru 650 637 13 54 2021-12-15 21:04:28 +0100 92.3% #########
Turkish tr 161 131 30 543 2021-12-15 21:04:28 +0100 22.9% ##
Chinese zh_CN 160 125 35 518 2021-12-15 21:04:28 +0100 23.6% ##
Chinese (trad) zh_TW 143 119 24 561 2021-12-15 21:04:28 +0100 20.3% ##

How to add a new Target

To add a new target you have to edit the following files:
  • utils/rbutilqt/rbutil.ini - add a new target similar to whats already there.
If your Target has a new Bootloader installation method:
  • utils/rbutilqt/base/bootloaderinstallXYZ.{cpp,h} - add a new class which implements the virtual classes of BootloaderInstallBase (at least install and uninstall) and does the necessary things for your bootloader. Don't forget to add those files to rbutil/rbutilqt/rbutilqt.pri to have them compiling with rbutil
  • utils/rbutilqt/base/bootloaderinstallbase.cpp - createBootloaderInstaller : add a case for your new Bootloader class
  • OF patcher program is going in a new mkXYZboot directory. Don't forget to edit utils/CMakeLists.txt to have it included as a library (look for how other methods have been added) and utils/rbutilqt/CMakeLists.txt to link it.
  • utils/rbutilqt/base/bootloaderinstallbase.cpp : postinstallHints() if your target needs user info after bootloader installation, add it here.
If there are ways for your target to detect the mountpoint or, in case of duplicate USB-IDs, detect the correct Target:
  • utils/rbutilqt/base/autodetection.{cpp,h} - edit so it also detects your specific files/folders or calls your specific detection method.

How to add a new TTS Engine

The TTS Engines are in base/tts.{cpp,h}. Add your new Engine to the list in initTTSList() and the switch in getTTS().

If your new engine is a simple external executable, you can add a template line to constructor of TTSExes and you are done.

If you have to interface your TTS Engine via another way, or want to give more options to the user, you have to create a new TTS Class which inherits from TTSBase. You will have to implement at least the following functions:
  • voice - generate a wavfile out of the given parameters
  • start - startup your engine
  • stop - stop your engine
  • configOk() - should return true, when everything setting is correct.
  • generateSettings() - generate settings-objects for your settings for display
  • saveSettings() - save the generated settings-objects to permanent storage.
To display settings, the TTS Classes implements the EncTtsSettingInterface which you can find in base/encttssettings.h/cpp. In the generateSetting() function you should create EncTtsSetting objects for all your settings. Each Setting contains the following Information:
  • The type of the Setting (bool,double,int,string,readonlystring,stringlist)
  • The name of the Setting
  • The current value
  • If it is a stringlist, the list of strings
  • If it is a int or double, the min and max values
  • If the setting needs a refresh or browse button
You can connect to the following signals:
  • refresh() - if you want to be noticed if the user clicks the refresh button.
  • dataChanged() - if you want to be noticed when ever the data changes
Add your newly generated objects with insertSetting() to the internal list. insertSetting() also takes a ID, which you can use to retrieve the object again in the saveSettings object.


All supported devices can be detected automatically. Rockbox Utility will display a warning when autodetection wasn't successful; you can always select your device manually. If you installed Rockbox once it can get detected via the file /.rockbox/rockbox-info.txt. This will work on all devices. See DeviceDetection for further details.

Resolving mountpoints

This relies on detecting the player first (see paragraph above). The following table list when / how we can resolve the mountpoint afterwards. This table only holds supported players; all supported player can now (as of 2008-04-03) be detected reliably. ALERT! denotes a possible way of resolving that hasn't been implemented yet. Once Rockbox is installed mountpoint resolving using rockbox-info.txt will always work.
Brand Player Windows Linux OS X
Apple all Ipods DONE resolving from drive UNC path figured by ipodpatcher (fallback: check for iPod_Control folder) DONE device node known by ipodpatcher, resolving using mtab DONE same as linux
Archos all DONE detect some specific files (firmware image on disk, magic in firmware file) DONE same DONE same
Cowon X5, M5 choice-no unknown (no specific file to check for) choice-no same choice-no same
Iriver H100, H300 choice-no only detection based on USB possible, currently there is no way known to resolve USB PID -> mountpoint choice-no same choice-no same
Iriver H10 ALERT! possible recognizing the bootloader file location ALERT! same ALERT! same
Packard Bell Vibe 500 ALERT! possible recognizing the bootloader file location ALERT! same ALERT! same
Sandisk e200, c200 DONE resolving from drive UNC path figured by sansapatcher DONE device node known by sansapatcher, resolving using mtab DONE same as linux
Olympus m:robe 100 ALERT! possible looking for bootloader file ALERT! same ALERT! same
Toshiba Gigabeat ALERT! possible searching for bootloader file ALERT! same ALERT! same


Brief release checklist:
  1. update the version info in version.h and Info.plist and commit them.
  2. tag git: git tag -a rbutil_ <commit>; git push --tags
  3. run common/ to create the source archive.
  4. build from a clean tree with make deploy_RockboxUtility. This builds a zip (Windows), AppImage (Linux), dmg (MacOS)
  5. Put the result to some public location and ping someone with access to the download server


This is the Qt version of Rockbox Utility. It supersedes the older wxwidgets based version which isn't maintained anymore and has therefore been removed from svn.

r101 - 27 Mar 2022 - 18:57:05 - DominikRiebeling

Copyright © by the contributing authors.