πŸŽ› Control Spotify from node.js
Clone or download
Latest commit 867e783 Aug 23, 2018
Permalink
Failed to load latest commit information.
lib Refactor wintools Oct 1, 2016
.gitignore Initial commit Aug 22, 2015
README.md Update README.md Aug 23, 2018
index.js Adds a method to be able to get a fresh status if needed Apr 15, 2018
package-lock.json 1.14.0 May 21, 2018
package.json 1.14.0 May 21, 2018
test.js Add seek to test Jun 28, 2017

README.md

Please note that because of a recent Spotify update, the library is not working at the moment. Discussion here: https://github.com/onetune/spotify-web-helper/issues/41


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 spotify-web-helper --save

Example

const SpotifyWebHelper = require('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('seek', newPosition => {});
  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.seekTo(60); // 60 seconds

  // 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

Gets the current saved status.

helper.getStatus()

Refetches the status from Spotify and returns it.

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: 'seek'

User has changed the current playing positon.

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.