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

Search | Go
Wiki > Main > PluginUsability

Plugin Usability Guidelines

= * WARNING: These are not official guidelines, suggest and discuss at the end * =

General usability principles

Almost everybody has a notion on what usability is, but not many people can summarize it in a small number of principles. Luckily, the people at GNOME and Apple have done it before in their usability guides. I like the GNOME introduction best and will mark in bold the principles most important for Rockbox:

  • Design for People.
  • Don't Limit Your User Base.
  • Create a Match Between Your Application and the Real World.
  • Make Your Application Consistent.
  • Keep the User Informed.
  • Keep It Simple and Pretty.
  • Put the User in Control.
  • Forgive the User.
  • Provide Direct Manipulation.

Particular Rockbox principles

Rockbox is not a general purpose operating system or environment for full blown computers, so there are some particular principles that you should keep in mind while designing your plugins. I will elaborate on them later regarding particular aspects on plugin design.

People use Rockbox to hear their music

The most important point is that Rockbox is first and foremost for audio playback, so engrave this in your mind: people use Rockbox to hear music. Never think that your plugin is so wonderful that people will carry a jukebox only for playing your game or watching your demo. You should let people hear the music they carry on it, if your plugin won't work as expected without interrupting the music (be it for needing sound output or using so much CPU that the music decoder cannot cope) - apart from graphics demos - then your plugin is likely not suited for Rockbox. Even if you think your plugin will work much better stopping music playback you should allow the user to use it while listening to their music and make it a priority.

People also like to hear their music for a long period of time, so please try to be gentle with batteries. Minimize the time you boost the CPU and keep your hard disk access frequency as low as possible. You should also consider not getting people too far from their music. Trying to keep them in control of the music they are playing.

People use Rockbox on portable devices

Rockbox is designed to work on portables (apart from the UI simulator builds) and you should keep that in mind. Portables are meant to be carried on very different situations, and probably many of them won't allow the user to read small texts on a tiny screen or holding the jukebox with more than one hand. So try to minimize and optimize your button distribution and do not show information on very small pieces of screen, that includes most of the time reading text on screen. Nobody wants to be seen on the subway with a jukebox standing at 10 cm from your eyes and using two hands and a nose to control your plugin

Rockbox is multitarget

Rockbox runs on a very wide array of players (and the number is increasing) so please try to make your plugin work, and work well, on as many targets as possible. That requires thinking about the other targets, not just the one you use. You need to think about things like graphics, buttons, CPU speed, etc. And don't think your plugin is too big to be useful on the Recorders and Ondios, or even the H100, think that Rockbox started because owners of those players started coding it, so please, try not to leave anybody behind. Rockbox has plugins for the smaller targets that can play chess, jewels, do calendaring and even playing videos so most probably your plugin will also work for almost every target. If you don't have the time or skills to make it work on every target you can ask for help on the lists or IRC, but always code your plugin in a way that can be ported to the different targets.

Starting and finishing the plugin

There's something you must understand: probably about 90% of the users will only start your plugin once and quit immediately. Get over it; probably 5%, once they know what your plugin is about, won't care about your nice splash screen, your wonderfully worded initial help or your magnificently designed start menu. Get over it.

Please code your plugin to work nice for the vast majority of users. The most important thing is letting those 90% know what your plugin is about so they can discard it wisely and fast, and letting your precious recurring client to use your plugin immediately. Keeping that in mind you should start your plugin directly on the main screen, ready for action. That means playing, displaying info, whatever - and let the new user experience it. If your plugin is wisely designed almost everybody will be able to use it without help, and if that's not the case (as we will see later) he or she will always know how to get a menu, a help screen or quit. The recurring user will want to play or view your plugin immediately. Only a "Press MENU for menu or any key to start" is allowed if your plugin depends on fast user interaction, like the Brickmania or Metronome plugins.

And just the same goes for quitting. As we all know, an mp3 player is for hearing music on the go, so probably if someone wants to quit a plugin, he/she wants to quit right here and right now. Please allow quick exiting of your plugin, for the user will probably have good reasons for wanting to. Quitting should always be active, on the same standard button, and should be inmediate and unconditional - no exit question, no "Goodbye, my love".

But, what about forgiving users? If I quit with the touch of a button he will probably loose the current plugin status, and so will lose the time spent playing the game or lose any data entered. No, sir. Because quitting and starting again a plugin should be a transparent, zero stress action. You should make your plugin emulate a multitasking environment, saving any status info on quit and restoring it on start, without question, and only informing the user about this with a "Saving status" and "Restoring status" notification if you think it will take some time (e.g. writing to disk). That way, a recurrent user can start and quit the plugin any moment he wants without losing time and thus using any free time he has, be it on the road, at work or at home.


Buttons are the only input method for users, and they are scarce and change from one target to another, moreover, different buttons have different function from one screen to another even on the default playback application so buttons are the main reason for problems on new and even recurring users. Some people come to think their player has crashed but the real problem is that they cannot find the way out of a plugin, for example. So we must have some basic default buttons and try to be consistent on the other buttons we choose.

Mandatory default buttons

There should always be a QUIT button that, as we saw before, should take efect inmediatly and unconditionaly, one important thing is that you should try to have this button available at any time on your plugin execution as we don't know when will the real world get in the middle of enjoying your plugin.

