Merge pull request #236 from svrooij/master

feat: Added `togglePlayback` to mimic the sonos button.

Author: svrooij

README.md

@@ -116,6 +116,7 @@ device.getVolume()
   * parseDIDL(didl)
   * pause()
   * play(uri)
+  * togglePlayback()
   * previous()
   * queue(uri, positionInQueue)
   * queueNext(uri)

docs/services/AVTransport.md

@@ -26,6 +26,7 @@ Set the Transport URI
 
 + **options.CurrentURIMetaData**: `string`, The metadata of the uri you wish to set.
 
+**Returns**: `Object`, Parsed response data.
 
 ### sonos.AVTransport.AddURIToQueue(options)
 
@@ -45,6 +46,7 @@ Add an URI to the queue
 
 + **options.EnqueueAsNext**: `number`, To Queue this item as the next item set to `1`
 
+**Returns**: `Object`, Parsed response data.
 
 ### sonos.AVTransport.ReorderTracksInQueue(options)
 
@@ -64,6 +66,7 @@ Reorder tracks in queue
 
 + **options.InsertBefore**: `number`, Where should these tracks be inserted?
 
+**Returns**: `Object`, Parsed response data.
 
 ### sonos.AVTransport.SetPlayMode(playmode)
 
@@ -73,6 +76,7 @@ Set the new playmode
 
 **playmode**: `string`, One of the following `NORMAL` `REPEAT_ALL` `SHUFFLE` `SHUFFLE_NOREPEAT`
 
+**Returns**: `Object`, Parsed response data.
 
 ### sonos.AVTransport.ConfigureSleepTimer(duration)
 
@@ -82,6 +86,8 @@ Configure a sleeptimer.
 
 **duration**: `string`, the duration as 'ISO8601Time', needs sample!
 
+**Returns**: `Object`, Parsed response data.
+
 ### sonos.AVTransport.SnoozeAlarm(duration)
 
 Snooze the current running alarm for a number of minutes.
@@ -90,10 +96,12 @@ Snooze the current running alarm for a number of minutes.
 
 **duration**: `string`, The duration, as 'ISO8601Time', needs sample!
 
+**Returns**: `Object`, Parsed response data.
 
 ### sonos.AVTransport.CurrentTrack()
 
 Get information about the current track, parsed version of `GetPositionInfo()`
 
+**Returns**: `Object`, The current playing track
 
 * * *

docs/sonos.md

@@ -29,7 +29,7 @@ Get Music Library Information
 
 **Returns**: `Object`, {returned: {String}, total: {String}, items:[{title:{String}, uri: {String}}]}
 
-### sonos.Sonos.searchMusicLibrary(searchType, searchTerm, options)
+### sonos.Sonos.searchMusicLibrary(searchType, searchTerm, requestOptions, separator)
 
 Get Music Library Information
 
@@ -39,7 +39,9 @@ Get Music Library Information
 
 **searchTerm**: `String`, Optional - search term to search for
 
-**options**: `Object`, Optional - default {start: 0, total: 100}
+**requestOptions**: `Object`, Optional - default {start: 0, total: 100}
+
+**separator**: `String`, Optional - default is colon. `:` or `/`
 
 **Returns**: `Object`, {returned: {String}, total: {String}, items:[{title:{String}, uri: {String}}]}
 
@@ -91,19 +93,19 @@ Plays a uri directly (the queue stays the same)
 
 Stop What's Playing
 
-**Returns**: `Promise`
+**Returns**: `boolean`
 
 ### sonos.Sonos.becomeCoordinatorOfStandaloneGroup()
 
 Become Coordinator of Standalone Group
 
-**Returns**: `Promise`
+**Returns**: `boolean`
 
 ### sonos.Sonos.leaveGroup()
 
 Leave the group (shortcut to becomeCoordinatorOfStandaloneGroup)
 
-**Returns**: `Promise`
+**Returns**: `boolean`
 
 ### sonos.Sonos.joinGroup(otherDeviceName)
 
@@ -139,6 +141,7 @@ Select specific track in queue
 
 **trackNr**: `Number`, Number of track in queue (optional, indexed from 1)
 
