Tracks

## Tracks Tracks — Data structure to store metadata about an iPod track |

## Synopsis

                        Itdb_Track;
                        Itdb_Track_Private;
    enum                Itdb_Mediatype;
    #define             ITDB_RATING_STEP
    Itdb_Track *        itdb_track_new                      (void);
    void                itdb_track_free                     (Itdb_Track *track);
    void                itdb_track_add                      (Itdb_iTunesDB *itdb,
                                                             Itdb_Track *track,
                                                             gint32 pos);
    void                itdb_track_remove                   (Itdb_Track *track);
    void                itdb_track_unlink                   (Itdb_Track *track);
    Itdb_Track *        itdb_track_duplicate                (Itdb_Track *tr);
    Itdb_Track *        itdb_track_by_id                    (Itdb_iTunesDB *itdb,
                                                             guint32 id);
    GTree *             itdb_track_id_tree_create           (Itdb_iTunesDB *itdb);
    void                itdb_track_id_tree_destroy          (GTree *idtree);
    Itdb_Track *        itdb_track_id_tree_by_id            (GTree *idtree,
                                                             guint32 id);
    gpointer            itdb_track_get_thumbnail            (Itdb_Track *track,
                                                             gint width,
                                                             gint height);
    gboolean            itdb_track_has_thumbnails           (Itdb_Track *track);
    gboolean            itdb_track_set_thumbnails           (Itdb_Track *track,
                                                             const gchar *filename);
    gboolean            itdb_track_set_thumbnails_from_data (Itdb_Track *track,
                                                             const guchar *image_data,
                                                             gsize image_data_len);
    gboolean            itdb_track_set_thumbnails_from_pixbuf
                                                            (Itdb_Track *track,
                                                             gpointer pixbuf);
    void                itdb_track_remove_thumbnails        (Itdb_Track *track);

## Description

These functions and structures are for storing and retrieving information about an iPod track.

## Details

### Itdb_Track

    typedef struct {
      Itdb_iTunesDB *itdb;
      gchar   *title;
      gchar   *ipod_path;
      gchar   *album;
      gchar   *artist;
      gchar   *genre;
      gchar   *filetype;
      gchar   *comment;
      gchar   *category;
      gchar   *composer;
      gchar   *grouping;
      gchar   *description;
      gchar   *podcasturl;
      gchar   *podcastrss;
      Itdb_Chapterdata *chapterdata;
      gchar   *subtitle;
    /* the following 5 are new in libgpod 0.4.2... */
      gchar   *tvshow;
      gchar   *tvepisode;
      gchar   *tvnetwork;
      gchar   *albumartist;
      gchar   *keywords;
    /* the following 6 are new in libgpod 0.5.0... */
      /* You can set these strings to override the standard
         sortorder. When set they take precedence over the default
         'artist', 'album'... fields.

         For example, in the case of an artist name like "The Artist",
         iTunes will set sort_artist to "Artist, The" followed by five
         0x01 characters. Why five 0x01 characters are added is not
         completely understood.

         If you do not set the sort_artist field, libgpod will pre-sort
         the lists displayed by the iPod according to "Artist, The",
         without setting the field.
      */
      gchar   *sort_artist;
      gchar   *sort_title;
      gchar   *sort_album;
      gchar   *sort_albumartist;
      gchar   *sort_composer;
      gchar   *sort_tvshow;
    /* end of new fields in libgpod 0.5.0 */
      guint32 id;
      gint32  size;
      gint32  tracklen;
      gint32  cd_nr;
      gint32  cds;
      gint32  track_nr;
      gint32  tracks;
      gint32  bitrate;
      guint16 samplerate;
      guint16 samplerate_low;
      gint32  year;
      gint32  volume;
      guint32 soundcheck;
      time_t  time_added;
      time_t  time_modified;
      time_t  time_played;
      guint32 bookmark_time;
      guint32 rating;
      guint32 playcount;
      guint32 playcount2;
      guint32 recent_playcount;
      gboolean transferred;
      gint16  BPM;
      guint8  app_rating;
      guint8  type1;
      guint8  type2;
      guint8  compilation;
      guint32 starttime;
      guint32 stoptime;
      guint8  checked;
      guint64 dbid;
      guint32 drm_userid;
      guint32 visible;
      guint32 filetype_marker;
      guint16 artwork_count;
      guint32 artwork_size;
      float samplerate2;
      guint16 unk126;
      guint32 unk132;
      time_t  time_released;
      guint16 unk144;
      guint16 explicit_flag;
      guint32 unk148;
      guint32 unk152;
      guint32 skipcount;
      guint32 recent_skipcount;
      guint32 last_skipped;
      guint8 has_artwork;
      guint8 skip_when_shuffling;
      guint8 remember_playback_position;
      guint8 flag4;
      guint64 dbid2;
      guint8 lyrics_flag;
      guint8 movie_flag;
      guint8 mark_unplayed;
      guint8 unk179;
      guint32 unk180;
      guint32 pregap;
      guint64 samplecount;
      guint32 unk196;
      guint32 postgap;
      guint32 unk204;
      guint32 mediatype;
      guint32 season_nr;
      guint32 episode_nr;
      guint32 unk220;
      guint32 unk224;
      guint32 unk228, unk232, unk236, unk240, unk244;
      guint32 gapless_data;
      guint32 unk252;
      guint16 gapless_track_flag;
      guint16 gapless_album_flag;
      guint16 obsolete;

      /* This is for Cover Art support */
      struct _Itdb_Artwork *artwork;

      /* This is for sparse artwork support, new in libgpod-0.7.0 */
      guint32 mhii_link;

      /* reserved for future use */
      gint32 reserved_int1;
      gint32 reserved_int2;
      gint32 reserved_int3;
      gint32 reserved_int4;
      gint32 reserved_int5;
      gint32 reserved_int6;
      Itdb_Track_Private *priv;
      gpointer reserved2;
      gpointer reserved3;
      gpointer reserved4;
      gpointer reserved5;
      gpointer reserved6;

      /* +++***+++***+++***+++***+++***+++***+++***+++***+++***+++***
         When adding string fields don't forget to add them in
         itdb_track_duplicate as well
         +++***+++***+++***+++***+++***+++***+++***+++***+++***+++*** */

      /* below is for use by application */
      guint64 usertype;
      gpointer userdata;
      /* functions called to duplicate/free userdata */
      ItdbUserDataDuplicateFunc userdata_duplicate;
      ItdbUserDataDestroyFunc userdata_destroy;
    } Itdb_Track;