Another mandatory button is the MENU/HELP one. If your plugin has a menu it should launch it, if there is no need for a menú there should be at least a help screen, with the name of the plugin, a brief description and the button asignements. Even if your plugin only shows a graphic demo and the only active buttons are QUIT and PLAYBACK_MENU a help screen is always good to keep Rockbox consistent and giving the user a sense of perceived stability of the system.

In order to keep the user close and in control of their music you should provide also if possible the option to enter the Playback Menu with a long press of the MENU/HELP button, that way he can change the volume or jump a song without getting out of the plugin and having to get again to the playback screen. If there is no option to have this (for example on the Ondio) you should always have a menu with this option and the help screen.

You should try to use the very same buttons for those three actions, this should be probable the first thing you should code on your plugin. These are the default ( please someone with other players check this as I have only used an iRiver ):

  Player Recorder Ondio iRiver iPod iAudio Gigabeat

Suggested buttons for typical actions

For the sake of consistency we add here a list of buttons for typical actions, we know that every plugin has different requirements and so these are only suggested. The only thing that should be pointed is the diference between Select and Action, while Select is a standalone event Action can be simultaneous with other buttons, think of it as the fire button ( please someone with other players check this as I have only used an iRiver ):

  Player Recorder Ondio iRiver iPod iAudio Gigabeat
Directions PLAY/STOP/+/- Arrows Arrows Arrows MENU/PLAY/LEFT/RIGHT Arrows Arrows
Action - ON - PLAY - PLAY A
Restart - - - REC - - -

Menus & Help Screens

Whenever your plugin need more actions than buttons are available (what in the case of the Ondio is almost always) you should add a menu to control them. All plugins should use the default menu system. Using the default menu system will give consistency to every plugin, it will use the default font (which is the one the user wants) and in the future it may be localizable and spoken and thus be available for non-english and blind users.

A typical menu should look like this, bracketed entries are optional:
  • Playback Menu - For controlling music playback
  • Resume - The same as exiting the menu
  • [Action1] - Execute action 1 (f.e. Restart)
  • [Action2] - Execute action 2 (f.e. Save position)
  • [Option1]
  • [Option2]
  • [High Scores] - If apropriate
  • [Reset Scores] - If apropriate
  • Help
  • [About]
  • Quit

All actions should go back to the plugin main screen inmediatly after activation. All options entries should open a screen for changing it much in the way the rest of the Rockbox option menus. If there are more thant two option entries there should be an "Options" entry and a secondary menu with all the available options.

The Help entry should open a help screen using the current default user font, this screen should contain the Plugin Title, a small description of it and the Button assignements ( How to make this scroll? I've never used text on plugins, please fix ). If you want to add some copyright, or splash screen or something like that for your plugin you can add an "About" entry on the menu, but this is not advised.


As we have said before, people use Rockbox on the go and screens are still quite small so you should try to optimize your graphics for every platform, using the most pixels on the screen and the most wise color to make your plugin aesthetic but still highly usable. This is a summary of the display capabilties of all the current targets:

Size Depth Jukebox Models Notes
11x2 Char Player  
112x64 1 Recorder, Ondio Anamorphic pixels, can do 4bits depth with grayscale lib
138x110 2 iPod Mini  
160x128 2 H1XX, iPod 4G H1XX can do 4bits depth with grayscale lib
160x128 16 X5  
176x132 16 iPod Nano  
220x176 16 H3XX, iPod Color  
240x320 16 Gigabeat  
320x240 16 iPod Video  

For a first release of a plugin it is suggested to design graphics at least for 112x64x2 (Recorder, Ondio), 138x110x2 (iPod Mini, H1XX and iPod 4G), 160x128x16 (X5 and iPod Nano) and 220x176 (all the rest) providing you make the code necessary for adding apropiate padding for the slightly bigger displays. That way your plugin will be quite usable on any target and allow other contributors to add the rest of the graphics resolution.

You should also keep in mind usability with regard to your color use on your plugin. On the B&W and gray displays you should take in account the fact that fast movements leaves a trail on the screen that may render your plugin not usable, the same must be said for black backgrounds that should be avoided on those targets. On the color targets you should also try not to convey information with colors only as there are many different kind of color blindness, use also shapes. In any target you should try to use the default background and foreground color if posible and try not to hard-code colors on the plugins if that can be avoided.

It's also important to add options to your plugin to keep the backlight on in case there will be long times without user interaction in order not to overuse the buttons just to keep light on while thinking on a game for example. This option should also be saved and restore on quit and start.


There shouldn't be really no need for sound output on a plugin on most cases. Maybe a beep() function on the plugin API for the targets that can help usability in some plugins that can take a time in respond like Chessbox and the like.

High scores

Keeping high scores is a good way for the user to see his advances and a way to make a game plugin more interesting so saving high scores is greatly advised. High scores should be saved (if changed) and restored on plugin quit and start. There should be a menu entry to display them (always with the user selected font) and another option to reset them with confirmation in order to prevent loosing them.

Suggestions and discussion here

  • Please note that the original author of this draft is a non-native english speaker, has only coded a plugin for Rockbox and owns only an iRiver iH-120 so try to be positive.
  • I feel that these guidelines will greatly improve the usability of the plugins. I suggest that a section concerning the HOLD button be added. If the hold button is activated, the user is not using the device. If the application is a game, it should be paused. The backlight should also be turned off when the device is on HOLD. A section addressing these issues should be added. - LukasSabota

r13 - 02 Apr 2021 - 20:46:07 - UnknownUser

Copyright © by the contributing authors.