Scripts for iTunes - Documentation
Introduction
This collection of scripts can be used to control iTunes.
You can use them from the command line, in a batch (command) file, or you
can assign them to the special controls keys on a multimedia keyboard (such
as "Play", "Next", or "Previous").
These scripts are free. If you find them useful, please consider registering at the
Maximized Software web site.
Registering will let you keep up to date on enhancements to these scripts, as well
as provide an opportunity to send us comments on them, or to suggest other iTunes or iPod products.
These scripts only require iTunes (not an iPod). You can always download the latest version
of iTunes from the iTunes website.
iTunes and iPod are registered trademarks of Apple Computer, Inc.
Scripts for iTunes is a trademark of Maximized Software, Inc.
Installation
To install Scripts for iTunes, simply run the setup program (setup.exe). You will
be asked where to install the scripts. Choose any folder that you desire. By default,
setup will place the scripts into a new folder named Scripts that it creates in
C:\Program Files\iTunes.
Using the scripts
Most people will want to use the scripts to control iTunes via their multimedia keyboard.
To do this, open the configuration utility that came with your computer or keyboard.
For example, on a Dell computer this utility is called DellTouch, and can be started
(under Windows XP) by clicking on the Start button, choosing All Programs, choosing Accessories,
choosing System Tools, and finally choosing DellTouch. You may also have a small icon in the
Windows system tray that looks like a key cap; clicking on this icon may bring up the configuration
utility.
Once you have the configuration utility open, use it to configure the keys that you would
like to use to control iTunes. For example, with the DellTouch utility, you would click on
the picture of a button such as Play. This opens a window which lets you configure this button.
Choose the option to specify an application to run, and browse to the desired script. You may
also need to change the text assigned to the button label.
The directions for configuring your system may be different. For example, Microsoft multimedia
keyboards are configured with the Keyboard applet of the Control Panel.
Here are a list of the recommended keyboard mappings to make:
| Key |
Script |
| Play / Pause |
C:\Program Files\iTunes\Scripts\PlayPause.vbs |
| Previous |
C:\Program Files\iTunes\Scripts\BackTrack.vbs |
| Next |
C:\Program Files\iTunes\Scripts\Next.vbs |
| Stop |
C:\Program Files\iTunes\Scripts\Stop.vbs |
It is not recommended to reconfigure the volume control keys (up, down, mute)
to use Scripts for iTunes. The scripts will affect the volume within iTunes only, and
will not affect any other sounds played on your PC. Instead, you should let the
multimedia volume keys continue to operate your entire sound card as they normally do.
To use the scripts from the command line or in a batch file, simply call the script
as you would any other program. See the description of each script below for details
on its syntax and any parameters it may support or require.
Uninstall
To uninstall Scripts for iTunes, open the Control Panel, choose Add / Remove Programs,
then select Scripts for iTunes and click on Remove.
If you have configured keys on your multimedia keyboard to use the scripts, you
will need to reconfigure the keys after removing the scripts.
Script reference
BackTrack.vbs
Description:
This script will cause iTunes to restart the current track, or go to the prior track
if it is already at (or near) the start of the current track.
Note that you can use the Previous script to always return
to the prior track regardless of your position in the current track.
Syntax:
BackTrack
FastForward.vbs
Description:
This script will cause iTunes to begin fast-forwarding through the current track.
To resume playing, run the Play or PlayPause script.
Syntax:
FastForward
GetPlayState.vbs
Description:
This script is useful for creating batch (command) files. This script will immediately exit,
setting the ERRORLEVEL value to indicate the current play state of iTunes.
Here is a list of the possible values returned by this script:
| ERRORLEVEL |
Description |
| 0 |
Stopped |
| 1 |
Playing |
| 2 |
Fast-forwarding |
| 3 |
Rewinding |
Syntax:
GetPlayState
Example:
Here is a sample batch (command) file:
@echo off
GetPlayState
if ERRORLEVEL 3 goto Rewinding
if ERRORLEVEL 2 goto FastForwarding
if ERRORLEVEL 1 goto Playing
rem Else, must be ERRORLEVEL 0
echo iTunes is currently stopped or paused.
goto Done
:Rewinding
echo iTunes is currently rewinding.
goto Done
:FastForwarding
echo iTunes is currently fast-forwarding.
goto Done
:Playing
echo iTunes is currently playing.
:Done
rem End of batch file
Mute.vbs
Description:
This script sets or toggles the muting within iTunes.
Note that this is a different muting control than
that provided by your sound card (which can be easily
accessed by double-clicking on the speaker icon in the
system tray).
Normally you will want to keep iTunes set to its maximum
volume and adjust your sound card's volume or muting using the
normal mapping of your multimedia keyboard. Therefore,
use of this script to control iTunes muting is
not recommended (unless you've got a special need in mind).
Also see the SetVolume, VolumeUp,
and VolumeDown scripts.
Syntax:
Mute [on|off]
Examples:
Here are some examples:
| Example |
Description |
| Mute |
Toggles iTunes' muting |
| Mute on |
Turns on muting |
| Mute off |
Turns off muting (ie, restores sound) |
Next.vbs
Description:
This script causes iTunes to go to the next song in the current playlist.
Syntax:
Next
Pause.vbs
Description:
This script pauses iTunes. Running this script when iTunes is already paused will have no effect.
Syntax:
Pause
Play.vbs
Description:
This script makes sure that iTunes is playing. If paused, it will start playing.
If fast-forwarding or rewinding, it will resume normal playback.
Syntax:
Play
PlayFile.vbs
Description:
This script will cause iTunes play the specified file.
The file will also be added to your iTunes "Library" if it isn't already in it.
Be sure to enclose the file name path in quotes.
Syntax:
PlayFile "Full path to file"
Example:
PlayFile "C:\My Documents\My Music\Devo\Freedom of Choice\Whip It.mp3"
PlayPause.vbs
Description:
This script toggles iTunes between playing and pausing.
It can also resume playing if currently fast-forwarding or rewinding.
Syntax:
PlayPause
PlayPlaylist.vbs
Description:
This script will cause iTunes play the first song in the specified playlist.
The /playlist: prefix is optional since there is only one possible parameter.
Be sure to enclose the playlist name in quotes if it contains spaces.
Syntax:
PlayPlaylist [/playlist:]"Name of playlist"
Examples:
PlayPlaylist "5 stars"
PlayPlaylist /playlist:"5 stars"
PlaySong.vbs
Description:
This script will cause iTunes play the specified song. You must specify the song name.
In addition, you can also specify the artist or album if desired.
If you only specify the song name, then you do not need to use the /song: prefix.
But if you choose to also specify artist and/or album, then each parameter needs to be prefixed.
If the desired resides in several different playlists, you can control which
playlist is selected by using the /playlist: parameter. If you
do not specify a playlist name, then the song will be played from the normal Library.
If you specify a playlist, then the song will be played from the specified playlist,
and when the song has finished then the specified playlist will continue playing.
Note that this script supports partial matches, so several tracks might
match the song, album, or artist name. You can specify as many parameters as necessary
to indicate which specific track you want to play.
Syntax:
PlaySong [/song:]"Name of song"
[/album:"Name of album"]
[/artist:"Name of artist"]
[/playlist:"Name of playlist"]
Be sure to enclose the names in quotes if they include spaces.
Examples:
PlaySong "Whip It"
PlaySong /song:"Whip It"
PlaySong /song:"Whip It" /album:"Freedom of Choice"
PlaySong /song:"Whip It" /artist:"Devo"
PlaySong /song:"Whip It" /album:"Freedom of Choice" /artist:Devo
PlaySong /song:"Whip It" /album:"Freedom of Choice" /artist:"Devo"
PlaySong /song:"Whip It" /album:"Freedom of Choice" /artist:"Devo" /playlist:"5 stars"
Previous.vbs
Description:
This script tells iTunes to play the previous track.
Note that this will always move to the previous track,
regardless of the position within the current track.
You can use the script BackTrack to use the "back track"
feature of iTunes, which restarts the current track if you're
at least a few seconds into it, or goes to the previous track
if you're within the first few seconds of the current track.
Syntax:
Previous
Rewind.vbs
Description:
This script causes iTunes to rewind through the current track.
To resume playing, run the Play or PlayPause script.
Syntax:
Rewind
ScriptEngineCache-Start.vbs
Description:
You may want to use this script if you find that your system sometimes takes a while to run
the script that you have associated with a key on a multimedia keyboard.
This script runs silently in a continuous loop, thus keeping the Windows Script Host loaded in
memory. On some systems, this might make subsequent scripts mapped to the keys on a multimedia
keyboard execute more quickly because the Windows Script Host is already loaded in memory.
This script works by setting a flag in the registry, then checking for the existence of the
flag every five seconds. This script sleeps in-between checking the registry, so it should have
no noticeable effect on system performance.
To stop this script from running, just run the
ScriptEngineCache-Stop script.
The ScriptEngineCache-Stop script will clear the flag in the registry which
tells the ScriptEngineCache-Start script to keep running.
Please note that some utilities may warn you that this script is attempting to
write to the registry. You may need to tell these utilities that it is okay for
this script to execute normally.
You may want to add a shortcut to this script to your Startup menu to ensure that it is
always running.
Syntax:
ScriptEngineCache-Start
ScriptEngineCache-Stop.vbs
Description:
Running this script will cause the ScriptEngineCache-Start script
to stop running.
See the ScriptEngineCache-Start script for more details.
Please note that some utilities may warn you that this script is attempting to
write to the registry. You may need to tell these utilities that it is okay for
this script to execute normally.
Syntax:
ScriptEngineCache-Stop
SetVolume.vbs
Description:
This script sets the volume within iTunes.
Note that this is a different volume control than
that provided by your sound card (which can be easily
accessed by double-clicking on the speaker icon in the
system tray).
Normally you will want to keep iTunes set to its maximum
volume and adjust your sound card's volume using the
normal mapping of your multimedia keyboard. Therefore,
use of this script to control the iTunes volume is
not recommended (unless you've got a special need in mind).
The iTunes volume ranges from 0 to 100. You can use this script
with a given number to set the volume at a specific level, or precede
the number with a + or - to indicate a relative amount of change.
Also see the VolumeUp and VolumeDown scripts.
Syntax:
SetVolume [+|-]number
Examples:
Here are some examples:
| Example |
Description |
| SetVolume 0 |
Sets volume to "off" (but not the same as "mute") |
| SetVolume 100 |
Sets volume to highest possible value |
| SetVolume 50 |
Sets volume to 50 (ie, half) |
| SetVolume -10 |
Turns volume down by 10 points |
Stop.vbs
Description:
This script stops iTunes, regardless of its current mode.
Note that "stopping" means that iTunes will stop any playback
and return to the beginning of the current track.
Of course, this is different than pausing.
Syntax:
Stop
VolumeDown.vbs
Description:
This script decrements the volume within iTunes by 10 points.
Note that this is a different volume control than
that provided by your sound card (which can be easily
accessed by double-clicking on the speaker icon in the
system tray).
Normally you will want to keep iTunes set to its maximum
volume and adjust your sound card's volume using the
normal mapping of your multimedia keyboard. Therefore,
use of this script to control the iTunes volume is
not recommended (unless you've got a special need in mind).
Also, see the SetVolume script.
Syntax:
VolumeDown
VolumeUp.vbs
Description:
This script increments the volume within iTunes by 10 points.
Note that this is a different volume control than
that provided by your sound card (which can be easily
accessed by double-clicking on the speaker icon in the
system tray).
Normally you will want to keep iTunes set to its maximum
volume and adjust your sound card's volume using the
normal mapping of your multimedia keyboard. Therefore,
use of this script to control the iTunes volume is
not recommended (unless you've got a special need in mind).
Also, see the SetVolume script.
Syntax:
VolumeUp
Scheduling an event
Want to wake up to iTunes? You can use Windows' Scheduled Tasks feature
to play a song or playlist at any desired time. Here's how:
Open Control Panel, and choose Scheduled Tasks.
Choose Add Scheduled Task.
In the window where you select the program to run, click on the Browse... button.
Navigate to the desired script (such as PlaySong
or PlayPlaylist). These scripts are normally
installed in a folder such as C:\Program Files\iTunes\Scripts.
Give your task a name, and fill out the information that tells Windows when
to run this task. Enter a user name and password if necessary.
On the final window of the Scheduled Task Wizard, make sure that the checkbox
labelled "Open advanced properties for this task when I click Finish" is checked, then
click Finish.
In the properties window for this task, append any necessary parameters to
the end of the Run command (such as song name or playlist name). Be sure to enclose
in quotes any parameter values which include spaces (as described in the documentation
above).
You can also change the Run command parameters for any scheduled task at any time
by opening Control Panel, choosing Scheduled Tasks, then right-clicking on the task
and choosing Properties.
