Plugins are programs that Rockbox can load and run. Only one plugin can be loaded at a
time. Plugins have exclusive control over the user interface. This means you cannot switch
back and forth between a plugin and Rockbox. When a plugin is loaded, you need to exit
it to return to the Rockbox interface. Most plugins will not interfere with music
playback but some of them will stop playback while running. Plugins have the file
extension .rock. Most of them can be started from Browse Plugins in the Main
Menu.
Viewer plugins get started automatically by opening an associated file (i.e. text files), or from the Open with option on the Context Menu.
Dice is a simple dice rolling simulator. Select number and type of dice to roll in a menu and start by choosing “Roll Dice”. The result is shown as individual numbers as well as the total of the rolled dice.
Key | Action |
On | Roll dice again |
Menu | Quit |
|
Flipping the colour of the token under the cursor also flips the tokens above, below, left and right of the cursor. The aim is to end up with a screen containing tokens of only one colour.
Key | Action |
On / Menu / Minus / Plus | Move the cursor |
Play | Flip |
On+Minus | Shuffle |
On+Plus | Solve |
On+Play | Solve step by step |
Stop | Quit the game |
|
This is a jackpot slot machine game. At the beginning of the game you have 20$. Payouts are given when three matching symbols come up.
Key | Action |
On | Play |
Menu | Exit the game |
|
Rockblox is a Rockbox version of the classic falling blocks game from Russia. The aim of the game is to make the falling blocks of different shapes form full rows. Whenever a row is completed, it will be cleared away, and you gain points. For every ten lines completed, the game level increases, making the blocks fall faster. If the pile of blocks reaches the ceiling, the game is over.
Key | Action |
Stop+Menu | Restart game |
Minus | Move left |
Plus | Move right |
Menu | Move down |
On+Play | Rotate anticlockwise |
Play | Rotate clockwise |
On | Drop |
Stop | Quit |
|
The credits plugin scrolls the entire list of the names of all the Rockbox contributors after displaying the Rockbox logo and version. This plugin is called when selecting Version from the System section of the Rockbox main menu. Exit at any time by pressing Stop.
This is a rotating cube screen saver in 3D.
Key | Action |
On | Display at maximum frame rate |
Play | Pause |
Menu | Cycle draw mode |
On+Plus / On+Minus | Select axis to adjust |
Plus / Minus | Change speed/angle (speed can not be changed while paused) |
Stop | Quit |
|
Demo showing the Rockbox logo bouncing around the screen.
Key | Action |
Plus / Minus | Increase / decrease speed on the x-axis |
Play / Stop | Increase / decrease speed on the y-axis |
Menu or Long Menu | Quit |
|
This simple graphics demo draws a mosaic picture on the screen of the player.
Key | Action |
Play | Change the gap between the drawing lines. |
On | Restart the drawing process. |
Menu or Long Menu | Exits Mosaique demo |
|
This demo replicates snow falling on your screen. If you love winter, you will love this demo. Or maybe not. Press Menu or Long Menu to quit.
Viewers are plugins which are associated with specific file extensions. They cannot be run directly but are started by “playing” the associated file. Viewers are stored in the /.rockbox/rocks/viewers/ directory.
Note: Some viewer plugins can only be used by selecting the Open With... option from the Context Menu (see section 4.1.2).
Viewer Plugin | Associated filetype(s) | Context Menu only |
Shortcuts | .link | |
Chip-8 Emulator | .ch8 | |
Frotz | .z1 - .z8 | |
Image Viewer | .bmp, .jpg, .jpeg, .png | |
Lua scripting language | .lua | |
Search | .m3u, .m3u8 | x |
Sort | .* | x |
Text Viewer | .txt,.nfo, .* | |
VBRfix | .mp3 | x |
ZXBox | .tap, .tax, .sna, .z80 | |
Shopping list | .shopper | |
|
The Shortcuts Plugin allows you to jump to places within the file browser without having to navigate there manually. The plugin works with .link files. A .link file is just a text file with every line containing the name of the file or the directory you want to quickly jump to. All names should be full absolute names, i.e. they should start with a /. Directory names should also end with a /.
You can use your favourite text editor to create a .link file on the PC an then copy the file to the player. Or you can use the context menu on either a file or a directory in the file browser tree, and use the “Add to shortcuts” menu option. This will append a line with the full name of the file or the directory to the shortcuts.link file in the root directory of the player. (The file will be created if it does not exist yet.) You can later rename the automatically created shortcuts.link file or move it to another directory if you wish. Subsequent calls of the context menu will create it again.
To use a .link file just “play” it from the file browser. This will show you a list with the entries in the file. Selecting one of them will then exit the plugin and leave you within the directory selected, or with the file selected in the file browser. You can then play the file or do with it whatever you want. The file will not be “played” automatically.
If the .link file contains only one entry no list will be shown, you will directly jump to that location. The file shortcuts.link in the root directory is an exception. After “playing” it, the list will be shown even if the file contains just one entry.
If the list you are seeing is from shortcuts.link in the root directory, you can delete the selected entry by pressing Menu. Deleting entries from other .link files is not possible.
Placing the line “#Display last path segments=n” (where n is a number) in the beginning of a .link file will leave just the last n segments of the entries when they are shown. For example, if n is chosen to be 1, then the entry /MyMusic/collection/song.mp3 will be shown as song.mp3. This allows you to hide common path prefixes.
You can also provide a custom display name for each entry individually. To do so, append a tabulator character after the entry’s path followed by your custom name. That name will then be used for showing the entry. For example:
This plugin can be used on playlists. It searches through the playlist that it opened on looking for any occurrences of the string entered by the user. The results of this search are saved to a new playlist, search_results.m3u, within the same directory as the original playlist.
Shopper is a plugin which allows you to maintain reusable shopping lists. To create a list, use a text editor to write down a list of items (one per line; note that the line length should not exceed 40 characters) and save the file as <name>.shopper. If you want to separate the items you can do so by creating categories, which are prepended with ‘#’. To open a .shopper file just “play” it from the file browser.
Note that it isn’t possible to choose exact quantities, but you can create a number of entries with different quantities in the name of the item, such as for the apples in the above example.
There are two modes, edit mode and view mode. The edit mode shows all the items, and it allows you to select which of the items you want to buy. When you have finished selecting the items, use the menu to go to the view mode, and you will see only the items you wish to buy. If you ‘select’ an item in view mode then that item will be removed from the list.
When you exit Shopper the last view is saved, including which items you have selected, so if you re-open the shopping list it will be as you left it. There are additional menu options for clearing the list, selecting all items, showing and hiding the categories, toggling the categories, and displaying the playback menu.
Key | Action |
Play | Select or clear an item |
Menu or Long Play | Show menu |
Stop | Exit |
|
This plugin takes a file and sorts it in ascending alphabetical order. Case is ignored. This is useful for ordering playlists generated by the Create Playlist menu option (see section 5.8).
This is a Viewer for text files with word wrap. Just open a .txt or .nfo file to display it. The text viewer features controls to handle various styles of text formatting and has top-of-file and bottom-of-file buttons. You can view files without a .txt or .nfo extension by using Open with from the Context Menu (see section 4.1.2). You can also bookmark pages.
Key | Action |
Minus | Scroll-up |
Plus | Scroll-down |
Menu+Minus | Top of file (Narrow mode) / One screen left (Wide mode) |
Menu+Plus | Bottom of file (Narrow mode) / One screen right (Wide mode) |
Play | Toggle autoscroll |
On | Set/Reset bookmarks |
Menu | Enter menu |
Stop | Exit text viewer |
|
To add a bookmark, press On. The bookmark will be displayed as shown below. To delete the bookmark press the same button again.
This plugin offers a way to remove a theme. Open the Context Menu (see section 4.1.2) upon a theme.cfg file and select Open With... → theme_remove. Some files are not removed regardless of the Remove Options such as rockbox_default.wps.
One of the following options can be chosen for each setting.
This function scans a VBR (Variable Bitrate) MP3 file and updates/creates the Xing VBR header. The Xing header contains information about the VBR stream used to calculate average bit rate, time information and to more accurately fwd/rew in the stream. This function is especially useful when the playback of a file skips, fwd/rew does not work correctly or the time display is incorrect. To use this plugin, open the Context Menu (see section 4.1.2) upon a .mp3 file and select Open With…→ vbrfix.
Note: VBRfix can only run when music is turned off (since it uses the same memory as the player) and can take a while to complete if run on big files.
The Battery Benchmark plugin enables you to test your battery’s performance whilst using your player normally. Results can be submitted to the BatteryRuntime wiki page.
Once loaded, Battery Benchmark runs in the background recording various information about your battery to memory. A new point is written to memory every minute. Every time the disk is accessed for any reason (such as refilling the audio buffer, opening a directory or entering USB mode etc.) then the information in memory is written to disk. Once the memory becomes full (after many hours), then the data are written to disk anyway. This is done so that the data are not biased by excessive additional disk accesses. The file is written to the root directory of your player and is called battery_bench.txt. The plugin will continue to log info until:
Benchmarks can be resumed if you accidentally load a plugin, or turn off your player, so long as the log file battery_bench.txt is not deleted.
At the top of the battery_bench.txt file is various information on how to use the plugin, followed by the data themselves.
The log file can be used to tell you how long the battery lasted (with some limitations, see below), but it is most useful for graphing discharge curves in order to improve Rockbox’s estimation of battery level and time remaining. The battery log (battery_bench.txt) is in CSV format (comma separated variables) and thus can be easily imported into a spreadsheet or similar program.
As Battery Benchmark needs to write the data held in memory to disk in order to save them, it is possible that should Rockbox shut down due to low battery then there will not be enough power remaining to write the data to disk. Therefore all measurements since the previous save will be lost.
The chess clock plugin is designed to simulate a chess clock, but it can be used in any kind of game with up to ten players.
Key | Action |
Plus / Minus | Increase / decrease displayed Value |
Play | Move to next screen |
Stop | Move to previous screen |
|
The number of the current player is displayed on the top line. The time below is the time remaining for that round (and possibly also the total time left if different).
Keys are as follows:
Key | Action |
On | Exit plugin |
Stop | Restart round for the current player |
Play | Pause the time (press again to continue) |
Plus | Switch to next player |
Minus | Switch to previous player |
Menu | Open menu (Play to select.) |
|
From the menu it is possible to delete a player, modify the round time for the current player or set the total time for the game. When the round time is up for a player the message “ROUND UP!” is shown (press NEXT to continue). When the total time is up for a player the message “TIME UP!”is shown. The player will then be removed from the timer.
To use the plugin, firstly you need to have the dictionary files which contain the words (index) and their description – dict.index and dict.desc, respectively – on /.rockbox/rocks/apps/ folder.
The dictionary files can be created by yourself, or you can get them crafted from the web. More information can be found at PluginDict.
Now that you already have the two necessary files in place, you can launch the dict plugin (under Applications on the Browse plugins menu). The first thing you will see is the text input screen.
Type part of a word (or the whole word) or anything the dict files have a definition to and accept the text input. The plugin will search for matching entries on the dict.index file and display according description/meaning contained in the dict.desc file.
If no matches are found on the dictionary, a “Not found” message will be displayed and the plugin will exit. You can do another search by relaunching the plugin.
Disk Tidy deletes junk files commonly left behind by Windows, Linux and OS X after connecting your player over USB. Select the files you want to delete in the “Files to Clean” menu and select “Start Cleaning” to begin the process. The settings are stored in the plain text file .rockbox/rocks/apps/disktidy.config that is user-modifiable to allow custom entries to be added.
The asterisk character (“*”) can be used as a wild-card which will match any string; however
only the first asterisk will be recognised as a wild-card with any additional uses being taken as
literal.
Warning: Be careful when you use custom entries as you could accidentally delete important files.
Key | Action |
Stop | Exit / Abort |
|
Keybox is an encrypted password storage using the “Tiny Encryption Algorithm” with a key derived using md5.
To get started, start up the plugin and select Enter Keybox. The first time you enter Keybox you will be prompted for a master password and for confirmation of the master password. The master password is the password that you must use to access your stored passwords.
Once inside, enter the context menu by pressing Long Play. From the context menu you can create new entries, delete entries and edit entries. Each entry has a “title”, a “user name” and a “password”.
Selecting Reset Keybox from the main menu will delete the current list of passwords and a new, empty list will be created the next time you select Enter Keybox after prompting for a new master password. Entries are automatically saved when the plugin is exited.
Lamp is a simple plugin to use your player as a lamp (flashlight, torch). You get an empty screen with maximum brightness.
Key | Action |
Menu or Long Menu | Exit to menu |
|
This plugin helps you customizing the main menu (i.e. reorder or hide menu items). It changes the appropriate configuration file as described in section 11.1.1.
When you start the plugin, the available main menu items will be displayed. By pressing Play you open a menu with the following options:
You can leave the plugin without saving by pressing Stop.
Open a file, a directory or just launch it from the plugin menu to create an md5sum of the file, the directory’s contents or the whole filesystem. If the file’s extension is .md5 or .md5sum, it will check the md5 sums in the file instead. If the file’s extension is .md5list it will compute md5 sums for all the files listed.
This plugin can be used as a metronome to keep time during music practice. It supports two modes of operation, depending on it being started from the plugin menu or as viewer for tempomap (.tempo) files.
The sound is a piercing square wave that can be heard well also through loud music from a band. In addition, the display also indicates the beats while playing so that you can discreetly place the device in your sight for checking the tempo instead of wearing headphones at a concert.
This is the mode of operation that is active when starting the plugin directly from the menu. It offers a uniform metronome sound at a constant tempo. You can adjust the tempo through the interface or by tapping it out on the appropriate button.
Key | Action |
Long Menu | Exit plugin |
Menu | Stop |
Long On | Start |
On | Tap tempo |
Minus / Plus | Adjust tempo |
Play / Stop | Adjust volume |
|
When starting the plugin as a viewer for tempomap files (ending in .tempo), it starts in the track mode that offers playback of a preprogrammed metronome track consisting out of multiple parts, each with possibly different properties.
In contrast to the simple mode, there exists the notion of meter and bars, along with emphasis on certain beats. Parts can have these properties:
The button mapping is different to enable navigation in the programmed track.
Key | Action |
Long Menu | Exit plugin |
Menu | Stop (stay at position) |
On | Start from / Stop at current position |
Minus / Plus | Seek in track |
Play / Stop | Adjust volume |
|
Navigation The display indicates the part properties and position in track as such:
In this example, the part label is “Interlude”, the meter is 3/4 and the tempo 120 quarter beats per minute (bpm). The volume setting is at -25 and this is the second part of a track with 13 total. In that part, the position is at the second beat of the first bar of five.
The syntax of programmed tracks in tempomap files follows the format defined by http://das.nasophon.de/klick/. Actually, the goal is to keep compatibility between klick and this Rockbox metronome. The parts of a track are specified one line each in this scheme (pieces in [] optional):
The bar count and tempo always have to be specified, the rest is optional.
One example is
for a part named “part I” , 12 bars long, in 3/4 meter with a tempo of 133 quarter beats per minute. Tempo changes are indicated by specifying a tempo range and the acceleration in one of these ways:
The first one goes from 90 to 150 bpm in an endless part with 0.25 bpm increase per bar. The second one goes down from 150 to 90 with 4 bars per bpm change, which is the same acceleration as in the first line. The last one is a part of 16 bars length that changes tempo from 100 to 200 smoothly during its whole lifetime (6.25 bpm/bar). For details on how the acceleration works, see http://thomas.orgis.org/science/metronome-_tempomath/tempomath.html.
It is also possible to provide a tempo for each individual beat in a part by separating values with a comma (no spaces),
where the beat duration is first according to 135 bpm, then 90 bpm, and so forth. You are required to provide a value for each beat in all bars of the part.
You can provide a pattern that controls how the beats are played:
Symbol | Meaning |
X | emphasized beat (Tick) |
x | normal beat (Tock) |
. | silent beat |
Some examples:
The 12/12 for the shuffle create 1/4 triplets. Just do a bit of math;-) This is still a metronome, not a drum machine, but it can act like a basic one, helping you to figure out a certain rhythm within the meter.
The UI is developed so that it fits into the display of a Sansa Clip+ and that is the hardware device it is tested on. It seems to work reasonably on some other models in the simulator.
At last, a more complete tempomap file:
This plugin provides the ability to generate one-time passwords (OTPs) for authentication purposes. It implements an HMAC-based One-Time Password Algorithm (RFC 4226), and on targets which support it, a Time-based One-Time Password Algorithm (RFC 6238).
The plugin supports two methods of adding accounts: URI import, and manual entry.
This method of adding an account reads a list of URIs from a file. It expects each URI to be on a line by itself in the following format:
An example is shown below, provisioning a TOTP key for an account called “bob”:
Any other URI options are not supported and will be ignored.
Most services will provide a scannable QR code that encodes a OTP URI. In order to use those, first scan the QR code separately and save the URI to a file on your device. If necessary, rewrite the URI so it is in the format shown above. For example, GitHub’s URI has a slash after the provider. In order for this URI to be properly parsed, you must rewrite the account name so that it does not contain a slash.
If direct URI import is not possible, the plugin supports the manual entry of data associated with an account. After you select the “Manual Entry” option, it will prompt you for an account name. You may type anything you wish, but it should be memorable. It will then prompt you for the Base32-encoded secret. Most services will provide this to you directly, but some may only provide you with a QR code. In these cases, you must scan the QR code separately, and then enter the string following the “secret=” parameter on your Rockbox device manually.
On devices with a real-time clock, the plugin will ask whether the account is a time-based account (TOTP). However, if your device lacks a real-time clock, the plugin’s functionality will be restricted to HMAC-based (HOTP) accounts only. If this is the case, the plugin will prompt you for information regarding the HOTP setup.
This plugin is used to configure the folders which will be considered when the Auto-Change Directory feature is set to Random.
Key | Action |
Play | Delete selected folder |
Long Play | Bring up the context menu which allows you to remove the selected folder or its entire folder tree |
Stop | Exit |
|
The resistor calculator is a plugin that works in 3 modes:
In Colour to Resistance mode, use the menus to select the colours of the bands of a resistor which you would like to know the resistance of.
In Resistance to Colour mode, use the menus to select the unit that you would like to use (choose from Ohms, Kiloohms, Megaohms), and use the on-screen keyboard to input the value of the resistor that you would like to know the colour code of. The colour codes are presented textually.
LED resistance calculator is used to determine the resistor necessary to light an LED safely at a given voltage. First, select the voltage that the LED will use (the first option is the most common and a safe bet), and the current that it will draw (likewise with the first option). Then, use the onscreen keyboard to type in the supply voltage and, if selected, the custom forward current. This function produces safe estimates, but use your own judgement when using these output values. Power rating and displayed resistance are rounded up to the nearest common value.
The stats plugin counts the directories and files (the total number as well as the number of audio, playlist, image and video files) on your player. Press Menu or Long Menu to abort counting and exit the plugin. Press it again to quit after counting has finished.
A simple stopwatch program with support for saving times.
Key | Action |
Menu | Quit Plugin |
Play | Start / stop |
Stop | Reset timer (only when timer is stopped) |
On | Take lap time |
Minus / Plus | Scroll through lap times |
|