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

Search | Go
Wiki > Main > CuesheetSupport (r21)

Cuesheet Support


This page aims to be the central point of the discussion about how to implement cuesheets support in Rockbox.

This feature has been requested almost since the beginnings of Rockbox (maybe I'm exaggerating a bit but it's probably not far from being true wink ).

There is tracker entry about it : FS#278.

There are also several forum discussions :

Possible implementation

There are two different possible ways of implementing cuesheet support in Rockbox.

IDEA! If you have any other ideas, please add them !

As a single playlist entry (i.e. the Amarok way)

A music file with an associated cuesheet is viewed as a single file. The possibility to change tracks within the cuesheet is brought by the WPS (PREV and NEXT) and by a special "cuesheet viewer". The WPS should display the information (artist, title) of the current segment of the cuesheet, but the progressbar should reflect progress within the entire file, with the possibility to seek within the whole file. There should also be markers in the progressbar to indicate the location of the different segments. Skipping to the next file in the playlist could be done with a key combination like PLAY+NEXT.

This approach doesn't allow shuffling or adding the tracks separately in the Database, but to me it seems easier to implement, and cleaner too.

As multiple playlist entries (i.e. the Foobar2000 way)

A cue sheet would be treated as a playlist file. Adding it would result of separately adding all of its tracks to the main playlist, allowing them to be used as if they were separate files (which includes shuffling).

I don't really like that approach because I believe cuesheets are used for a purpose that's not the same as simply obtaining gapless playback. Also it seems harder to implement in the playback code.

Other considerations


Is the possibility of shuffling the songs within a cuesheet possible ? a good idea ? a wanted feature ?

IMHO, cuesheets are used with files that constitute a single entity (for example live recording, DJ mixes or mixed compilations), so shuffling them doesn't really make sense. That's why I'm more in favor of the first approach (Amarok).


Should the individual tracks from the cuesheet be added to the database ?

I'll quote Llorean on this, because it reflects pretty well what I think (original post):

"As for the Tag Database, yeah there's only one file open operation instead of several, but seeking has to occur in the file to start at various points, which actually probably means more effort during playback.
I don't say that it won't be a good feature to have. I'm basically asking, why should it treat the different tracks as individual songs, complicating the loading because of the seek, rather than just treating them as seekpoints when you play the individual file? If you want to shuffle them, or play them out of order, why not make them individual files?"

Not only CUE files

Cuesheet support should in fact not be limited to CUE files (that can be separate or included in the metadata of a FLAC file). We also have to consider the possibility of extending the same system to enable support of bookmarked audio formats :
  • M4B? (bookmarkable MP4/M4A) files - Rockbox can bookmark audio files itself. m4a and m4b files can contain chapter / bookmark metadata and reading this probably falls under tag/id3 stuff
  • Ogg files with chained streams (see Large oggs with chained streams discussion).

Useful resources

IRC discussion

The topic was brought up on IRC and a few problems have been identified in adding cue (or any sub-track handling) into the core.


Nico and I (JdGordon?) are going about cue support in two sort of different ways, So we'll see which way works better.

Jdgordon's version

cuesheet.patch: the patch

compile it and put cuesheet.rock in the viewers/ folder. to run, select your .cue file (must be int he same fodler as the associated audio file. One annoying problem is that the player may lock up if you try running a .cue file after exiting this plugin without running any other plugins first. Dont know why. (The current attachment is commitable, but I'll wait to see what Nicolas comes up with first)

Nicolas' version

First try : Viewer plugin

cuesheet_tracklist.patch: the cuesheet viewer patch

I used Jonathan's parser as a base and, with his help, implemented a cuesheet viewer plugin which displays a list of the tracks. It allows to seek to the position of the track within the currently playing file (even if it's not the file represented by the cuesheet, but there are still some checks to make sure we don't try to seek to a position that doesn't exist). The seeking is also much faster because I added audio_pre_ff_rewind() to the plugin API.

Second try : In the core

%W% The patch is now also in the tracker : FS#6460

cuesheet_core_v4.patch: cuesheet support in the core (v4)

This time I added cuesheet support in the core. In this implementation, cuesheets behave just like regular audio files, but when they are loaded, it's actually the audio file they point to that is loaded instead. This means the file mentioned in the cue file must exist (it has to be a relative path), and the filenames of the cuesheet and the audio file are totally independent. Cuesheets can also be viewed like before (and seeking works too) by selecting them, entering the context menu, and then selecting "View cuesheet".

Changed in v2 :
  • Add controls to the WPS to be able to skip between tracks without having to use the "View cuesheet" feature
  • Added struct cuesheet and created a global instance to regroup all the global variables there were before
  • It's now possible to open a cuesheet in "read-only mode" (if it doesn't describe the currently playing track)
  • Fixed : the last track wasn't shown in the cuesheet viewer
  • Added lots of comments
  • A few other changes smile

