Player (iTunes) Object Reference
| Parent | window (Global Window Object) |
| Scope | Global |
| Available since | Bowtie 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
property()(BTWrapper)
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.