Player (iTunes) Object Reference

Parentwindow (Global Window Object)
ScopeGlobal
Available sinceBowtie 1.0 Beta 1 (iTunes)
Bowtie 1.0 (Player)
Bowtie Touch 2.0

Overview

The Player object is used to control playback of the media player Bowtie is currently controlling. Themes use the Player object to modify the play state (play/pause), skip tracks in either direction, scrub back and forth in tracks, change the volume, change a track's rating, control shuffle and repeat, and gather other information from the media player.

The Player object is also available as iTunes for compatibility, but because Bowtie is capable of controlling more than just iTunes, the Player object is more semantically correct. If you don't need your themes to run on Bowtie releases prior to 1.0 (eg, beta releases), use Player; otherwise, use iTunes.

Methods and Properties

Playback Methods isConnected(), nextTrack(), pause(), play(), playerPosition(), playPause(), playState(), previousTrack(), setPlayerPosition(), setVolume(), stop(), volume()
Track Information currentTrack(), rating(), ratingStars(), renderedArtwork(), setRating(), uniqueString()
Shuffle and Repeat repeat(), setRepeat(), setShuffle(), shuffle()
Presentation Methods canShow(), name(), show()
Deprecated Methods artwork(), fullArtwork(), iTunesRunning()

Object Methods

canShow()

Returns a boolean value representing whether or not the current source can be "shown."

Player.canShow()

Return Value

A boolean value representing whether or not the current source can be "shown."

Discussion

Application sources, like iTunes, will typically return true for this, because an application can be "shown" (ie, made the active application and brought to the front). Device sources, like iPhones, will return false, because there is no analog.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

currentTrack()

Returns information on the currently playing track.

Player.currentTrack()

Return Value

A BTWrapper object containing information about the current track.

Discussion

Properties are accessed using the property() (all versions) or propertyHTML() (Bowtie 1.1 and later) method, or the native JavaScript syntax (Bowtie 1.1 and later). The available properties are:

title
A string representing the track's title.
artist
A string representing the track's artist.
album
A string representing the track's album.
genre
A string representing the track's genre.
length
A float representing the track's length in seconds.

For more information, see Accessing Properties in a BTWrapper.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

isConnected()

Returns whether or not a source is connected.

Player.isConnected()

Return Value

A boolean value representing whether or not a source is currently connected to Bowtie. In Bowtie Touch, this always returns true.

Availability

Available in Bowtie 1.1 and later.
Available in Bowtie Touch 2.0 and later.

name()

Returns the localized name of the source Bowtie is controlling.

Player.name()

Return Value

A string representing the localized name of the source Bowtie is controlling (eg, "iTunes" or "Spotify"), or undefined if no sources are connected. If you need to support Bowtie 1.3 or earlier, use Bowtie.currentSourceName().

Availability

Available in Bowtie 1.4 and later.

nextTrack()

Tells the media player to skip to the next track.

Player.nextTrack()

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

pause()

Tells the media player to pause playback.

Player.pause()

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

play()

Tells the media player to start or resume playback.

Player.play()

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

playerPosition()

Returns the position of the playhead in the current track.

Player.playerPosition()

Return Value

A float representing the number of seconds that have elapsed in the current track.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

playPause()

Tells the media player to play if it is paused or stopped, or pause otherwise.

Player.playPause()

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

playState()

Returns the current playback state (playing/paused/stopped) as an integer.

Player.playState()

Return Value

An integer representing the current playback state: 0 for stopped, 1 for playing, 2 for paused.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

previousTrack()

Tells the media player to skip to the previous track.

Player.previousTrack()

Discussion

Note that different sources may interpret this command differently. For instance, as of Bowtie 1.0 (and Bowtie for iPhone 1.0), iTunes interprets this command as a "skip to previous track" command, whereas Bowtie for iPhone interprets this more like the iPod: if we're only a few seconds into a track, it skips to the previous track, but if we're further in, it first returns to the beginning of the current track.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

rating()

Returns the rating of the current track.

Player.rating()

Return Value

An integer representing the current track's rating from 0 – 100. Every 20 units represents one star; 10 units represents a half-star.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

ratingStars()

Returns a string representation of the rating of the current track using "stars."

Player.ratingStars()

