What is GNUpod?
---------------
With GNUpod, you can use your iPod on GNU/Linux and
many other Operating Systems (with a useable Port
of Perl5 + FireWire / USB2 Support)


Installing GNUpod
-----------------
Running
 # ./configure
 # make install
should be enough.


Using GNUpod
------------
After installing GNUpod, you can use
# info gnupod

to view GNUpod's info page.

An HTML Version of the info-page is also
included in this package (see doc/)

You should also read the FAQ


GNUpod commands (cheatsheet)
----------------------------

gnupod_INIT.pl      INIT a new iPod (create empty Database + Directories)
gnupod_addsong.pl   Add files
gnupod_check.pl     Check for 'zombie' files
gnupod_otgsync.pl   Handles On-The-Go Sync (not for humans)
gnupod_search.pl    Search ;)
mktunes.pl          Convert the GNUtunesDB.xml to a iTunesDB
tunes2pod.pl        Convert the iTunesDB into a GNUtunesDB.xml

You'll have to use mktunes.pl if you added/deleted/changed something
on the iPod.


Supported iPods
---------------

* All iPods up to late 2007 (Touch, Classic and Nano) are supported,
  GNUpod supports:

 - ALAC, MP4 (AAC), MP3 and PCM
 - MP4  Videos
 - On-The-Fly re-encoding from flac, ogg, avi, etc..
 - Normal Playlists
 - On-The-Go Playlists
 - GNUpod extended playlists (<regex />)
 - iTunes Smart-Playlists (not supported by all models)
 - Artwork Support for Video and Nano iPods

 See: http://support.apple.com/kb/HT1353 (Identifying iPod models)
 and  http://en.wikipedia.org/wiki/IPod

*Note*  - GNUpod does *not* support DRM-Stuff!

About m4a + GNUpod
===================

GNUpod can read .m4a files and add them to your iPod.

GNUpod also provides a nice little tool to read m4a
TAGS on *nix, see tools/m4a-info.pl

Use it like this:


# tools/m4a-info.pl myaacfile.m4a


It's also possible to CREATE .m4a files with
Linux/BSD/Waschmaschine

You'll need FAAC 1.24 (<-- yes: version >= 1.24) for this.

* Get it at www.audiocoding.com
* Install FAAD2 (NOT FAAC, You'll have to install FAAD2 before
  installing faac, because FAAD2 provides the mp4v2 lib used
  by faac!)
* Install FAAC >= 1.24
* Encode your Files with the -w switch, you can also set the tags
  (See: faac --help)

  Example: faac -w --title mytitle file.wav

Now you can add the file using gnupod_addsong.pl

# gnupod_addsong.pl file.m4a
# mktunes.pl

:)

This is a collection of notes for the gnupod developers.
Nothing interesting for users.
These aren't the droids you're looking for. Move along! :-)

Minimal testing:
> gnupod_INIT.pl /mnt/empty
> gnupod_addsong
> mktunes.pl
> tunes2pod.pl --force
> mktunes.pl
> check if your ipod can read the result

Release checklist
* technical
  * Set new version in first line of configure.ac
  * run autotests
  * make release and sign with the gpg key
  * upload to blinkenlights.ch and gnu.org
* pr
  * Update http://www.blinkenlights.ch/ccms/ipod(e).html
  * Update http://www.gnu.org/software/gnupod/
  * Add news item on http://savannah.gnu.org/projects/gnupod
  * Update last release http://freshmeat.net/projects/gnupod/
  * Announce new release on mailing list
  * Contact Debian package maintainer of "gnupod-tools"

Upstream contacts
* MP3::Info
  * Dan Sully < daniel @ electricrain . com >
  * http://bugs.slimdevices.com/

About SmartPlaylist-Support
===========================

GNUpod can read and write SmartPlaylists.
Please note that this feature isn't supported
for iPods running Firmware 1.x
(Because GNUpod can only do 'liveupdates' at the moment..)

Use the <regex.. stuff if you own a 1.x iPod.

Smartplaylists are powerful but creating them is somewhat ugly.

An example for a SmartPlaylist:

   <smartplaylist checkrule="both" limititem="song" limitsort="random" limitval="55" liveupdate="1" name="Example SPL1" >
     <spl action="gt" field="bitrate" string="189" />
   </smartplaylist>

This Playlist includes 55 songs (limitval/limititem) sort by random (limitsort)
with a Bitrate > 189 (<spl field)

Please note that you have to set liveupdate="1" or the Playlist will be empty :)
[Because GNUpod can only do liveupdates atm..]


It's a bit complicated, maybe you should have a look at
http://blinkenlights.ch/gnupod/mkspl.html
 [or doc/mkspl.html]
You can use Mozilla (needs JS & DOM) to create
SmartPlaylists via Klickibunti interface ;)



##### SMARTPLAYLIST
CHECKRULE:
 limit (Only match <smartplaylist ... stuff, don't watch <spl.. entries)
 spl   (Only match <spl entries, don't limit or sort)
 both  (Match both items)

LIMITITEM:
 minute
 megabyte
 song
 hour
 gigabyte

LIMITSORT:
 random
 title
 album
 artist
 genre
 addtime_high
 addtime_low
 playcount_high
 playcount_low
 lastplay_high
 lastplay_low
 rating_high
 rating_low

##### SPL
FIELD for use with action IS/CONTAINS/STARTWITH/ENDWITH (use NOT_ for 'not' -> 'NOT_IS'   [STRINGS]
 TITLE
 ALBUM
 ARTIST
 GENRE
 FDESC
 COMMENT
 COMPOSER
 GROUP

FIELD for use with action eq/gt/lt/range (Use ! for 'not' -> '!eq') [NUM]
 bitrate
 srate
 year
 changetime (MAC TIMESTAMP!)
 tracknum
 size
 time
 addtime (MAC TIMESTAMP!)
 playcount
 lastplay (MAC TIMESTAMP!)
 cdnum
 rating (20 = 1 star / 60 = 3 starts ...-> STARTS*20 = Value)
 compilation (0 or 1)
 bpm

There is also a 'within' field for use with
 changetime
 addtime
 lastplay

 The 'value' of a within field needs a suffix: _day / _week / _month
 So you could write
   <spl action="within" field="lastplay" value="2_month"/>
 to add all songs played within the last 2 months.
 You could also use a ! to invert the result: (=NOT within)
   <spl action="!within" field="lastplay" value="2_month"/>