Enable JavaScript to show search field.

10  Plugins

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.

10.1 Games
10.1.1 Dice
10.1.2 Flipit
10.1.3 Jackpot
10.1.4 Rockblox
10.2 Demos
10.2.1 Credits
10.2.2 Cube
10.2.3 Logo
10.2.4 Mosaique
10.2.5 Snow
10.3 Viewers
10.3.1 Shortcuts
10.3.2 Search
10.3.3 Shopper
10.3.4 Sort
10.3.5 Text Viewer
10.3.6 Theme Remove
10.3.7 VBRfix
10.4 Applications
10.4.1 Battery Benchmark
10.4.2 Chess Clock
10.4.3 Disk Tidy
10.4.4 Keybox
10.4.5 Lamp
10.4.6 md5sum
10.4.7 Metronome
10.4.8 Random Folder Advance Configuration
10.4.9 Resistor Calculator
10.4.10 Stats
10.4.11 Stopwatch

10.1  Games

10.1.1  Dice

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

10.1.2  Flipit


PIC

Figure 10.1.: Flipit

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

10.1.3  Jackpot


PIC

Figure 10.2.: Jackpot

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

10.1.4  Rockblox


PIC

Figure 10.3.: Rockblox

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

10.2  Demos

10.2.1  Credits

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.

10.2.2  Cube


PIC

Figure 10.4.: Cube

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

10.2.3  Logo

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

10.2.4  Mosaique


PIC

Figure 10.5.: Mosaique

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

10.2.5  Snow


PIC

Figure 10.6.: Have you ever seen snow falling?

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.

10.3  Viewers

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


10.3.1  Shortcuts

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 /.

How to create .link files

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.

How to use .link files, i.e. jump to desired places

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.

Advanced Usage

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:

  /MyMusic/collection/song.mp3<TAB>My favourite song!

10.3.2  Search

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.

10.3.3  Shopper

Shopper is a shopping list plugin which allows you to maintain reusable shopping lists.

10.3.4  Sort

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).

10.3.5  Text Viewer


PIC

Figure 10.7.: Text Viewer

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.

Default keys

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

Menu
Return
Return to the file being viewed.
Viewer Options
Change settings for the current file.
Encoding
Set the codepage in the text viewer. Available settings: ISO-8859-1 (Latin 1). ISO-8859-7 (Greek), CP1251 (Cyrillic), ISO-8859-9 (Turkish), ISO-8859-2 (Latin Extended), CP1250 (Central European), UTF-8 (Unicode), This setting only applies to the plugin and is independent from the Default Codepage setting (see section 8.4).
Word Wrap
Toggle word wrap mode.
On
Break lines at the maximum column limit.
Off (Chop Words)
Break lines at white space or hyphen.
Line Mode
Change how lines are displayed.
Normal
Break lines at newline characters.
Join
Join lines together.
Expand
Add a blank line at newlines. Useful for making paragraphs clearer in some book style text files.
Screens Per Page
Set the number of screens per page. Available options are 1 to 5 screens per page.
Alignment
Set the text alignment.
Right
Set the text alignment to the right. (Useful for displaying right-to-left languages, such as Arabic or Hebrew)
Left
Set the text alignment to the left.
Scroll Settings
The scrolling settings submenu.
Horizontal
Submenu for horizontal scrolling settings.
Scrollbar
Toggle the horizontal scrollbar for the current mode. If the file fits on one screen, there is no scrollbar and this setting has no effect.
No
Do not display the horizontal scroll bar.
Yes
Display the horizontal scroll bar.
Scroll Mode
Change the function of the “Left” and “Right” buttons.
Scroll by Screen
Move to the previous/next screen.
Scroll by Column
Move to the previous/next column.
Vertical
Submenu for vertical scrolling settings.
Scrollbar
Toggle the vertical scrollbar for the current mode. If the file fits on one screen, there is no scrollbar and this setting has no effect.
No
Do not display the vertical scroll bar.
Yes
Display the vertical scroll bar.
Scroll Mode
Change the function of the “Scroll-up” and “Scroll-down” buttons.
Scroll by Page
Scroll up or down one full screen.
Scroll by Line
Scroll up or down one line.
Auto-scroll Speed
Control the speed of auto-scrolling in number of lines per second. Available options are 1 to 10 lines per second. As an example, 4 will scroll the text at four lines per second.
Left/Right Key (Narrow mode)
Change the function of the “Left” and “Right” buttons when the screen is in narrow mode (i.e. one screen per page).
Previous/Next Page
Scroll up or down one full screen.
Top/Bottom Page
Move to the top or bottom page.
Indent Spaces
Set the number of spaces to indent the text when line mode is set to Reflow Lines. Available options are 0 to 5 spaces. If you select 0, a blank line is displayed as an indent.
Show Playback Menu
Display the playback menu to allow control of the currently playing music without leaving the plugin.
Select Bookmark
Select a saved bookmark. In the screenshot below, the “*” denotes the current page.

PIC

Figure 10.8.: The select bookmark menu

