== Synopsis

itch - Control Helper for ITunes - Perform operations on iTunes tracks.


== Usage

Program help:
-h, --help Display program help.
Playback controls:
-p, --play-pause If currently paused, begin playing. If currently playing, pause playback.
--pause Pause playback.
--play Play the current track.
-s, --stop Stop playback.
-n, --next-track Go to the next track.
-N, --previous-track Go to the previous track.
-m, --mute Mute the audio.
-M, --unmute Unmute the audio.
-v, --volume number Set the volume to X percentage points.
--volume-down [number] Decrease the volume by X percentage points (default 10).
--volume-up [number] Increase the volume by X percentage points (default 10).
--scan-to seconds Scan to an offset X seconds within the current track.
--scan-backwards [seconds] Scan backwards X seconds within the current track (default 10).
--scan-forwards [seconds] Scan forwards X seconds within the current track (default 10).
--play-file name Play the specified file or folder.
Info on selected tracks:
-i, --print-info format For each track, print information in the given format. If the following strings appear in the given format, they will be replaced with the corresponding track information:
"%a": artist
"%e": encoding
"%A": album
"%b": BPM (beats per minute)
"%c": composer
"%C": comment
"%d": disc number
"%D": disc count
"%E": Enabled status ("enabled" or "disabled")
"%l": location (file name/URL)
"%p": play count
"%q": equalizer
"%g": genre
"%G": grouping
"%n": name (title)
"%r": rating
"%s": skip count
"%t": track number
"%T": track count
"%v": volume adjustment
"%y": year
"%%": percent sign
General iTunes controls:
-a, --add-file name Add the specified file or folder to the library.
-q, --quit Exit iTunes.
--open-url url Open the given URL.
--goto-store-home-page Go to the Store.
--update-ipod Update the iPod.
Playlist selection:
--library Operation will include the entire iTunes library. Used by default unless other libraries are selected.
--current-playlist Operation will include the current playlist.
--playlist name Operation will include the named playlist. (This option can occur more than once.)
--all-playlists Operation will include all playlists.
--create-playlist name Create a playlist with the specified name and include it in the operation. (This option can occur more than once.)
--delete-playlist name Delete the playlist with the specified name. (This option can occur more than once.)
Track selection:
-f, --find string Operation will include all tracks in the specified playlist(s) where any field matches the specified string. (This option can occur more than once.)
-c, --current-track Operation will inclue the current track.
--selected-tracks Operation will include the selected tracks.
--all-tracks Operation will include all tracks in the specified playlist(s).
--visible-find string Operation will include all tracks in the specified playlist(s) where any visible field matches the specified string. (This option can occur more than once.)
--find-artist string Operation will include all tracks in the specified playlist(s) where the artist matches the specified string. (This option can occur more than once.)
--find-album string Operation will include all tracks in the specified playlist(s) where the album matches the specified string. (This option can occur more than once.)
--find-composer string Operation will include all tracks in the specified playlist(s) where the composer matches the specified string. (This option can occur more than once.)
--find-track-name string Operation will include all tracks in the specified playlist(s) where the track name matches the specified string. (This option can occur more than once.)
-F, --play-found Play the first of the selected tracks.
Set track info:
--set-artist name Set the artist for each track.
--set-album name Set the album for each track.
--set-bpm number Set the beats per minute for each track.
--set-comment string Set the comment for each track.
--set-composer string Set the composer for each track.
--set-disc-number number For each track, set the disc number. (Used with multi-disc albums.)
--set-disc-count number For each track, set the number of discs in the album. (Used with multi-disc albums.)
--set-enabled Enable the check box for each track.
--set-disabled Disable the check box for each track.
--set-eq name Set the equalizer to the named preset. Use 'None' to disable.
--set-genre name Set the genre for each track.
--set-grouping string Set the grouping for each track.
--set-name name Set the name (title) for each track.
--set-play-count number Set the play count for each track.
--set-rating number Set the rating for each track. Valid values are 0 through 5.
--set-skip-count number Set the skip count for each track.
--set-track-number number For each track, set its album track number.
--set-track-count number For each track, set the number of tracks on its album.
--set-track-volume percent Set the volume adjustment percentage for each track, from -100 to 100. Negative numbers decrease the volume, positive numbers increase it. 0 means no adjustment.
--set-year number Set the year of publication for each track.


== Description

Allows control of iTunes for Windows via a command line.
It provides all basic media controls such as play, pause, stop, next/previous track, and volume adjustment.
In addition, you can search for tracks in any given playlist and perform operations on them, or retrieve information regarding them.
You can also add tracks to the library, sync your iPod, and perform a variety of other operations.


== Examples

Get help:

itch -h

Start up iTunes (if necessary) and begin playing:

itch -p

Find and play a song:

itch -f "mookid" -F

Find all songs from an artist, show basic info on them, and play the first found:

itch -f "aphex twin" -i "%a - %A - %t - %n" -F

You can improve readability in batch files by specifying options in long form:

itch --find "aphex twin" --print-info "%a - %A - %t - %n" --play-found


== Installation

* Windows (without Ruby): Visit the project site (see below), download and run the Windows installer.

* With Ruby: install itch}}


== Building from Source

The setup should be fairly standard for anyone familiar with Rake. There are a few external dependencies; see below for links.

Get the source from the project site.

Change into the project directory. Run "rake -T" for a list of targets. You'll need RubyScript2Exe to build a Windows executable, or NSIS to build a Windows installer. Building a gem should work out of the box. "rake" builds an installer and a gem by default.


== See Also

Project Site: http://code.google.com/p/itunes-control/

Nullsoft Scriptable Install System: http://nsis.sourceforge.net/

RubyScript2Exe: http://www.erikveen.dds.nl/rubyscript2exe/index.html

iTunes: http://www.apple.com/itunes/


== Thanks

Thanks to Eden Li and Gary Wright for various Ruby advice and assistance.

NullSoft Scriptable Install System is used to make the Windows installer; thanks to its authors.

RubyScript2Exe is used to make the Windows executable; thanks to Erik Veenstra for pulling off this seemingly impossible feat!


== Author

Copyright Jay McGavren, [email protected]


== License

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Please see the LICENSE.txt file for the full license.


== Legal

iTunes is a trademark of Apple Inc.

Windows is a registered trademark of Microsoft Corporation in the United States and other countries.

itch is not endorsed, licensed, or sponsored by Apple Inc or Microsoft Corporation.