+**Returns**: `Boolean`
 
 ### sonos.Sonos.next()
 
@@ -211,6 +214,7 @@ Set the LED State
 
 **newState**: `String`, "On"/"Off"
 
+**Returns**: `Boolean`
 
 ### sonos.Sonos.getZoneInfo()
 
@@ -302,6 +306,12 @@ Get Current Playback State
 
 **Returns**: `String`, the current playback state
 
+### sonos.Sonos.togglePlayback()
+
+Toggle the current playback, like the button. Currently only works for state `playing` or `paused`
+
+**Returns**: `Boolean`
+
 ### sonos.Sonos.getFavoritesRadioStations(options)
 
 Get Favorites Radio Stations
@@ -372,10 +382,12 @@ Reorder tracks in queue.
 
 **updateId**: `number`, Not sure what this means, just leave it at `0`
 
+**Returns**: `Boolean`
 
 ### sonos.Sonos.getSpotifyConnectInfo()
 
 Get SpotifyConnect info, will error when no premium account is present
 
+**Returns**: `Object`
 
 * * *

lib/services/AVTransport.js

@@ -32,6 +32,7 @@ util.inherits(AVTransport, Service)
  * @param {number} options.InstanceID The instance you want to control is always `0`
  * @param {string} options.CurrentURI The new URI you wish to set.
  * @param {string} options.CurrentURIMetaData The metadata of the uri you wish to set.
+ * @returns {Object} Parsed response data.
  */
 AVTransport.prototype.SetAVTransportURI = async function (options) { return this._request('SetAVTransportURI', options) }
 
