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

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.

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

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

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

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

This is a rotating cube screen saver in 3D.

10.2.3  Logo

Demo showing the Rockbox logo bouncing around the screen.

10.2.4  Mosaique

This simple graphics demo draws a mosaic picture on the screen of the player. Press Stop to quit.

10.2.5  Snow

This demo replicates snow falling on your screen. If you love winter, you will love this demo. Or maybe not.

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

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:

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

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

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.

---

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.

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:

• Another plugin is loaded.
• The player is shut down.
• The battery is empty.

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

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

• First enter the number of players (1–10)
• Then set the total game time in mm:ss
• Then the maximum round time is entered. For example, this could be used to play Scrabble for a maximum of 15 minutes each, with each round taking no longer than one minute.
• Done. Player 1 starts in paused mode.

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:

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.

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.

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.

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

10.4.9  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

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 Stop to abort counting and exit the plugin. Press it again to quit after counting has finished.

10.4.11  Stopwatch

A simple stopwatch program with support for saving times.