Tracks

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

## Synopsis

                Itdb_Track;
    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);
    gboolean    itdb_track_set_thumbnails       (Itdb_Track *track,
                                                 const gchar *filename);
    void        itdb_track_remove_thumbnails    (Itdb_Track *track);
    #define     ITDB_RATING_STEP

## Description

## Details

### Itdb_Track

    typedef struct {
      Itdb_iTunesDB *itdb;       /* pointer to iTunesDB (for convenience) */
      gchar   *title;            /* title (utf8)           */
      gchar   *ipod_path;        /* name of file on iPod: uses ":"
    				instead of "/"                        */
      gchar   *album;            /* album (utf8)           */
      gchar   *artist;           /* artist (utf8)          */
      gchar   *genre;            /* genre (utf8)           */
      gchar   *filetype;         /* eg. "MP3-File"...(utf8)*/
      gchar   *comment;          /* comment (utf8)         */
      gchar   *category;         /* Category for podcast   */
      gchar   *composer;         /* Composer (utf8)        */
      gchar   *grouping;         /* ? (utf8)               */
      gchar   *description;      /* see note for MHOD_ID in itdb_itunesdb.c */
      gchar   *podcasturl;       /* see note for MHOD_ID in itdb_itunesdb.c */
      gchar   *podcastrss;       /* see note for MHOD_ID in itdb_itunesdb.c */
      gchar   *chapterdata;      /* see note for MHOD_ID in itdb_itunesdb.c */
      gchar   *subtitle;         /* see note for MHOD_ID in itdb_itunesdb.c */
      guint32 id;                /* unique ID of track     */
      gint32  size;              /* size of file in bytes  */
      gint32  tracklen;          /* Length of track in ms  */
      gint32  cd_nr;             /* CD number              */
      gint32  cds;               /* number of CDs          */
      gint32  track_nr;          /* track number           */
      gint32  tracks;            /* number of tracks       */
      gint32  bitrate;           /* bitrate                */
      guint16 samplerate;        /* samplerate (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;              /* year                   */
      gint32  volume;            /* volume adjustment              */
      guint32 soundcheck;        /* volume adjustment "soundcheck" */
      guint32 time_added;        /* time when added (Mac type)          */
      guint32 time_played;       /* time of last play (Mac type)        */
      guint32 time_modified;     /* time of last modification (Mac type)*/
      guint32 bookmark_time;     /* bookmark set for (AudioBook) in ms  */
      guint32 rating;            /* star rating (stars * RATING_STEP (20))     */
      guint32 playcount;         /* number of times track was played    */
      guint32 playcount2;        /* Also stores the play count of the
    				song.  Don't know if it ever differs
    				from the above value. During sync itdb
    				sets playcount2 to the same value as
    				playcount. */
      guint32 recent_playcount;  /* times track was played since last sync */
      gboolean transferred;      /* has file been transferred to iPod?  */
      gint16  BPM;               /* supposed to vary the playback speed */
      guint8  app_rating;        /* star rating set by appl. (not
    			      * iPod). If the rating set on the iPod
    			        and the rating field above differ, the
    				original rating is copied here and the
    				new rating is stored above. */
      guint8  type1;             /* CBR MP3s and AAC are 0x00, VBR MP3s are
    			        0x01 */
      guint8  type2;             /* MP3s are 0x01, AAC are 0x00 */
      guint8  compilation;
      guint32 starttime;
      guint32 stoptime;
      guint8  checked;           /* 0x0: checkmark on track is set 0x1: not set */
      guint64 dbid;              /* unique database ID */
      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>. (set to
    				the filename extension by itdb when
    				copying track to 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
    				iPodDB version 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's uncertain why this is
    				here.  itdb 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. itdb
    			 will try to set this when adding a new track */
      guint32 unk132;     /* unknown */
      guint32 time_released;/* date/time added to music store? definitely a
    			 timestamp, always appears to be a time of
    			 0700 GMT. For podcasts: release date as
    			 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. itdb
    			 will attempt to set this value when adding a
    			 track. */
      guint16 unk146;     /* unknown, but appears to be 1 if played at
    			 least once in iTunes and 0 otherwise. */
      guint32 unk148;     /* unknown - used for Apple Store DRM songs
    			 (always 0x01010100?), zero otherwise */
      guint32 unk152;     /* unknown */
      guint32 unk156, unk160;
      guint8 has_artwork; /* 0x01: artwork is present. 0x02: no artwork is
    			 present for this track (used by the iPod to
    			 decide whether to display Artwork or not) */
      guint8 skip_when_shuffling;/* "Skip when shuffling" when set to
    			 0x01, set to 0x00 otherwise. .m4b and .aa
    			 files always seem to be skipped when
    			 shuffling, however */
      guint8 remember_playback_position;/* "Remember playback position"
    			 when set to 0x01, set to 0x00 otherwise. .m4b
    			 and .aa files always seem to remember the
    			 playback position, however. */
      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;      /* not clear. if not set, itdb will set this to
    			 the same value as dbid when adding a track */
      guint8 lyrics_flag; /* set to 0x01 if lyrics are present in MP3 tag
    			 ("ULST"), 0x00 otherwise */
      guint8 movie_flag;  /* set to 0x01 if it's a movie file, 0x00
    		         otherwise */
      guint8 mark_unplayed; /* A value of 0x02 marks a podcast as unplayed
    			   on the iPod (bullet) once played it is set to
    			   0x01. Non-podcasts have this set to 0x01. */
      guint8 unk179;      /* unknown (always 0x00 so far) */
      guint32 unk180, unk184;
      guint32 samplecount;/* Number of samples in the song. First observed
    			 in dbversion 0x0d, and only for AAC and WAV
    			 files (not MP3?!?). */
      guint32 unk192, unk196, unk200;
      guint32 unk204;     /*  unknown - added in dbversion 0x0c, first
    			  values observed in 0x0d. Observed to be 0x0
    			  or 0x1. */
      guint32 unk208, unk212, unk216, unk220, unk224;
      guint32 unk228, unk232, unk236, unk240;

        /* Chapter data: defines where the chapter stops are in the track,
           as well as what info should be displayed for each section of
           the track. Until it can be parsed and interpreted, the
           chapterdata will just be read as a block and written back on
           sync. This will be changed at a later time */
      void *chapterdata_raw;
      guint32 chapterdata_raw_length;

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

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

### 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()` function below

`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_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, ie 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.

### itdb_track_remove_thumbnails ()

    void        itdb_track_remove_thumbnails    (Itdb_Track *track);

Removes the thumbnails associated with `track`

`track` : | an Itdb_Track

### ITDB_RATING_STEP

    #define ITDB_RATING_STEP 20