Using Display Names

*Note: 2014-01-07: The patches, notes and builds referred to below as in SourceForge are no longer present there.*

Using display names allows you to browse files using the id3 tags embedded into most mp3 files. An id3 tag contains extended information about an mp3 file. You probably already use id3 tags to store information about the title, artist, track number, genre, album, and other information about the music contained in the mp3.

A quick note: this is NOT an id3 database like DataBase. You probably wouldn't want to use this to quickly switch between sorting by different criteria. The purpose of this feature is to allow you to browse and play back a folder full of mp3s in a different order than alphabetical file name.

Getting this feature

CVS and Patching

Right now this feature is not part of the rockbox distribution. If you want it, you will have to download the source code (either CVS or a recent daily build) and apply a patch. Since you will be working with a daily or bleeding-edge build, please ensure that you back up any important files on your Archos unit, and that you are familiar with recovery features should you experience problems. Having said that, I can say that this feature has been tested on several different models without any issues. If you experience a problem with the feature, report it to me, or report it at the sourceforge listing for this patch.

The patch and notes about it are located here. Details on applying patches and building the code are available in other sections of this wiki. See the "How To" section of DocsIndex.

Pre-built code with this feature

If you'd like a prebuilt object file for your unit, there are some builds on the SourceForge patch tracker for this patch. You will need to have a recent daily build installed already (so that you have the latest version of the plugins and such). Again, be warned: using a daily build is riskier than using a release build. There are two files: one is the plugin (build_id3_names.rock) that belongs in /.rockbox/rocks and the other is the rockbox build for your unit. Place this in the root directory, replacing the file from the daily build.

Enabling this feature

Once you have applied the patch and built the code, (or installed the prebuilt files) you will need to enable the feature. In the main menu, under "General Settings" and "File View" select "Use id3 Tags in Browser" and set this option to "Yes". You will need to reboot the unit after this, since certain variables that can only be initialized at startup have to be created.

Choosing a display format

Display formatting is controlled by:

• The file /.rockbox/.display_global which contains the default style. If this file is missing, invalid, or blank, the default style will be to display the file name.
• The file (directory)/.display which contains the local display style. If this file is missing, invalid, or blank, the default style will be used. (or file names will be used if there is no default style)

Style files (.display and .display_global) follow a simple format:

• The escape sequence %a is replaced by "Artist Name"
• The escape sequence %t is replaced by "Song Title"
• The escape sequence %n is replaced by "Track Number"
• Any other text is copied directly.

For instance, say you have a directory containing a file called "Track 01.mp3" that is "My Song" by "My Artist" and is track "1"

The formatting string %t - %a would display: My Song - My Artist

The formatting string (%n) %t would display: ( 1) My Song

If there is no useful id3 information in the file, then the file name is used.

(New for patch version 5) The feature will select the id3 v1 or v2 data based on your preferences settings.

Cached display formats

This feature creates a directory called /.rockbox/cache where it stores cached display name information. Loading the display name information from cache is several times quicker than reading each file for its id3 information each time you browse a particular directory. The cache for a directory is created at the time the directory is first browsed to. There is a plugin, also available from the patch site that can rebuild and clean these caches all at once. You do not need to run this plugin in order to use caches, the caches are generated on the fly the first time you enter a new directory. If files are changed or removed, or if the format for a directory changes, the cache is automatically refreshed.

(New for patch version 5) There is now an option in the ON+PLAY menu for directories to clear the cache for the selected directory.

Performance

Browsing folders with id3 names is slower than just using file names, since in order to read id3 information, we need to open each file. Caching reduces this problem somewhat.

For a directory of 44 files, on a Recorder V2,

• First time browsing, no cache: ~4.5 seconds
• After cache is built: ~1.6 seconds
• Just using file names: less than 1 second (somewhere around .7-.9 sec)

In addition, this uses slightly more disk access and a small amount of RAM. Of course, with the .display and .display_global files, you can control which directories you want to view file names for, and which directories you need to have sorted differently.

Coming soon

This feature is still a work in progress. In its current form, it works, and works well. However, there is always room for improvement.

• Integration into the main code (so that this feature is in daily builds)
• Better UI integration for creating/modifying .display files
• More options for display format strings (What do people want? Perhaps like the While Playing Screen?)

-- JonathanDeonarine - 07 Aug 2004