Global Settings
Set the default settings for the text viewer. The setting items are the same as Viewer Options. The global settings are stored in .rockbox/rocks/viewers/viewer.dat.
Quit
Exits the plugin. The text viewer automatically stores its settings, the current position and bookmarks in .rockbox/rocks/viewers/viewer_file.dat.

Bookmarks

To add a bookmark, press On. The bookmark will be displayed as shown below. To delete the bookmark press the same button again.


PIC

Figure 10.9.: A bookmark

10.3.6  Theme Remove

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.

Theme Remove menu
Remove Theme.
Selecting this will delete the files specified in the Remove Options. After a theme has been successfully removed, a log message is displayed listing which items have been deleted and which are being kept. Exit this screen by pressing any key. A file called theme_remove_log.txt is created in the root directory of your player listing all the changes.
Remove Options.
This menu specifies which items are removed if Remove Theme is selected in the menu.

One of the following options can be chosen for each setting.

Ask for Removal.
Selecting this option brings up a dialogue with two options: press Play to confirm deletion or any other key to cancel.
Remove if not Used.
Selecting this option will remove the file automatically, if it is not used by another theme in the theme directory and not currently used.
Never Remove.
Selecting this option will always skip deleting the file.
Always Remove.
Selecting this option will remove the file with no regard to whether it’s used by another theme or not.
WPS.
Specifies how the .wps file belonging to a theme .cfg file is handled.
Create Log File.
Setting this to No prevents the log file from being created.
Quit.
Exits this plugin.

10.3.7  VBRfix

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.

10.4  Applications

10.4.1  Battery Benchmark

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.

How it works

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.

Information explained

At the top of the battery_bench.txt file is various information on how to use the plugin, followed by the data themselves.

Time
This column reports the total time of operation of the player. It is not the time that you started the plug-in. If you have your player on for 5 minutes and then start the plugin, it will start measuring from 5 minutes.
Seconds
The same as Time, except measured in seconds.
Level
The percent level of the battery estimated by Rockbox, and not the actual battery level. The actual battery level can be seen from the Voltage column
Time Left
This shows the time remaining until the battery is empty, again as estimated by Rockbox.
Voltage
The battery voltage in mV at the moment the measurement was taken.
C
This stands for Charger. An “A” in that column shows if the power adapter was attached to the unit at the time of the measurement.
U
USB powered. Only for targets that support this. A “U” will indicate if the unit was using the USB port for power at the time of the measurement.

Usage

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.

Limitations

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.

10.4.2  Chess Clock


PIC

Figure 10.10.: Chess Clock

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.

Setup

Key

Action



Plus / Minus

Increase / decrease displayed Value

Play

Move to next screen

Stop

Move to previous screen

While playing

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.

10.4.3  Disk Tidy

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.

Available Options
All
selects all Linux, OS X, and Windows files.
None
deselects all file options.
Linux
selects Linux files. Default files are .dolphinview, .d3lphinview, and .Trash-*/.
Windows
selects Windows files. Default files are Thumbs.db, $RECYCLE.BIN/, Desktop.ini, Recycled/ and System Volume Information/.
Mac
selects OS X files. Default files are ._*, .DS_Store, .Spotlight-V100/ and .Trashes/.
Other
selects additional files added to the configuration file by the user.

Key

Action



Stop

Exit / Abort

10.4.4  Keybox

Keybox is an encrypted password storage using the “Tiny Encryption Algorithm” with a key derived using md5.

Using Keybox

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.

10.4.5  Lamp

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

10.4.6  md5sum

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.

10.4.7  Metronome

This plugin can be used as a metronome to keep time during music practice. 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

10.4.8  Random Folder Advance Configuration

This plugin is used to configure the folders which will be considered when the Auto-Change Directory feature is set to Random.

Menu
Generate Folder List
Generates a list of all folders found on the player. You can filter the directories which are scanned by creating a file called
/.rockbox/folder_advance_dir.txt. Only the directories in this file and any contained directories will be scanned. You can have up to 10 directories ignored by the scan by placing a minus sign before them in the list (i.e. -/CDs will cause everything in the /CDs directory to be ignored.). If you just want /CDs to be ignored but want to include the folders within it you need to have both -/CDs and CDs as entries.
Edit Folder List
Enter the folder list editor
Export List To Textfile
Exports the list to /.rockbox/folder_advance_list.txt
Import List From Textfile
Imports the list from /.rockbox/folder_advance_list.txt
Play Shuffled
Starts playback with the selected directories in random order. Tracks within a directory will be played in normal order. The plugin will exit after starting playback.
Quit

Folder List Editor Keys

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

10.4.9  Resistor Calculator


WARNING! Image not found

Figure 10.11.: Resistor calculator

The resistor calculator is a plugin that works in 3 modes:

Colour to Resistance

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.

Resistance to Colour

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

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.

10.4.10  Stats


PIC

Figure 10.12.: The stats-plugin

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.

10.4.11  Stopwatch


PIC

Figure 10.13.: Stopwatch

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