Documentation: add Itdb_Track

1 files changed, 399 insertions, 208 deletions

diff --git a/src/itdb.h b/src/itdb.h
index fec1f0d..838798d 100644
--- a/src/itdb.h
+++ b/src/itdb.h
@@ -1141,35 +1141,335 @@ typedef enum
     ITDB_MEDIATYPE_TVSHOW     = 0x0040,
 } Itdb_Mediatype;
 
-/* some of the descriptive comments below are copied verbatim from
-   http://ipodlinux.org/ITunesDB. 
-   http://ipodlinux.org/ITunesDB is the best source for information
-   about the iTunesDB and related files. */
+/**
+ * Itdb_Track:
+ * @itdb:                       A pointer to the #Itdb_iTunesDB (for convenience)
+ * @title:                      The title of the track in UTF8
+ * @ipod_path:                  The file path on the iPod.  Directories are
+ *                              separated with ":" instead of "/".  The path is
+ *                              relative to the iPod mountpoint.
+ * @album:                      The album name in UTF8
+ * @artist:                     The artist name in UTF8
+ * @genre:                      The genre in UTF8
+ * @filetype:                   A UTF8 string describing the file type.  E.g.
+ *                              "MP3-File".
+ * @comment:                    A comment in UTF8
+ * @category:                   The category ("Technology", "Music", etc.)
+ *                              where the podcast was located.  (Added in
+ *                              dbversion 0x0d)
+ * @composer:                   The composer name in UTF8
+ * @grouping:                   ??? (UTF8)
+ * @description:                Description text (such as podcast show notes).
+ *                              (Added in dbversion 0x0d)
+ * @podcasturl:                 Podcast Enclosure URL in UTF-8 or ASCII.
+ *                              (Added in dbversion 0x0d)
+ * @podcastrss:                 Podcast RSS URL in UTF-8 or ASCII.
+ *                              (Added in dbversion 0x0d)
+ * @chapterdata:                This is an m4a-style entry that is used to
+ *                              display subsongs within a mhit.  (Added in
+ *                              dbversion 0x0d)
+ * @subtitle:                   Subtitle (usually the same as Description).
+ *                              (Added in dbversion 0x0d)
+ * @tvshow:                     Name of the TV show (only used for TV Shows).
+ *                              (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
+ * @tvepisode:                  The episode number (only used for TV Shows).
+ *                              (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
+ * @tvnetwork:                  The TV network (only used for TV Shows).
+ *                              (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
+ * @albumartist:                The album artist (Added in dbversion 0x13?)
+ *                              (Since libgpod-0.4.2)
+ * @keywords:                   List of keywords pertaining to the track.
+ *                              (Added in dbversion 0x13?) (Since libgpod-0.4.2)
+ * @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)
+ * @sort_title:                 The track title used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @sort_album:                 The album name used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @sort_albumartist:           The album artist used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @sort_composer:              The composer used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @sort_tvshow:                The name of the TV show used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @id:                         Unique ID of track
+ * @size:                       The size of the file in bytes
+ * @tracklen:                   The length of the track in ms
+ * @cd_nr:                      The CD number the track comes from.
+ * @cds:                        The total number of CDs.
+ * @track_nr:                   The track number.
+ * @tracks:                     The total number of tracks.
+ * @bitrate:                    The bitrate at which the file is encoded.
+ * @samplerate:                 The samplerate of the track (e.g. CD = 44100)
+ * @samplerate_low:             In the iTunesDB the samplerate is
+ *                              multiplied by 0x10000 -- these are the
+ *                              lower 16 bit, which are usually 0
+ * @year:                       The year the track was released
+ * @volume:                     Volume adjustment field.  This is a value from
+ *                              -255 to 255 that will be applied to the track
+ *                              on playback.
+ * @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_added:                 The time the track was added.
+ * @time_modified:              The time the track was last modified
+ * @time_played:                The time the track was last played
+ * @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.
+ * @rating:                     The track rating (stars * #ITDB_RATING_STEP)
+ * @playcount:                  The number of times the track has been played
+ * @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.
+ * @recent_playcount:           The number of times the track was played since
+ *                              the last sync.
+ * @transferred:                Whether the file been transferred to iPod.
+ * @BPM:                        BPM (beats per minute) of the track
+ * @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.
+ * @type1:                      CBR MP3s and AAC are 0x00, VBR MP3s are 0x01
+ * @type2:                      MP3s are 0x01, AAC are 0x00
+ * @compilation:                Flag to mark the track as a compilation.  True
+ *                              if set to 0x1, false if set to 0x0.
+ * @starttime:                  The time, in milliseconds, at which the song
+ *                              will start playing.
+ * @stoptime:                   The time, in milliseconds, at which the song
+ *                              will stop playing.
+ * @checked:                    Flag for whether the track is checked.  True if
+ *                              set to 0x0, false if set to 0x1
+ * @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.
+ * @drm_userid:                 Apple Store/Audible User ID (for DRM'ed files
+ *                              only, set to 0 otherwise).
+ * @visible:                    If this value is 1, the song is visible on the
+ *                              iPod. All other values cause the file to be
+ *                              hidden.
+ * @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.
+ * @artwork_count:              The number of album artwork items associated
+ *                              with this song.  libgpod updates this value
+ *                              when syncing.
+ * @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.
+ * @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.
+ * @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.
+ * @unk132:                     Unknown
+ * @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.
+ * @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.
+ * @explicit_flag:              Flag to mark a track as "explicit" in iTunes.
+ *                              True if to 0x1, false if set to 0x0.
+ * @unk148:                     Unknown - used for Apple Store DRM songs
+ *                              (always 0x01010100?), zero otherwise
+ * @unk152:                     Unknown
+ * @skipcount:                  The number of times the track has been skipped.
+ *                              (Added in dbversion 0x0c)
+ * @recent_skipcount:           The number of times the track was skipped since
+ *                              the last sync.
+ * @last_skipped:               The time the track was last skipped.  (Added in
+ *                              dbversion 0x0c)
+ * @has_artwork:                Whether the track has artwork.
+ *                              True if set to 0x01, false if set to 0x02.
+ * @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.
+ * @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.
+ * @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.
+ * @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.)
+ * @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.
+ * @movie_flag:                 Whether the track is a movie.  True if set to
+ *                              0x01, false if set to 0x00.
+ * @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)
+ * @unk179:                     Unknown, always 0x00 so far.  (Added in
+ *                              dbversion 0x0c)
+ * @unk180:                     Unknown.  (Added in dbversion 0x0c)
+ * @pregap:                     The number of samples of silence before the
+ *                              track starts (for gapless playback).
+ * @samplecount:                The number of samples in the track (for gapless
+ *                              playback).
+ * @unk196:                     Unknown.  (Added in dbversion 0x0c)
+ * @postgap:                    The number of samples of silence at the end of
+ *                              the track (for gapless playback).
+ * @unk204:                     Unknown.  Appears to be 0x1 for files encoded
+ *                              using the MP3 encoder, 0x0 otherwise.  (Added
+ *                              in dbversion 0x0c, first values observed in
+ *                              0x0d.)
+ * @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".
+ *                              <para>
+ *                              The following list summarizes all observed types:
+ *                              </para>
+ *                              <itemizedlist>
+ *                              <listitem>0x00 00 00 00 - Audio/Video</listitem>
+ *                              <listitem>0x00 00 00 01 - Audio</listitem>
+ *                              <listitem>0x00 00 00 02 - Video</listitem>
+ *                              <listitem>0x00 00 00 04 - Podcast</listitem>
+ *                              <listitem>0x00 00 00 06 - Video Podcast</listitem>
+ *                              <listitem>0x00 00 00 08 - Audiobook</listitem>
+ *                              <listitem>0x00 00 00 20 - Music Video</listitem>
+ *                              <listitem>0x00 00 00 40 - TV Show (shows up ONLY
+ *                              in TV Shows)</listitem>
+ *                              <listitem>0x00 00 00 60 - TV Show (shows up in
+ *                              the Music lists as well)</listitem>
+ *                              </itemizedlist>
+ * @season_nr:                  The season number of the track (only used for
+ *                              TV Shows).
+ * @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.
+ * @unk220:                     Unknown.  This has something to do with
+ *                              protected files.  It is set to 0x0 for
+ *                              non-protected files.
+ * @unk224:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk228:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk232:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk236:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk240:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk244:                     Unknown.  (Added in dbversion 0x13)
+ * @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)
+ * @unk252:                     Unknown.  (Added in dbversion 0x0c)
+ * @gapless_track_flag:         If set to 1, this track has gapless playback
+ *                              data.  (Added in dbversion 0x13)
+ * @gapless_album_flag:         If set to 1, this track does not use
+ *                              crossfading in iTunes.  (Added in dbversion
+ *                              0x13)
+ * @chapterdata_raw:            Defines where the chapter stops are in the
+ *                              track as well as what info should be
+ *                              displayed for each section of the track.
+ * @chapterdata_raw_length:     The length of the chapterdata.
+ * @artwork:                    An #Itdb_Artwork for cover art
+ * @mhii_link:                  This is set to the id of the corresponding
+ *                              ArtworkDB mhii, used for sparse artwork
+ *                              support.  (Since libgpod-0.7.0)
+ * @reserved_int1:              Reserved for future use
+ * @reserved_int2:              Reserved for future use
+ * @reserved_int3:              Reserved for future use
+ * @reserved_int4:              Reserved for future use
+ * @reserved_int5:              Reserved for future use
+ * @reserved_int6:              Reserved for future use
+ * @reserved1:                  Reserved for future use
+ * @reserved2:                  Reserved for future use
+ * @reserved3:                  Reserved for future use
+ * @reserved4:                  Reserved for future use
+ * @reserved5:                  Reserved for future use
+ * @reserved6:                  Reserved for future use
+ * @usertype:                   For use by application
+ * @userdata:                   For use by application
+ * @userdata_duplicate:         A function to duplicate #userdata
+ * @userdata_destroy:           A function to free #userdata
+ *
+ * Structure representing a track in an iTunesDB
+ *
+ * <note><para>When adding string fields don't forget to add them in
+ * itdb_track_duplicate() as well.</para></note>
+ *
+ * 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.
+ */
 struct _Itdb_Track
 {
-  Itdb_iTunesDB *itdb;       /* pointer to iTunesDB (for convenience)   */
-  gchar   *title;            /* title (utf8)                            */
-  gchar   *ipod_path;        /* name of file on iPod: uses ":" instead
-				of "/" and is relative to mountpoint    */
-  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 */
-  Itdb_Chapterdata *chapterdata; /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *subtitle;         /* see note for MHOD_ID in itdb_itunesdb.c */
-/* the following 6 are new in libgpod 0.4.2... */
-  gchar   *tvshow;           /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *tvepisode;        /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *tvnetwork;        /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *albumartist;      /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *keywords;         /* see note for MHOD_ID in itdb_itunesdb.c */
+  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
@@ -1184,199 +1484,90 @@ struct _Itdb_Track
      the lists displayed by the iPod according to "Artist, The",
      without setting the field.
   */
-  gchar   *sort_artist;      /* artist (for sorting)                    */
-  gchar   *sort_title;       /* title (for sorting)                     */
-  gchar   *sort_album;       /* album (for sorting)                     */
-  gchar   *sort_albumartist; /* album artist (for sorting)              */
-  gchar   *sort_composer;    /* composer (for sorting)                  */
-  gchar   *sort_tvshow;      /* tv show (for sorting)                   */
-/* new fields in libgpod 0.5.0 up to here */
-  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"          */
-  time_t  time_added;        /* time when added                         */
-  time_t  time_modified;     /* time of last modification               */
-  time_t  time_played;       /* time of last play                       */
-  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;               /* BPM (beats per minute) of this track    */
-  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             */
+  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;           /* 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 */
-  time_t  time_released;/* date/time added to music store? 
-			   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 explicit_flag;/* If this flag is set to 1, the track is shown as
-			   explicit content in iTunes. Otherwise set this flag
-			   to 0.*/
-  guint32 unk148;     /* unknown - used for Apple Store DRM songs
-			 (always 0x01010100?), zero otherwise */
-  guint32 unk152;     /* unknown */
-  guint32 skipcount;  /* Number of times the track has been skipped.
-			 Formerly unk156 (added in dbversion 0x0c) */
-  guint32 recent_skipcount; /* number of times track was skipped since
-			       last sync */
-  guint32 last_skipped;/* Date/time last skipped. Formerly unk160
-			 (added in dbversion 0x0c) */
-  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. (With iTunes, since V0x12, this field
-			 value differs from the dbid one.) */
-  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) */
+  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;     /* Number of samples of silence before the songs
-			 starts (for gapless playback). */
-  guint64 samplecount;/* Number of samples in the song. First observed
-			 in dbversion 0x0d, and only for AAC and WAV
-			 files (for gapless playback). */
+  guint32 pregap;
+  guint64 samplecount;
   guint32 unk196;