Changes in v3 :
  • Add markers to the progressbar in the same way as the A-B repeat feature
  • Make the WPS display the metadata from the current track in the cuesheet
  • Cleaned the code a bit

Changes in v4 :
  • Made the markers be displayed at the right places when the progressbar doesn't use the full screen width
  • Made the tracknumber be updated correctly

What's left to do :
  • Add the right #ifdef's
  • Test on different targets
  • Test with different cuesheets
  • You tell me smile

Known bugs :
  • Sometimes moving too fast within the cuesheet (or other different cases of abuse wink can cause the playback engine to become confused and play the wrong section of the file, or even changed tracks.
  • It's not possible to go back to the beginning of the current track in the cuesheet. This is because to allow this we would want to check whether we're close to the beginning of the current track (if we're close, skip to the previous, if not, go back to the beginning of the current). I've tried this, but the imprecision in seeking is a big problem. In fact when we seek to a track that's among the last of the cuesheet, we arrive to a point that's far beyond what we asked. This makes it very difficult to decide whether to skip to the previous track or to go back to the beginning of the current, and in my tests, once I reached the last tracks, I wasn't able to skip backwards again.

Getting it commited!


OK, well i've warmed to Nico's patch and unless i'm mistaken the only big problem with this patch is its crazy memory usage. I think the bes solution is to allocate a user-specified buffer for the sub tracks at bootup so the people who want big cue's can have them, and there is very minimal waste for people who wont use cues. The edited patch I have added is a very basic start for this. there needs more error checking and i don't know what else, but this should work (default is room for 10 tracks)


cuesheet_dynram_v3.patch (no v2 ! wink

I've made some changes to Jonathan's patch to solve a few bugs and add the ability to play several cuesheets in a row. Also I've added the ability to quickly skip to the next track or the beginning of the cuesheet (without having to go through all the tracks) by using the prev/next dir key combination. There are now two cuesheets in memory and I've changed the default max number of tracks to 20. We should add a setting to allow the users to change this number.
I Attachment Action Size Date Who Comment
IRC_log_cuesheets_20061213.txttxt IRC_log_cuesheets_20061213.txt manage 16.2 K 13 Dec 2006 - 15:41 NicolasPennequin Discussion on IRC
cuesheet.patchpatch cuesheet.patch manage 15.6 K 17 Dec 2006 - 13:48 JonathanGordon the patch
cuesheet_core.patchpatch cuesheet_core.patch manage 14.9 K 18 Dec 2006 - 01:13 NicolasPennequin cuesheet support in the core
cuesheet_core_v2.patchpatch cuesheet_core_v2.patch manage 19.0 K 18 Dec 2006 - 23:52 NicolasPennequin cuesheet support in the core, version 2
cuesheet_core_v3.patchpatch cuesheet_core_v3.patch manage 23.7 K 20 Dec 2006 - 04:40 NicolasPennequin cuesheet support in the core, version 3
cuesheet_core_v4.patchpatch cuesheet_core_v4.patch manage 24.0 K 20 Dec 2006 - 17:18 NicolasPennequin cuesheet support in the core, version 4
cuesheet_dynram.patchpatch cuesheet_dynram.patch manage 26.3 K 31 Dec 2006 - 10:17 JonathanGordon v4 with dynamic ram changes
cuesheet_dynram_v3.patchpatch cuesheet_dynram_v3.patch manage 29.4 K 03 Jan 2007 - 21:14 NicolasPennequin Improved dynram (see above)
cuesheet_tracklist.patchpatch cuesheet_tracklist.patch manage 8.3 K 17 Dec 2006 - 05:40 NicolasPennequin the cuesheet viewer patch
r21 - 03 Jan 2007 - 21:19:06 - NicolasPennequin

Copyright by the contributing authors.