Structure representing a track in an iTunesDB

### Note

When adding string fields don't forget to add them in `itdb_track_duplicate()` as well.

Many of the parameter descriptions are copied verbatim from http://ipodlinux.org/ITunesDB, which is the best source for information about the iTunesDB and related files.

Itdb_iTunesDB *`itdb`; | A pointer to the Itdb_iTunesDB (for convenience)
gchar *`title`; | The title of the track in UTF8
gchar *`ipod_path`; | The file path on the iPod. Directories are separated with ":" instead of "/". The path is relative to the iPod mountpoint.
gchar *`album`; | The album name in UTF8
gchar *`artist`; | The artist name in UTF8
gchar *`genre`; | The genre in UTF8
gchar *`filetype`; | A UTF8 string describing the file type. E.g. "MP3-File".
gchar *`comment`; | A comment in UTF8
gchar *`category`; | The category ("Technology", "Music", etc.) where the podcast was located. (Added in dbversion 0x0d)
gchar *`composer`; | The composer name in UTF8
gchar *`grouping`; | ??? (UTF8)
gchar *`description`; | Description text (such as podcast show notes). (Added in dbversion 0x0d)
gchar *`podcasturl`; | Podcast Enclosure URL in UTF-8 or ASCII. (Added in dbversion 0x0d)
gchar *`podcastrss`; | Podcast RSS URL in UTF-8 or ASCII. (Added in dbversion 0x0d)
Itdb_Chapterdata *`chapterdata`; | This is an m4a-style entry that is used to display subsongs within a mhit. (Added in dbversion 0x0d)
gchar *`subtitle`; | Subtitle (usually the same as Description). (Added in dbversion 0x0d)
gchar *`tvshow`; | Name of the TV show (only used for TV Shows). (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
gchar *`tvepisode`; | The episode number (only used for TV Shows). (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
gchar *`tvnetwork`; | The TV network (only used for TV Shows). (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
gchar *`albumartist`; | The album artist (Added in dbversion 0x13?) (Since libgpod-0.4.2)
gchar *`keywords`; | List of keywords pertaining to the track. (Added in dbversion 0x13?) (Since libgpod-0.4.2)
gchar *`sort_artist`; | The artist name used for sorting. Artists with names like "The Artist" would have "Artist, The" here. If you do not set this field, libgpod will pre-sort the lists displayed by the iPod according to "Artist, The", without setting this field. (Added in dbversion 0x13?) (Since libgpod-0.5.0)
gchar *`sort_title`; | The track title used for sorting. See `sort_artist`. (Since libgpod-0.5.0)
gchar *`sort_album`; | The album name used for sorting. See `sort_artist`. (Since libgpod-0.5.0)
gchar *`sort_albumartist`; | The album artist used for sorting. See `sort_artist`. (Since libgpod-0.5.0)
gchar *`sort_composer`; | The composer used for sorting. See `sort_artist`. (Since libgpod-0.5.0)
gchar *`sort_tvshow`; | The name of the TV show used for sorting. See `sort_artist`. (Since libgpod-0.5.0)
guint32 `id`; | Unique ID of track
gint32 `size`; | The size of the file in bytes
gint32 `tracklen`; | The length of the track in ms
gint32 `cd_nr`; | The CD number the track comes from.
gint32 `cds`; | The total number of CDs.
gint32 `track_nr`; | The track number.
gint32 `tracks`; | The total number of tracks.
gint32 `bitrate`; | The bitrate at which the file is encoded.
guint16 `samplerate`; | The samplerate of the track (e.g. CD = 44100)
guint16 `samplerate_low`; | In the iTunesDB the samplerate is multiplied by 0x10000 -- these are the lower 16 bit, which are usually 0
gint32 `year`; | The year the track was released
gint32 `volume`; | Volume adjustment field. This is a value from -255 to 255 that will be applied to the track on playback.
guint32 `soundcheck`; | The SoundCheck value to apply to the song, when SoundCheck is switched on in the iPod settings. The value for this field can be determined by the equation: X = 1000 * 10 ^ (-.1 * Y) where Y is the adjustment value in dB and X is the value that goes into the SoundCheck field. The value 0 is special, the equation is not used and it is treated as "no Soundcheck" (basically the same as the value 1000). This equation works perfectly well with ReplayGain derived data instead of the iTunes SoundCheck derived information.
time_t `time_added`; | The time the track was added.
time_t `time_modified`; | The time the track was last modified
time_t `time_played`; | The time the track was last played
guint32 `bookmark_time`; | The time, in milliseconds, that the track will start playing at. This is used for AudioBook filetypes (.aa and .m4b). Note that there is also a bookmark value in the play counts file that will be set by the iPod and can be used instead of this value.
guint32 `rating`; | The track rating (stars * ITDB_RATING_STEP)
guint32 `playcount`; | The number of times the track has been played
guint32 `playcount2`; | This also stores the play count of the track. It is unclear if this ever differs from the above value. During sync, this is set to the same value as `playcount`.
guint32 `recent_playcount`; | The number of times the track was played since the last sync.
gboolean `transferred`; | Whether the file been transferred to iPod.
gint16 `BPM`; | BPM (beats per minute) of the track
guint8 `app_rating`; | The last rating set by an application (e.g. iTunes). If the rating on the iPod and the `rating` field above differ, the original rating is copied here and the new rating is stored in `rating`.
guint8 `type1`; | CBR MP3s and AAC are 0x00, VBR MP3s are 0x01
guint8 `type2`; | MP3s are 0x01, AAC are 0x00
guint8 `compilation`; | Flag to mark the track as a compilation. True if set to 0x1, false if set to 0x0.
guint32 `starttime`; | The offset, in milliseconds, at which the song will start playing.
guint32 `stoptime`; | The offset, in milliseconds, at which the song will stop playing.
guint8 `checked`; | Flag for whether the track is checked. True if set to 0x0, false if set to 0x1
guint64 `dbid`; | Unique database ID that identifies this song across the databases on the iPod. For example, this id joins an iTunesDB mhit with an ArtworkDB mhii.
guint32 `drm_userid`; | Apple Store/Audible User ID (for DRM'ed files only, set to 0 otherwise).
guint32 `visible`; | If this value is 1, the song is visible on the iPod. All other values cause the file to be hidden.
guint32 `filetype_marker`; | This appears to always be 0 on hard drive based iPods, but for the iTunesDB that is written to an iPod Shuffle, iTunes 4.7.1 writes out the file's type as an ANSI string(!). For example, a MP3 file has a filetype of 0x4d503320 -> 0x4d = 'M', 0x50 = 'P', 0x33 = '3', 0x20 = <space>. This is set to the filename extension by libgpod when copying the track to the iPod.
guint16 `artwork_count`; | The number of album artwork items associated with this song. libgpod updates this value when syncing.
guint32 `artwork_size`; | The total size of artwork (in bytes) attached to this song, when it is converted to JPEG format. Observed in dbversion 0x0b and with an iPod Photo. libgpod updates this value when syncing.
float `samplerate2`; | The sample rate of the song expressed as an IEEE 32 bit floating point number. It is uncertain why this is here. libgpod will set this when adding a track.
guint16 `unk126`; | Unknown, but always seems to be 0xffff for MP3/AAC songs, 0x0 for uncompressed songs (like WAVE format), 0x1 for Audible. libgpod will try to set this when adding a new track.
guint32 `unk132`; | Unknown
time_t `time_released`; | The date/time the track was added to the iTunes music store? For podcasts this is the release date that is displayed next to the title in the Podcast playlist.
guint16 `unk144`; | Unknown, but MP3 songs appear to be always 0x000c, AAC songs are always 0x0033, Audible files are 0x0029, WAV files are 0x0. libgpod will attempt to set this value when adding a track.
guint16 `explicit_flag`; | Flag to mark a track as "explicit" in iTunes. True if to 0x1, false if set to 0x0.
guint32 `unk148`; | Unknown - used for Apple Store DRM songs (always 0x01010100?), zero otherwise
guint32 `unk152`; | Unknown
guint32 `skipcount`; | The number of times the track has been skipped. (Added in dbversion 0x0c)
guint32 `recent_skipcount`; | The number of times the track was skipped since the last sync.
guint32 `last_skipped`; | The time the track was last skipped. (Added in dbversion 0x0c)
guint8 `has_artwork`; | Whether the track has artwork. True if set to 0x01, false if set to 0x02.
guint8 `skip_when_shuffling`; | Flag to skip the track when shuffling. True if set to 0x01, false if set to 0x00. Audiobooks (.aa and .m4b) always seem to be skipped when shuffling, regardless of this flag.
guint8 `remember_playback_position`; | Flag to remember playback position. True when set to 0x01, false when set to 0x00. Audiobooks (.aa and .m4b) always seem to remember the playback position, regardless of this flag.
guint8 `flag4`; | Used for podcasts, 0x00 otherwise. If set to 0x01 the "Now Playing" page will show Title/Album, when set to 0x00 it will also show the Artist. When set to 0x02 a sub-page (middle button) with further information about the track will be shown.
guint64 `dbid2`; | The purpose of the field is unclear. If not set, libgpod will set this to the same value as `dbid` when adding a track. (With iTunes, since dbversion 0x12, this field value differs from `dbid`.)
guint8 `lyrics_flag`; | Whether the track has lyrics (e.g. it has a USLT ID3 tag in an MP3 or a `lyr` atom in an MP4). True if set to 0x01, false if set to 0x00.
guint8 `movie_flag`; | Whether the track is a movie. True if set to 0x01, false if set to 0x00.
guint8 `mark_unplayed`; | A value of 0x02 marks a podcast as unplayed on the iPod, with a bullet. Once played it is set to 0x01. Non-podcasts have this set to 0x01. (Added in dbversion 0x0c)
guint8 `unk179`; | Unknown, always 0x00 so far. (Added in dbversion 0x0c)
guint32 `unk180`; | Unknown. (Added in dbversion 0x0c)
guint32 `pregap`; | The number of samples of silence before the track starts (for gapless playback).
guint64 `samplecount`; | The number of samples in the track (for gapless playback).
guint32 `unk196`; | Unknown. (Added in dbversion 0x0c)
guint32 `postgap`; | The number of samples of silence at the end of the track (for gapless playback).
guint32 `unk204`; | Unknown. Appears to be 0x1 for files encoded using the MP3 encoder, 0x0 otherwise. (Added in dbversion 0x0c, first values observed in 0x0d.)
guint32 `mediatype`; | The type of file. It must be set to 0x00000001 for audio files, and set to 0x00000002 for video files. If set to 0x00, the files show up in both, the audio menus ("Songs", "Artists", etc.) and the video menus ("Movies", "Music Videos", etc.). It appears to be set to 0x20 for music videos, and if set to 0x60 the file shows up in "TV Shows" rather than "Movies". The following list summarizes all observed types: 0x00 00 00 00 - Audio/Video 0x00 00 00 01 - Audio 0x00 00 00 02 - Video 0x00 00 00 04 - Podcast 0x00 00 00 06 - Video Podcast 0x00 00 00 08 - Audiobook 0x00 00 00 20 - Music Video 0x00 00 00 40 - TV Show (shows up ONLY in TV Shows) 0x00 00 00 60 - TV Show (shows up in the Music lists as well)
guint32 `season_nr`; | The season number of the track (only used for TV Shows).
guint32 `episode_nr`; | The episode number of the track (only used for TV Shows). Although this is not displayed on the iPod, the episodes are sorted by episode number.
guint32 `unk220`; | Unknown. This has something to do with protected files. It is set to 0x0 for non-protected files.
guint32 `unk224`; | Unknown. (Added in dbversion 0x0c)
guint32 `unk228`; | Unknown. (Added in dbversion 0x0c)
guint32 `unk232`; | Unknown. (Added in dbversion 0x0c)
guint32 `unk236`; | Unknown. (Added in dbversion 0x0c)
guint32 `unk240`; | Unknown. (Added in dbversion 0x0c)
guint32 `unk244`; | Unknown. (Added in dbversion 0x13)
guint32 `gapless_data`; | The size in bytes from first Synch Frame (which is usually the XING frame that includes the LAME tag) until the 8th before the last frame. The gapless playback does not work for MP3 files if this is set to zero. For AAC tracks, this may be zero. (Added in dbversion 0x13)
guint32 `unk252`; | Unknown. (Added in dbversion 0x0c)
guint16 `gapless_track_flag`; | If set to 1, this track has gapless playback data. (Added in dbversion 0x13)
guint16 `gapless_album_flag`; | If set to 1, this track does not use crossfading in iTunes. (Added in dbversion 0x13)
guint16 `obsolete`; |
struct _Itdb_Artwork *`artwork`; | An Itdb_Artwork for cover art
guint32 `mhii_link`; | This is set to the id of the corresponding ArtworkDB mhii, used for sparse artwork support. (Since libgpod-0.7.0)
gint32 `reserved_int1`; | Reserved for future use
gint32 `reserved_int2`; | Reserved for future use
gint32 `reserved_int3`; | Reserved for future use
gint32 `reserved_int4`; | Reserved for future use
gint32 `reserved_int5`; | Reserved for future use
gint32 `reserved_int6`; | Reserved for future use
Itdb_Track_Private *`priv`; | Private data
gpointer `reserved2`; | Reserved for future use
gpointer `reserved3`; | Reserved for future use
gpointer `reserved4`; | Reserved for future use
gpointer `reserved5`; | Reserved for future use
gpointer `reserved6`; | Reserved for future use
guint64 `usertype`; | For use by application
gpointer `userdata`; | For use by application
ItdbUserDataDuplicateFunc `userdata_duplicate`; | A function to duplicate userdata
ItdbUserDataDestroyFunc `userdata_destroy`; | A function to free userdata

### Itdb_Track_Private

    typedef struct {
    	guint32 album_id;
    	guint32 artist_id;
    	guint32 composer_id;
    } Itdb_Track_Private;

### enum Itdb_Mediatype

    typedef enum
    {
        ITDB_MEDIATYPE_AUDIO        = (1 << 0),
        ITDB_MEDIATYPE_MOVIE        = (1 << 1),
        ITDB_MEDIATYPE_PODCAST      = (1 << 2),
        ITDB_MEDIATYPE_AUDIOBOOK    = (1 << 3),
        ITDB_MEDIATYPE_MUSICVIDEO   = (1 << 5),
        ITDB_MEDIATYPE_TVSHOW       = (1 << 6),
        ITDB_MEDIATYPE_RINGTONE     = (1 << 14),
        ITDB_MEDIATYPE_RENTAL       = (1 << 15),
        ITDB_MEDIATYPE_ITUNES_EXTRA = (1 << 16),
        ITDB_MEDIATYPE_MEMO         = (1 << 20),
        ITDB_MEDIATYPE_ITUNES_U     = (1 << 21),
        ITDB_MEDIATYPE_EPUB_BOOK    = (1 << 22)
    } Itdb_Mediatype;

Mediatype definitions

The mediatype is used to determine what menu a track appears under. For example, setting the mediatype to ITDB_MEDIATYPE_PODCAST makes the track appear on the Podcast menu. Media type is a bitfield, so it can be a binary combination of these constants, make sure to use binary operators when you want to operate on media types (eg use a binary AND in preference over a straight == when you want to test if a track has a given media type).

`ITDB_MEDIATYPE_AUDIO` | Audio files
`ITDB_MEDIATYPE_MOVIE` | Movies
`ITDB_MEDIATYPE_PODCAST` | Podcasts
`ITDB_MEDIATYPE_AUDIOBOOK` | Audio books
`ITDB_MEDIATYPE_MUSICVIDEO` | Music videos
`ITDB_MEDIATYPE_TVSHOW` | TV Shows
`ITDB_MEDIATYPE_RINGTONE` | Ringtone
`ITDB_MEDIATYPE_RENTAL` | Rental
`ITDB_MEDIATYPE_ITUNES_EXTRA` | ?
`ITDB_MEDIATYPE_MEMO` | Memo
`ITDB_MEDIATYPE_ITUNES_U` | iTunes U
`ITDB_MEDIATYPE_EPUB_BOOK` |

Since 0.5.0

### ITDB_RATING_STEP

    #define ITDB_RATING_STEP 20

The multiplier for each star in track->rating

### itdb_track_new ()

    Itdb_Track *        itdb_track_new                      (void);

Creates an empty Itdb_Track

Returns : | the new Itdb_Track, free it with `itdb_track_free()` when no longer needed

### itdb_track_free ()

    void                itdb_track_free                     (Itdb_Track *track);

Frees the memory used by `track`

`track` : | an Itdb_Track

### itdb_track_add ()

    void                itdb_track_add                      (Itdb_iTunesDB *itdb,
                                                             Itdb_Track *track,
                                                             gint32 pos);

Adds `track` to `itdb->tracks` at position `pos` (or at the end if pos is -1). The application is responsible to also add it to the master playlist. The `itdb` gets ownership of the `track` and will take care of freeing the memory it uses when it's no longer necessary.

`itdb` : | an Itdb_iTunesDB
`track` : | an Itdb_Track
`pos` : | position of the track to add

### itdb_track_remove ()

    void                itdb_track_remove                   (Itdb_Track *track);

Removes `track` from the Itdb_iTunesDB it's associated with, and frees the memory it uses. It doesn't remove the track from the playlists it may have been added to, in particular it won't be removed from the master playlist.

`track` : | an Itdb_Track

### itdb_track_unlink ()

    void                itdb_track_unlink                   (Itdb_Track *track);

Removes `track` from the Itdb_iTunesDB it's associated with, but do not free memory. It doesn't remove the track from the playlists it may have been added to, in particular it won't be removed from the master playlist. `track->itdb` is set to NULL.

`track` : | an Itdb_Track

### itdb_track_duplicate ()

    Itdb_Track *        itdb_track_duplicate                (Itdb_Track *tr);

Duplicates an existing track

`tr` : | an Itdb_Track
Returns : | a newly allocated Itdb_Track

### itdb_track_by_id ()

    Itdb_Track *        itdb_track_by_id                    (Itdb_iTunesDB *itdb,
                                                             guint32 id);

Looks up a track using its ID in `itdb`.

Looking up tracks by ID is not really a good idea because the IDs are created by itdb just before export. The functions are here because they are needed during import of the iTunesDB which is referencing tracks by IDs.

This function is very slow (linear in the number of tracks contained in the database). If you need to lookup many IDs use `itdb_track_id_tree_create()`, `itdb_track_id_tree_destroy()`, and `itdb_track_id_tree_by_id()`.

`itdb` : | an Itdb_iTunesDB
`id` : | ID of the track to look for
Returns : | Itdb_Track with the ID `id` or NULL if the ID cannot be found.

### itdb_track_id_tree_create ()

    GTree *             itdb_track_id_tree_create           (Itdb_iTunesDB *itdb);

Creates a balanced-binary tree for quick ID lookup that is used in `itdb_track_by_id_tree()`

`itdb` : | an Itdb_iTunesDB
Returns : | a GTree indexed by track IDs to be freed with `itdb_track_id_tree_destroy()` when no longer used

### itdb_track_id_tree_destroy ()

    void                itdb_track_id_tree_destroy          (GTree *idtree);

Frees the memory used by `idtree`

`idtree` : | a GTree

### itdb_track_id_tree_by_id ()

    Itdb_Track *        itdb_track_id_tree_by_id            (GTree *idtree,
                                                             guint32 id);

Lookup an Itdb_Track by `id` using `idtree` for faster lookup (compared to `itdb_track_by_id()`)

`idtree` : | a GTree created using `itdb_track_id_tree_create()`
`id` : | the ID of the track to search for
Returns : | the Itdb_Track whose ID is `id`, or NULL if such a track couldn't be found

### itdb_track_get_thumbnail ()

    gpointer            itdb_track_get_thumbnail            (Itdb_Track *track,
                                                             gint width,
                                                             gint height);

Get a thumbnail representing the cover associated with the current track, scaling it if appropriate. If either height or width is -1, then the biggest unscaled thumbnail available will be returned.

`track` : | an Itdb_Track
`width` : | width of the pixbuf to retrieve, -1 for the biggest possible size (with no scaling)
`height` : | height of the pixbuf to retrieve, -1 for the biggest possible size (with no scaling)
Returns : | a GdkPixbuf that must be unreffed when no longer used, NULL if no artwork could be found or if libgpod is compiled without GdkPixbuf support

Since 0.7.0

### itdb_track_has_thumbnails ()

    gboolean            itdb_track_has_thumbnails           (Itdb_Track *track);

Determine if a `track` has thumbnails

`track` : | an Itdb_Track
Returns : | TRUE if `track` has artwork available, FALSE otherwise

Since 0.7.0

### itdb_track_set_thumbnails ()

    gboolean            itdb_track_set_thumbnails           (Itdb_Track *track,
                                                             const gchar *filename);

Uses the image contained in `filename` to generate iPod thumbnails. The image can be in any format supported by gdk-pixbuf. To save memory, the thumbnails will only be generated when necessary, i.e. when `itdb_save()` or a similar function is called.

`track` : | an Itdb_Track
`filename` : | image file to use as a thumbnail
Returns : | TRUE if the thumbnail could be added, FALSE otherwise.

Since 0.3.0

### itdb_track_set_thumbnails_from_data ()

    gboolean            itdb_track_set_thumbnails_from_data (Itdb_Track *track,
                                                             const guchar *image_data,
                                                             gsize image_data_len);

Uses `image_data` to generate iPod thumbnails. The image can be in any format supported by gdk-pixbuf. To save memory, the thumbnails will only be generated when necessary, i.e. when `itdb_save()` or a similar function is called.

`track` : | an Itdb_Track
`image_data` : | data used to create the thumbnail (the raw contents of an image file)
`image_data_len` : | length of above data block
Returns : | TRUE if the thumbnail could be added, FALSE otherwise.

Since 0.4.0

### itdb_track_set_thumbnails_from_pixbuf ()

    gboolean            itdb_track_set_thumbnails_from_pixbuf
                                                            (Itdb_Track *track,
                                                             gpointer pixbuf);

Uses `pixbuf` to generate iPod thumbnails. To save memory, the thumbnails will only be generated when necessary, i.e. when `itdb_save()` or a similar function is called.

`track` : | an Itdb_Track
`pixbuf` : | a GdkPixbuf used to generate the thumbnail
Returns : | TRUE if the thumbnail could be added, FALSE otherwise.

Since 0.5.0

### itdb_track_remove_thumbnails ()

    void                itdb_track_remove_thumbnails        (Itdb_Track *track);

Removes the thumbnails associated with `track`

`track` : | an Itdb_Track

Since 0.3.0