Return Value

A string representing the current track's rating using Unicode star (★) and half (½) symbols. Make sure your theme uses the UTF-8 encoding to avoid potential rendering issues.

Discussion

Note that, on Bowtie for Mac, this method returns Unicode characters, but on Bowtie Touch, this method returns HTML entities (★ and ½, respectively).

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

renderedArtwork()

Returns the URL to the current track's artwork.

Player.renderedArtwork()

Return Value

A string representing the URL to the current track's artwork, or else an empty string if there is no artwork for the current track.

Discussion

The artwork returned by this method is already sized to the values specified in your Info.plist file. This is the preferred method to access artwork.

Availability

Available in Bowtie 1.0 and later.
Available in Bowtie Touch 2.0 and later.

repeat()

Returns the repeat mode of the current playlist as an integer.

Player.repeat()

Return Value

An integer representing the repeat mode of the current playlist: 0 for off, 1 for repeat all, 2 for repeat single track.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

setPlayerPosition()

Sets the position of the playhead in the current track.

Player.setPlayerPosition(position)

Parameters

position
An integer representing the number of seconds into the current track to place the playhead.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

setRating()

Sets the rating of the current track.

Player.setRating(rating)

Parameters

rating
An integer representing the current track's new rating from 0 – 100. Every 20 units represents one star; 10 units represents a half-star.

Availability

Available in Bowtie 1.0 Beta 1 and later.

See Also

setRepeat()

Sets the repeat mode of the current playlist.

Player.setRepeat(repeat)

Parameters

repeat
An integer representing the new repeat mode of the current playlist: 0 for off, 1 for repeat all, 2 for repeat single track.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

setShuffle()

Sets the shuffle mode of the current playlist.

Player.setShuffle(shuffle)

Parameters

shuffle
A boolean value representing the new shuffle mode of the current playlist.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

setVolume()

Sets the playback volume of the source.

Player.setVolume(volume)

Parameters

volume
An integer representing the new playback volume as an integer from 0 – 100.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

show()

Shows the current source, if possible.

Player.show()

Discussion

Application sources, like iTunes, will typically activate and make themselves the frontmost application. Device sources, like iPhones, however, will likely be incapable of "showing." For this reason, you should first test to see if it's possible to "show" the current source using Player.canShow().

Availability

Available in Bowtie 1.0 Beta 1 and later.

See Also

shuffle()

Returns the shuffle mode of the current playlist.

Player.shuffle()

Return Value

A boolean value representing the shuffle mode of the current playlist.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

stop()

Tells the media player to stop playback and clear the current track.

Player.stop()

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

uniqueString()

Returns a string unique to the current track.

Player.uniqueString()

Return Value

A string that uniquely identifies the current track.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

volume()

Returns the playback volume of the source.

Player.volume()

Return Value

An integer representing the playback volume as an integer from 0 – 100.

Availability

Available in Bowtie 1.0 Beta 1 and later.
Available in Bowtie Touch 2.0 and later.

See Also

Deprecated Methods

artwork()

Returns a "data:" URL to resized artwork for the current track. Deprecated: use Player.renderedArtwork().

Player.artwork(width, height)

Parameters

width
An integer representing the desired width in pixels of the artwork.
height
An integer representing the desired height in pixels of the artwork.

Return Value

A string representing the "data:" URL to the resized artwork for the current track.

Availability

Available in Bowtie 1.0 Beta 1 and later.

fullArtwork()

Returns the URL to the original artwork for the current track. Deprecated: use Player.renderedArtwork().

Player.fullArtwork()

Return Value

A string representing the URL to the unaltered artwork for the current track.

Availability

Available in Bowtie 1.0 Beta 1 and later.

iTunesRunning()

Returns a boolean value representing whether or not the source is running. Deprecated: use Player.isConnected() instead.

Player.iTunesRunning()

Return Value

A boolean value representing whether or not a source is connected.

Discussion

Before 1.0, this returned a value indicating whether or not iTunes was running. As of 1.0, this always returned true. As of 1.1, this returns a value indicating whether or not a source is connected (equivalent to "typeof(Bowtie.currentSourceName()) != 'undefined'").

Availability

Available in Bowtie 1.0 Beta 1 and later.