<wiki:toc max_depth="1" />
Introduction
If you don't know what CUE is, you probably don't need to read this. Still, if you'd like to learn what CUE is, a good starting point would be this Wikipedia article. Before we start, check out CUEs in action!
A media file and its CUE sheet:
http://student.agh.edu.pl/~bara/cue.png
Dragging the CUE over Clementine:
http://student.agh.edu.pl/~bara/cue_dnd.png
Notice that both songs that were described in the sheet appear in the playlist even though there is only one media file:
http://student.agh.edu.pl/~bara/cue_result.png
Dictionary
CUE related song - every song represented by a media file described with a CUE sheet. For example, song1.wav is CUE related:
C:\songs\best\song1.wav
C:\media.cue:
FILE C:\songs\best\song1.wav WAVE
PERFORMER "Artist"
TITLE "Album"
TRACK 01 AUDIO
TITLE "Title"
INDEX 00 00:00:00
INDEX 01 00:01:00
CUE associated song - song for which an associated .cue exists. By associated .cue we mean a file with this path = DIR/FILE_NAME.cue for a media file with this path = DIR/FILE_NAME.MEDIA_EXTENSION. For example, those two files are associated:
~/MUSIC/A_DJ/A_Mix/a_mix.mp3
~/MUSIC/A_DJ/A_Mix/a_mix.cue
CUE sheets outside the library
When we're dealing with CUE sheets outside of the library, we're talking about the full spectrum of features. When loading CUE related songs using the 'Files' tab or dragging and dropping such songs from your native file browser:
- all metadata from sheet (CUE tags like TITLE, PERFORMER, SONGWRITER etc.) is used
- Clementine will try to extract as much data from the CUE as possible, ignoring the uncritical CUE errors in the process
- multiple FILE based CUEs are supported
- both relative and absolute FILE paths are supported
You can open any .cue file this way and Clementine will try to find the related media files and load them using both absolute and relative paths.
Also, when you're opening a media file, if Clementine finds an associated CUE, it will use it to split the media file to sections if necessary.
Please note one thing about the multiple FILE based CUEs: any given FILE should appear in a CUE file at most once!
CUE sheets in library
Library supports ONLY the associated .cues which means you need to name your .cues just like their associated media files, otherwise library scanner won't recognize them.
In library mode some features are absent, namely: CUE can still link to multiple files but only the songs coming from the file with the name associated with the CUE will be used!
For example, in this situation...
C:\songs\best\song1.wav
C:\songs\best\song2.wav
C:\songs\best\song1.cue
FILE song1.cue WAVE
... METADATA...
FILE song2.cue WAVE
... METADATA...
... all sections coming from the song2.wav file won't appear in the library (or rather the file song2.wav will appear as if there was no .cue related at all).
Please note that when rescanning the library, a song is marked as changed (which means it'll get updated) when either its media file has changed or its associated CUE file has changed. Also, when a CUE sheet that was used by library song sections gets deleted, the associated song sections are deleted from it too and the only thing that's left is the 'raw' media file like there was no CUE support in the first place.
Embedded CUEs
Embedded CUEs are currently not supported and won't be supported until at least 0.8 version of Clementine. If you'd really like to see this feature, vote for this issue: issue #1276
CUEs and invalid media files
Some formats (like APE) are not recognized by the tag library which Clementine's using. That means you cannot load such files (let's call those 'invalid') into Clementine. Try dropping such a song into playlist - the request will be ignored.
But... If you have a CUE related to such an invalid file, you'll be able to load it into playlist and possibly even play it! It's this way because all CUE related / associated songs are considered valid, even if they don't exist and in some situations (for example with APE files) Clementine might be able to play a media file while simultaneously not being able to read its tags.
Keep in mind though that while you'll be able to load a CUE + invalid song pair into playlist, such a pair won't ever get into the library!
Encoding
Unfortunately the CUE sheet standard is not specifying an encoding. There's a SLIGHT chance that Clementine will recognize any encoding out there... but if you don't want to see any weird characters in your tags, please convert all your CUEs to UTF because UTF (UTF-8 for example) is the only encoding family that's fully supported.