![]() |
![]() |
![]() |
libgpod Reference Manual | ![]() |
---|---|---|---|---|
Itdb_Track; 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); 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);
These functions and structures are for storing and retrieving information about an iPod 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 "/" 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 */ gpointer chapterdata; /* not yet supported. Help welcome. */ 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 */ /* 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; /* 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 */ 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 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 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) */ 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 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 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 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) */ /* 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; /* reserved for future use */ gint32 reserved_int1; gint32 reserved_int2; gint32 reserved_int3; gint32 reserved_int4; gint32 reserved_int5; gint32 reserved_int6; gpointer reserved1; 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;
typedef enum { ITDB_MEDIATYPE_AUDIO = 0x0001, ITDB_MEDIATYPE_MOVIE = 0x0002, ITDB_MEDIATYPE_PODCAST = 0x0004, ITDB_MEDIATYPE_AUDIOBOOK = 0x0008, ITDB_MEDIATYPE_MUSICVIDEO = 0x0020, ITDB_MEDIATYPE_TVSHOW = 0x0040, } Itdb_Mediatype;
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
|
void itdb_track_free (Itdb_Track *track);
Frees the memory used by track
track : |
an Itdb_Track |
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 |
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 |
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* itdb_track_duplicate (Itdb_Track *tr);
Duplicates an existing track
tr : |
an Itdb_Track |
Returns : | a newly allocated Itdb_Track |
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.
|
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
|
void itdb_track_id_tree_destroy (GTree *idtree);
Frees the memory used by idtree
idtree : |
a GTree |
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
|
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. |
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, ie 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. |
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, ie 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. |
void itdb_track_remove_thumbnails (Itdb_Track *track);
Removes the thumbnails associated with track
track : |
an Itdb_Track |