|
Packit |
29108b |
libgpod is a library meant to abstract access to an iPod content. It
|
|
Packit |
29108b |
provides an easy to use API to retrieve the list of files and playlist
|
|
Packit |
29108b |
stored on an iPod, to modify them and to save them back to the iPod.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
This code was originally part of gtkpod (www.gtkpod.org). When the iPod
|
|
Packit |
29108b |
content parsing code was made to be self-contained with gtkpod 0.93,
|
|
Packit |
29108b |
we chose to put this code in a separate library so that other project
|
|
Packit |
29108b |
can benefit from it without duplicating code.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
Currently (2010-03-23) libgpod supports writing to all "classic" iPod models,
|
|
Packit |
29108b |
all iPod Nanos, iPod Minis and iPhones and iPod Touch. iPod Nano 5th Gen. and
|
|
Packit |
29108b |
iPhone/iPod Touch support is "partial" in the sense that a database with at
|
|
Packit |
29108b |
least one song written by iTunes is needed the first time you use the iPod
|
|
Packit |
29108b |
with libgpod. For these models, it's also highly recommended to get the
|
|
Packit |
29108b |
provided udev/hal callout to work for proper support. Older iPod Shuffle models
|
|
Packit |
29108b |
are supported, but the new button-less ones (3rd and 4th Gen.) are not. Please
|
|
Packit |
29108b |
get in touch if you want to hack on adding support for that.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
For supported models, covert art and photos are supported in addition to
|
|
Packit |
29108b |
manipulating the music database.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
If you decide to make improvements, or have bug fixes to report or contribute,
|
|
Packit |
29108b |
just drop a mail to Gtkpod-devel@lists.sourceforge.net (due to too much spam,
|
|
Packit |
29108b |
the mailing list is unfortunately subscriber-only).
|
|
Packit |
29108b |
|
|
Packit |
29108b |
----------------------------------------------------------------------
|
|
Packit |
29108b |
|
|
Packit |
29108b |
Quick HOWTO use libgpod for audio
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_parse(): read the iTunesDB and ArtworkDB
|
|
Packit |
29108b |
itdb_write(): write the iTunesDB and ArtworkDB
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_parse() will return a Itdb_iTunesDB structure with GLists
|
|
Packit |
29108b |
containing all tracks (each track is represented by a Itdb_Track
|
|
Packit |
29108b |
structure) and the playlists (each playlist is represented by a
|
|
Packit |
29108b |
Itdb_Playlist structure).
|
|
Packit |
29108b |
|
|
Packit |
29108b |
A number of functions for adding, removing, duplicating tracks are
|
|
Packit |
29108b |
available. Please see itdb.h for details (itdb_track_*()).
|
|
Packit |
29108b |
|
|
Packit |
29108b |
In each Itdb_Playlist structure you can find a GList called 'members'
|
|
Packit |
29108b |
with listing all member tracks. Each track referenced in a playlist
|
|
Packit |
29108b |
must also be present in the tracks GList of the iTunesDB.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
The iPod must contain one master playlist (MPL) containing all tracks
|
|
Packit |
29108b |
accessible on the iPod through the
|
|
Packit |
29108b |
Music->Tracks/Albums/Artists... menu. Besides the MPL there can be a
|
|
Packit |
29108b |
number of normal playlists accessible through the Music->Playlists
|
|
Packit |
29108b |
menu on the iPod. Tracks that are a member of one of these normal
|
|
Packit |
29108b |
playlists must also be a member of the MPL.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
The Podcasts playlist is just another playlist with some internal
|
|
Packit |
29108b |
flags set differently. Also, member tracks in the Podcasts playlist
|
|
Packit |
29108b |
are not normally members of the MPL (so on the iPod they will only
|
|
Packit |
29108b |
show up under the Podcasts menu). All tracks referenced must be in the
|
|
Packit |
29108b |
tracklist of the Itdb_iTunesDB, however.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
A number of functions to add/remove playlists, or add/remove tracks
|
|
Packit |
29108b |
are available. Please see itdb.h for details (itdb_playlist_*()).
|
|
Packit |
29108b |
|
|
Packit |
29108b |
Each track can have a thumbnail associated with it. You can retrieve a
|
|
Packit |
29108b |
GdkPixmap of the thumbnail using itdb_artwork_get_pixbuf(). You can
|
|
Packit |
29108b |
remove a thumbnail with itdb_track_remove_thumbnails(). And finally,
|
|
Packit |
29108b |
you can set a new thumbnail using itdb_track_set_thumbnails().
|
|
Packit |
29108b |
|
|
Packit |
29108b |
Please note that iTunes additionally stores the artwork as tags in the
|
|
Packit |
29108b |
original music file. That's also from where the data is read when
|
|
Packit |
29108b |
artwork is displayed in iTunes, and there can be more than one piece
|
|
Packit |
29108b |
of artwork. libgpod does not store the artwork as tags in the original
|
|
Packit |
29108b |
music file. As a consequence, if iTunes attempts to access the
|
|
Packit |
29108b |
artwork, it will find none, and remove libgpod's artwork. Luckily,
|
|
Packit |
29108b |
iTunes will only attempt to access the artwork if you select a track
|
|
Packit |
29108b |
in iTunes. (To work around this, gtkpod keeps a list of the original
|
|
Packit |
29108b |
filename of all artwork and silently adds the thumbnails if they were
|
|
Packit |
29108b |
'lost'. Your application might want to do something similar, or you
|
|
Packit |
29108b |
can supply patches for (optionally!) adding tags to the original music
|
|
Packit |
29108b |
files.)
|
|
Packit |
29108b |
|
|
Packit |
29108b |
The Itdb_iTunesDB, Itdb_Playlist and Itdb_Track structures each have a
|
|
Packit |
29108b |
userdata and a usertype field that can be used by the application to
|
|
Packit |
29108b |
store application-specific additional data. If userdata is a pointer
|
|
Packit |
29108b |
to an external structure, you can supply a ItdbUserDataDuplicateFunc
|
|
Packit |
29108b |
and a ItdbUserDataDestroyFunc so that this data can be duplicated
|
|
Packit |
29108b |
or freed automatically with a call to the library _duplicate()/_free()
|
|
Packit |
29108b |
functions.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
For more information I would advice to have a look at gtkpod's source
|
|
Packit |
29108b |
code. You can also ask questions on the developer's mailing list:
|
|
Packit |
29108b |
gtkpod-devel at lists dot sourceforge dot net
|
|
Packit |
29108b |
|
|
Packit |
29108b |
|
|
Packit |
29108b |
Jörg Schuler (jcsjcs at users dot sourceforge dot net)
|
|
Packit |
29108b |
|
|
Packit |
29108b |
----------------------------------------------------------------------
|
|
Packit |
29108b |
|
|
Packit |
29108b |
Quick HOWTO use libgpod for photos
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_parse():
|
|
Packit |
29108b |
Read an existing PhotoDB.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_create():
|
|
Packit |
29108b |
Create a new Itdb_PhotoDB structure. The Photo Library Album is
|
|
Packit |
29108b |
(first album) is created automatically.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_add_photo(), itdb_photodb_add_photo_from_data():
|
|
Packit |
29108b |
Add a photo to the PhotoDB (from file or from a chunk of
|
|
Packit |
29108b |
memory). It is automatically added to the Photo Library Album
|
|
Packit |
29108b |
(first album), which is created if it does not exist already.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_photoalbum_create():
|
|
Packit |
29108b |
Create and add a new photoalbum.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_photoalbum_add_photo():
|
|
Packit |
29108b |
Add a photo (Itdb_Artwork) to an existing photoalbum.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_photoalbum_remove():
|
|
Packit |
29108b |
Remove an existing photoalbum. Pictures can be kept in the
|
|
Packit |
29108b |
Photo Library or automatically removed as well.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_remove_photo():
|
|
Packit |
29108b |
Remove a photo either from a photoalbum or completely from the database.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_write():
|
|
Packit |
29108b |
Write out your PhotoDB.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_free():
|
|
Packit |
29108b |
Free all memory taken by the PhotoDB.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_photodb_photoalbum_by_name():
|
|
Packit |
29108b |
Find the first photoalbum with a given name or the Photo
|
|
Packit |
29108b |
Library Album if called with no name.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
|
|
Packit |
29108b |
If you cannot add photos because your iPod is not recognized, you may
|
|
Packit |
29108b |
have to set the iPod model by calling
|
|
Packit |
29108b |
|
|
Packit |
29108b |
itdb_device_set_sysinfo (db->device, "ModelNumStr", model);
|
|
Packit |
29108b |
|
|
Packit |
29108b |
For example, "MA450" would stand for an 80 GB 6th generation iPod
|
|
Packit |
29108b |
Video. See itdb_device.c for a list of supported models.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
This information will be written to the iPod when the PhotoDB is saved
|
|
Packit |
29108b |
(itdb_device_write_sysinfo() is called).
|
|
Packit |
29108b |
|
|
Packit |
29108b |
Have a look at the following test-photos test program in the tests/
|
|
Packit |
29108b |
subdirectory for an example of how to use the interface.
|
|
Packit |
29108b |
|
|
Packit |
29108b |
|
|
Packit |
29108b |
Jörg Schuler (jcsjcs at users dot sourceforge dot net)
|
|
Packit |
29108b |
|
|
Packit |
29108b |
----------------------------------------------------------------------
|