====== iTunes Plugin for Indigo ======

<color red>Note:</color> iTunes 11 support was added to v1.1.0 of the plugin delivered with Indigo 6.

This plugin is the basic iTunes integration plugin. You may create as many "iTunes Server" devices as you have on your network (but only one per iTunes instance as defined by iTunes running on a Mac - you can't have multiple iTunes server devices that are pointing to the same iTunes instance). For each of those devices, you can trigger off of various [[#device_states|state changes]] in the built-in Device State Changed trigger type and you can execute many different [[#actions|actions]] in the Actions tab. None of this requires scripting of any kind.

The old iTunes AppleScripts are included by the installer for backwards compatibility.

Indigo now includes a device state image for use with iTunes which mimics the Play/Pause button in iTunes. If the iTunes play state is "playing", the icon will show the pause symbol and vice versa. If it's "unavailable" it will be grayed out and if there's an error it will be reddish. To use just select iTunesStatus_large+, iTunesStatus_med+, or iTunesStatus_small+ in the control page editor and you'll get automatic play/pause switching icon. Works even better when you make the action a "Toggle Play/Pause" plugin action.
==== Plugin Config ====

{{:plugins:itunes_plugin_config.png|}}

The plugin's config dialog allows you to turn on extra debugging information in the Event Log. Unless you're trying to debug a problem it's probably best to leave that unchecked.

==== Creating an iTunes Server Device ====

The iTunes Plugin allows you to create iTunes Server devices. To create a new one, switch to the device view and click the **''New...''** button. This will bring up the device edit dialog:

{{:plugins:device_dialog.png|}}

As shown above, select **''Plugin''** from the **''Type:''** popup. Select **''iTunes Plugin''** from the **''Plugin:''** popup, and select **''iTunes Server''** from the **''Model:''** popup. Click on the **''Edit Device Settings...''** button and you'll see the iTunes Device Config UI:

{{:plugins:configure_device_dialog.png|}}

This dialog tells you what to do next. You must pair this new device with the iTunes Server that you intend to control. Switch to iTunes - if you're using iTunes 11, you'll see a button titled **''Remote''** in the upper right corner next to the **''iTunes Store''** button:

{{:plugins:itunes_11_pair.png?nolink|}}

Click on that button. If you're using iTunes 10.x you should see this in the outline view:

{{:plugins:itunes_outline_view.png|}}

Select **''Indigo Remote Control''**

With either case, you'll be prompted to enter a passcode:

{{:plugins:itunes_passkey_prompt.png|}}

Enter 0 0 0 0 for the passcode (or anything actually) - you'll see a message that says "Your Remote is now able to control iTunes" and an **''OK''** button. Click **''OK''**, then switch back to Indigo and click the **''Save''** button. That should save your device and you should start seeing state updates.

If you use the Pause Playback and Speak Text action and iTunes is running on a remote Mac and/or you are using Airfoil to direct sound to other devices, you may notice that the speaking and iTunes music overlap somewhat. That's what the other setting in the device config UI above is for (**''# of seconds of latency''**) - just increase that incrementally until the spoken text no longer overlaps the iTunes music. You may not need any latency adjustment.

**<color green>TIP</color>**: If you ever change the name of the Mac that you're controlling, you'll need to re-pair - just open the config dialog again and pair just like you did above. This may also help if your device can't connect to iTunes.
==== Device States ====

You can trigger off of various custom state changes on an iTunes Server device - like when the player status changes (playing, paused, etc), when the album, artist, track changes, etc.

{{:plugins:itunes_device_states.png|}}

iTunes Server device types provide you with several device states that you can use in the Trigger dialog:

  * **''Player Status Changed''** - any change to the play state of iTunes
  * **''Player Status is Playing''** - iTunes is playing
  * **''Player Status is Paused''** - iTunes is paused
  * **''Player Status is Stopped''** - iTunes is stopped
  * **''Player Status is Unavailable''** - iTunes is unavailable - it's probably not running
  * **''Player Status is Error''** - this iTunes device has an unknown error - look in the Event Log for details

  * **''Current Playlist Name''** - the current playlist that's selected in iTunes
  * **''Current Album''** - the current album name
  * **''Current Artist''** - the current artist name
  * **''Current Track''** - the current track name
  * **''Current Volume''** - the current volume level
  
  * **''Repeating Changed''** - any change in repeat status
  * **''Repeating None''** - iTunes is not repeating
  * **''Repeating Song''** - iTunes is repeating the current song
  * **''Repeating Playlist''** - iTunes is repeating the current playlist
  * **''Shuffling''** - iTunes is shuffling songs


==== Actions ====

{{:plugins:itunes_pause_and_say_dialog.png|{{:plugins:itunes_actions.png|}}

The actions provided by the plugin are as follows:

  * **''Play''** - start iTunes playing
  * **''Pause''** - pause iTunes
  * **''Toggle Play/Pause''** - toggle between playing and paused
  * **''Next Track''** - move to the next track
  * **''Previous Track''** - go back to the previous track
  * **''Restart Track''** - restart the current track

  * **''Pause iTunes and Say''** - pause iTunes (if it's running) and speak the supplied text. Restart only if it was paused to begin with.

  * **''Set Volume''** - set the volume to a specific level (0-100)
  * **''Increase Volume''** - increase the volume by a specific amount (0-100)
  * **''Decrease Volume''** - decrease the volume by a specific amount (0-100)

  * **''Set Repeat''** - set iTunes to repeat (or not)
  * **''Set Shuffle''** - set/unset shuffling

**<color red>NOTE</color>**: you can use the special variable substitution fields in the Pause iTunes and Say text field - see [[Variable Substitution]] for more information.


===== Scripting Support =====

As with all plugins, actions defined by this plugin may be executed by [[indigo_5_documentation:plugin_scripting_tutorial&#scripting_indigo_plugins|Python scripts]]. Here's the information you need to script the actions in this plugin.

**Plugin ID**: com.perceptiveautomation.indigoplugin.itunes

==== Action specific properties ====

=== Play ===

**Action id**: play

No properties for scripting required.

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("play", deviceId=135305663)</code>

=== Pause ===

**Action id**: pause

No properties for scripting required.

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("pause", deviceId=135305663)</code>

=== Toggle Play/Pause ===

**Action id**: playPause

No properties for scripting required.

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("playPause", deviceId=135305663)</code>

=== Next Track ===

**Action id**: nextTrack

No properties for scripting required.

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("nextTrack", deviceId=135305663)</code>

=== Previous Track ===

**Action id**: prevTrack

No properties for scripting required.

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("prevTrack", deviceId=135305663)</code>

=== Restart Track ===

**Action id**: restartTrack

No properties for scripting required.

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("restartTrack", deviceId=135305663)</code>

=== Pause and Speak Text ===

**Action id**: pauseAndSay

Properties for scripting:

|  //''message''//  |the string to speak, which may include variable substitution markup - ignored (and not required) if 'speakLastMessage' is True  |
|  //''speakLastMessage''//  |boolean specifying if the last spoken message should be repeated  |

Example:

<code>itunesId = "com.perceptiveautomation.indigoplugin.itunes"
itunesPlugin = indigo.server.getPlugin(itunesId)
if itunesPlugin.isEnabled():
	myWeatherStation = indigo.devices[1798384204]
	outsideTemp = myWeatherStation.states['temperatureF']
	currentCondition = myWeatherStation.states['currentCondition']
	spokenString = "The current temperature is %s degrees. Current condition is %s." % (outsideTemp, currentCondition)
	itunesPlugin.executeAction("pauseAndSay", deviceId=135305663, props={'message':spokenString})
	
	itunesPlugin.executeAction("pauseAndSay", deviceId=135305663, props={'speakLastMessage':True})
</code>

=== Set Volume ===

**Action id**: setVolume

Properties for scripting:

|  //''volume''//  |a number from 0 to 100 representing the absolute volume  |

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("setVolume", deviceId=135305663, props={'volume':50})</code>

=== Increase Volume ===

**Action id**: increaseVolume

Properties for scripting:

|  //''volume''//  |a number from 0 to 100 representing the amount to increase - so if the volume is currently at 50, and volume is set to 25, the volume will end up being 75  |

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("increaseVolume", deviceId=135305663, props={'volume':25})</code>

=== Decrease Volume ===

**Action id**: decreaseVolume

Properties for scripting:

|  //''volume''//  |a number from 0 to 100 representing the amount to increase - so the volume is currently at 50, and volume is set to 25, the volume will end up being 25  |

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("decreaseVolume", deviceId=135305663, props={'volume':25})</code>

=== Set Repeat ===

**Action id**: setRepeat

Properties for scripting:

|  //''repeat''//  |a number representing the repeat type: 0 (no repeat), 1 (repeat song), 2 (repeat playlist)  |

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("setRepeat", deviceId=135305663, props={'repeat':0})</code>

=== Set Shuffle ===

**Action id**: setShuffle

Properties for scripting:

|  //''shuffle''//  |a boolean representing whether to shuffle or not  |

Example:

<code>itunesPlugin = indigo.server.getPlugin("com.perceptiveautomation.indigoplugin.itunes")
if itunesPlugin.isEnabled():
	itunesPlugin.executeAction("setShuffle", deviceId=135305663, props={'shuffle':True})</code>

===== Support and Troubleshooting =====

For usage or troubleshooting tips [[https://forums.indigodomo.com/viewforum.php?f=96|discuss this device]] on our forum.