-  guint32 postgap;    /* Number of samples of silence at the end of
-			 the song (for gapless playback). */
-  guint32 unk204;     /* unknown - added in dbversion 0x0c, first
-			 values observed in 0x0d. Observed to be 0x0
-			 or 0x1. */
-  guint32 mediatype;  /* It seems that this field denotes the type of
-		         the file on (e.g.) the 5g video iPod. 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, for TV shows only. */
-  guint32 episode_nr; /* the episode number of the track, for TV shows
-			 only - although not displayed on the iPod,
-			 the episodes are sorted by episode number. */
-  guint32 unk220;     /* Has something to do with protected files -
-			 set to 0x0 for non-protected files. */
+  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;/* some magic number needed for gapless playback
-			  (added in dbversion 0x13) It has been observed
-			  that gapless playback does not work if this is
-			  set to zero. This number is related to the the
-			  filesize in bytes, but it is a couple of bytes
-			  less than the filesize. Maybe ID3 tags
-			  etc... taken off? */
+  guint32 gapless_data;
   guint32 unk252;
-  guint16 gapless_track_flag; /* if 1, this track has gapless playback data
-			         (added in dbversion 0x13) */
-  guint16 gapless_album_flag; /* if 1, this track does not use crossfading
-			         in iTunes (added in dbversion 0x13) */
+  guint16 gapless_track_flag;
+  guint16 gapless_album_flag;
 
   /* This is for Cover Art support */
   struct _Itdb_Artwork *artwork;
 
-    /* 200805 */
+  /* This is for sparse artwork support, new in libgpod-0.7.0 */
   guint32 mhii_link;
 
   /* reserved for future use */