node package manager
Painless code sharing. npm Orgs help your team discover, share, and reuse code. Create a free org »

@jonny/spotify-web-helper

Spotify Web Helper for node.js

This is a rewrite of the excellent node-spotify-webhelper, but with support for events, so you don't have to do getStatus() all the time. It also is faster, and starts SpotifyWebHelper on OS X, not just on Windows.
I am also trying to maintain the project and handle issues, at least every 2 months. Pull requests welcome!

Install

$ npm install @jonny/spotify-web-helper --save

Example

const SpotifyWebHelper = require('@jonny/spotify-web-helper');
 
const helper = SpotifyWebHelper();
 
helper.player.on('error', err => {
  if (error.message.match(/No user logged in/)) {
    // also fires when Spotify client quits 
  } else {
    // other errors: /Cannot start Spotify/ and /Spotify is not installed/ 
  }
});
helper.player.on('ready', () => {
 
  // Playback events 
  helper.player.on('play', () => { });
  helper.player.on('pause', () => { });
  helper.player.on('end', () => { });
  helper.player.on('track-will-change', track => {});
  helper.player.on('status-will-change', status => {});
 
  // Playback control. These methods return promises 
  helper.player.play('spotify:track:4uLU6hMCjMI75M1A2tKUQC');
  helper.player.pause();
  helper.player.seek();
 
  // Get current playback status, including up to date playing position 
  console.log(helper.status);
  // 'status': { 
  //    'track': ..., 
  //    'shuffle': ..., 
  //    'playing_position': ... 
  //  } 
 
});

API

Class: SpotifyWebHelper

new SpotifyWebHelper([opts])

  • opts <object> Options.
    • opts.port <number> Web helper port. Default is 4370.

helper.player

helper.status

Class: PlayerEventEmitter

Inherits from EventEmitter.

Event: 'end'

Playback has ended.

Event: 'error'

An error has occurred. The listener callback receive the <Error> as first argument. An error occurs when Spotify cannot be started, is not installed, or quits. Refer to the example above to see how to distinguish errors.

Event: 'pause'

Playback has paused.

Event: 'play'

Playback has started.

Event: 'ready'

This player object is ready to use.

Event: 'status-will-change'

Current status has changed. The listener callback receive a <SpotifyStatus> object as first argument.

helper.status will be changed by the new status after this event is emitted.

Event: 'track-will-change'

Current track has changed. The listener callback receive a <SpotifyTrack> object as first argument.

player.pause([unpause]);

  • unpause <boolean> true to resume playback. Default is false.
  • Returns <Promise<SpotifyStatus>>

player.play(spotifyUri);

  • spotifyUri <string> Spotify URI.
  • Returns <Promise<SpotifyStatus>>

Typedef: SpotifyStatus

status.version

  • <number> Web helper API version. Currently 9.

status.client_version

  • <string> Client version.

status.playing

  • <boolean> true if a track is playing.

status.shuffle

  • <boolean> true if shuffle is enabled.

status.repeat

  • <boolean> true if repeat is enabled.

status.play_enabled

  • <boolean> true if playing is available.

status.prev_enabled

  • <boolean> true if skipping to previous track is available.

status.next_enabled

  • <boolean> true if skipping to next track is available.

status.track

status.context

  • <object>

status.playing_position

  • <number> Current track position, in counting seconds.

status.server_time

  • <number> Server time in UNIX time.

status.volume

  • <number> Audio volume, from 0 to 1.

status.online

  • <boolean>

status.open_graph_state

  • <object>

status.running

  • <boolean>

Typedef: SpotifyTrack

track.track_resource

track.artist_resource

track.album_resource

track.length

  • <number> Track length in seconds.

track.track_type

  • <string>

Typedef: SpotifyResource

res.name

  • <string> Name.

res.uri

  • <string> Spotify URI.

res.location

  • <object> Object containing attribute og, which represent an HTTPS URL to the resource.

Compatibility

Since 1.3.0 node >=4.0 is required. Use 1.2.0 for older node versions.