@@ -43,6 +44,7 @@ AVTransport.prototype.SetAVTransportURI = async function (options) { return this
  * @param {number} options.EnqueuedURIMetaData The Metadata of the track you wish to add, see `Helpers.GenerateMetadata`
  * @param {number} options.DesiredFirstTrackNumberEnqueued The position in the queue
  * @param {number} options.EnqueueAsNext To Queue this item as the next item set to `1`
+ * @returns {Object} Parsed response data.
  */
 AVTransport.prototype.AddURIToQueue = async function (options) { return this._request('AddURIToQueue', options) }
 AVTransport.prototype.AddMultipleURIsToQueue = async function (options) { return this._request('AddMultipleURIsToQueue', options) }
@@ -55,6 +57,7 @@ AVTransport.prototype.AddMultipleURIsToQueue = async function (options) { return
  * @param {number} options.StartingIndex The index of the first song you want to move.
  * @param {number} options.NumberOfTracks How many tracks do you want to move?
  * @param {number} options.InsertBefore Where should these tracks be inserted?
+ * @returns {Object} Parsed response data.
  */
 AVTransport.prototype.ReorderTracksInQueue = async function (options) { return this._request('ReorderTracksInQueue', options) }
 AVTransport.prototype.RemoveTrackFromQueue = async function (options) { return this._request('RemoveTrackFromQueue', options) }
@@ -81,6 +84,7 @@ AVTransport.prototype.PreviousSection = async function (options) { return this._
 /**
  * Set the new playmode
  * @param {string} playmode One of the following `NORMAL` `REPEAT_ALL` `SHUFFLE` `SHUFFLE_NOREPEAT`
+ * @returns {Object} Parsed response data.
  */
 AVTransport.prototype.SetPlayMode = async function (playmode) { return this._request('SetPlayMode', {InstanceID: 0, NewPlayMode: playmode}) }
 AVTransport.prototype.SetCrossfadeMode = async function (options) { return this._request('SetCrossfadeMode', options) }
@@ -94,6 +98,7 @@ AVTransport.prototype.BecomeGroupCoordinatorAndSource = async function (options)
 /**
  * Configure a sleeptimer.
  * @param {string} duration the duration as 'ISO8601Time', needs sample!
+ * @returns {Object} Parsed response data.
  */
 AVTransport.prototype.ConfigureSleepTimer = async function (duration) { return this._request('ConfigureSleepTimer', {InstanceID: 0, NewSleepTimerDuration: duration}) }
 AVTransport.prototype.GetRemainingSleepTimerDuration = async function () { return this._request('GetRemainingSleepTimerDuration', {InstanceID: 0}) }
@@ -104,11 +109,13 @@ AVTransport.prototype.GetRunningAlarmProperties = async function (options) { ret
 /**
  * Snooze the current running alarm for a number of minutes.
  * @param {string} duration The duration, as 'ISO8601Time', needs sample!
+ * @returns {Object} Parsed response data.
  */
 AVTransport.prototype.SnoozeAlarm = async function (duration) { return this._request('SnoozeAlarm', {InstanceID: 0, Duration: duration}) }
 
 /**
  * Get information about the current track, parsed version of `GetPositionInfo()`
+ * @returns {Object} The current playing track
  */
 AVTransport.prototype.CurrentTrack = async function () {
   return this.GetPositionInfo()

lib/sonos.js

@@ -47,7 +47,7 @@ var SpotifyRegion = {
  * @class Sonos
  * @param {String} host IP/DNS
  * @param {Number} port
- * @return {Sonos}
+ * @returns {Sonos}
  */
 var Sonos = function Sonos (host, port, options) {
   this.host = host
@@ -309,6 +309,7 @@ Sonos.prototype.seek = async function (seconds) {
 /**
  * Select specific track in queue
  * @param  {Number}   trackNr    Number of track in queue (optional, indexed from 1)
+ * @returns {Boolean}
  */
 Sonos.prototype.selectTrack = async function (trackNr) {
   debug('Sonos.selectTrack(%j)', trackNr)
@@ -413,6 +414,7 @@ Sonos.prototype.getLEDState = async function () {
 /**
  * Set the LED State
  * @param  {String}   newState           "On"/"Off"
+ * @returns {Boolean}
  */
 Sonos.prototype.setLEDState = async function (newState) {
   debug('Sonos.setLEDState(%j)', newState)
@@ -467,7 +469,7 @@ Sonos.prototype.setName = async function (name) {
 
 /**
  * Get Play Mode
- * @return {String}
+ * @returns {String}
  */
 Sonos.prototype.getPlayMode = async function () {
   debug('Sonos.getPlayMode()')
@@ -558,14 +560,34 @@ Sonos.prototype.getTopology = async function () {
  * Get Current Playback State
  * @returns {String} the current playback state
  */
-Sonos.prototype.getCurrentState = function () {
+Sonos.prototype.getCurrentState = async function () {
   debug('Sonos.currentState()')
   if (this._isSubscribed && this._state) return this._state
   return this.avTransportService().GetTransportInfo()
     .then(result => {
       return Helpers.TranslateState(result.CurrentTransportState)
     })
 }
+
+/**
+ * Toggle the current playback, like the button. Currently only works for state `playing` or `paused`
+ * @returns {Boolean}
+ */
+Sonos.prototype.togglePlayback = async function () {
+  debug('Sonos.togglePlayback()')
+  return this.getCurrentState()
+    .then(state => {
+      if (state === 'paused') {
+        return this.play()
+      } else if (state === 'playing') {
+        return this.pause()
+      } else {
+        debug('toggle playback doesn\'t support %s', state)
+        return false
+      }
+    })
+}
+
 /**
  * Get Favorites Radio Stations
  * @param  {Object}   options     Optional - default {start: 0, total: 100}
@@ -687,6 +709,7 @@ Sonos.prototype.playNotification = async function (options) {
  * @param {number} numberOfTracks How many tracks do we want to move
  * @param {number} insertBefore Index of place where the tracks should be moved to
  * @param {number} updateId Not sure what this means, just leave it at `0`
+ * @returns {Boolean}
  */
 Sonos.prototype.reorderTracksInQueue = async function (startingIndex, numberOfTracks, insertBefore, updateId = 0) {
   return this.avTransportService().ReorderTracksInQueue({
@@ -700,6 +723,7 @@ Sonos.prototype.reorderTracksInQueue = async function (startingIndex, numberOfTr
 
 /**
  * Get SpotifyConnect info, will error when no premium account is present
+ * @returns {Object}
  */
 Sonos.prototype.getSpotifyConnectInfo = async function () {
   const uri = 'http://' + this.host + ':' + this.port + '/spotifyzc?action=getInfo'