Skip to content

sovpro/heos-lib

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

20 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Heos Library

A Node.js library for HEOS device interaction

Constructor

The constructor requires a socket as can be acquired with net.createConnection (...)

const heos_lib = new HeosLib (socket)

A timeout for command results may be specified as a timeout property on an optional configuration parameter. The value should be set in milliseconds. By default the timeout is set to 5000 (5 seconds).

const heos_lib = new HeosLib (socket, {timeout: 10000})

Methods

There are a number of recurring method parameters

A list of methods:

Recurring Method Parameters

Player Identifier

A pid property value of an item returned by getPlayers. ^ recurring method parameters

Source Identifier

A sid property value of an item returned by getMusicSources, browseSource. ^ recurring method parameters

Container Identifier

A cid property value of an item returned by browseSource, browseSourceContainers, browseSearch. ^ recurring method parameters

Search Criteria Identifier

A scid property value of an item returned by getSourceSearchCriteria. ^ recurring method parameters

Static constants are available for:

  1. HeosLib.SEARCH_CRITERIA_ARTIST
  2. HeosLib.SEARCH_CRITERIA_ALBUM
  3. HeosLib.SEARCH_CRITERIA_TRACK
  4. HeosLib.SEARCH_CRITERIA_STATION
  5. HeosLib.SEARCH_CRITERIA_SHOWS
  6. HeosLib.SEARCH_CRITERIA_PLAYLIST
  7. HeosLib.SEARCH_CRITERIA_ACCOUNTS

Identifiers that can be used vary by source. Identifiers other than provided by the static contants may be available depending on the music source. See HEOS CLI Protocol Specification. ^ recurring method parameters

Media Identifier

A mid property value of an item returned by browseSourceContainers, browseSearch. ^ recurring method parameters

Add Criteria Identifier

A value available as static constants:

  1. HeosLib.QUEUE_PLAY_NOW
  2. HeosLib.QUEUE_PLAY_NEXT
  3. HeosLib.QUEUE_PLAY_LAST
  4. HeosLib.QUEUE_REPLACE_AND_PLAY

^ recurring method parameters

Queue Item Identifier

A qid property value on an item returned by getQueue.. ^ recurring method parameters

Range Specifier

A comma separated pair of start and end paging index values; inclusive (e.g. '0,9'). ^ recurring method parameters

On Off State

A value of on or off. ^ recurring method parameters

Input Name

An input name from 4.4.9 of the HEOS CLI Protocol Specification v1.13. ^ recurring method parameters

registerForChangeEvents

var result = await heos_lib
  .registerForChangeEvents (onoff)
var { enable } = result

See 4.1.1 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

registerForChangeEvents parameters:

checkAccount

var result = await heos_lib
  .checkAccount ()
var { un } = result
if (un) {
  // 'un' is defined if user is signed-in
  console.log ('Signed-in as ' + un)
}

See 4.1.2 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

signIn

try {
  await heos_lib.signIn (un, pw)
  // or: await heos_lib.signIn ({ un, pw })
  console.log ('Sign-in success')
}
catch (error) {
  // error message might be 'Invalid credentials'
  console.log ('Sign-in error: ' + error.message)
}

See 4.1.3 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

signIn parameters:

  • un: username
  • pw: password

signOut

try {
  await heos_lib.signOut ()
}
catch (error) {
  console.log ('Sign-out error: ' + error.message)
}

See 4.1.4 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

heartBeat

try {
  await heos_lib.heartBeat ()
}
catch (error) {
  console.log ('Heart beat error: ' + error.message)
}

See 4.1.5 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getPlayers

var [ player_info ] = await heos_lib.getPlayers ()
var { name, pid, model, version } = player_info

See 4.2.1 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getPlayerInfo

var player_info = await heos_lib.getPlayerInfo (pid)
// or: var player_info = await heos_lib.getPlayerInfo ({ pid })
var { name, pid, model, version } = player_info

See 4.2.2 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getPlayerInfo parameters:

getPlayState

var play_state = await heos_lib.getPlayState (pid)
// or: var play_state = await heos_lib.getPlayState ({ pid })
var { state } = play_state

See 4.2.3 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getPlayState parameters:

setPlayState

var result = await heos_lib
  .setPlayState (pid, state)
// or:
// var result = await heos_lib
//   .setPlayState ({ pid, state })
var { pid, state } = result

See 4.2.4 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

setPlayState parameters:

getNowPlayingMedia

var now_playing = await heos_lib
  .getNowPlayingMedia (pid)
// or:
// var now_playing = await heos_lib
//   .getNowPlayingMedia ({ pid })
var { type, song, artist } = now_playing

See 4.2.5 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getNowPlayingMedia parameters:

getVolume

var { pid, level } = await heos_lib.getVolume (pid)
// or: var { pid, level } = await heos_lib.getVolume ({ pid })

See 4.2.6 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getVolume parameters:

setVolume

var result = await heos_lib.setVolume (pid, level)
// or: var result = await heos_lib.setVolume ({ pid, level })
var { pid, level } = result

See 4.2.7 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

setVolume parameters:

volumeUp

var result = await heos_lib.volumeUp (pid, step)
// or: var result = await heos_lib.volumeUp ({ pid, step })
var { pid, step } = result

See 4.2.8 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

volumeUp parameters:

volumeDown

var result = await heos_lib.volumeDown (pid, step)
// or: var result = await heos_lib.volumeDown ({ pid, step })
var { pid, step } = result

See 4.2.9 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

volumeDown parameters:

getMute

var { pid, state } = await heos_lib.getMute (pid)
// or: var { pid, state } = await heos_lib.getMute ({ pid })

See 4.2.10 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getMute parameters:

setMute

var result = await heos_lib.setMute (pid, state)
// or: var result = await heos_lib.setMute ({ pid, state })
var { pid, state } = result

See 4.2.11 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

setMute parameters:

toggleMute

var result = await heos_lib.toggleMute (pid)
// or: var result = await heos_lib.toggleMute ({ pid })
var { pid } = result

See 4.2.12 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

toggleMute parameters:

getPlayMode

var play_mode = await heos_lib.getPlayMode (pid)
// or: var play_mode = await heos_lib.getPlayMode ({ pid })
var { pid, repeat, shuffle } = play_mode

See 4.2.13 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getPlayMode parameters:

setPlayMode

var result = await heos_lib
  .setPlayMode (pid, repeat, shuffle)
// or:
// var result = await heos_lib
//   .setPlayMode ({ pid, repeat, shuffle })
var { pid, repeat, shuffle } = result

See 4.2.14 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

setPlayMode parameters:

  • pid: Player Identifier
  • repeat: must be off, on_one, or on_all
  • shuffle: must be off or on

getQueue

var queue_data = await heos_lib.getQueue (pid, range)
// or: var queue_data = await heos_lib.getQueue ({ pid, range })
var { count, items } = queue_data

See 4.2.15 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getQueue parameters:

playQueueItem

var result = await heos_lib.playQueueItem (pid, qid)
// or: var result = await heos_lib.playQueueItem ({ pid, qid })
var { pid, qid } = result

See 4.2.16 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

playQueueItem parameters:

removeFromQueue

var result = await heos_lib.removeFromQueue (pid, qid)
// or: var result = await heos_lib.removeFromQueue ({ pid, qid })
var { pid, qid } = result

See 4.2.17 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

remvoeFromQueue parameters:

saveQueue

var result = await heos_lib.saveQueue (pid, name)
// or: var result = await heos_lib.saveQueue ({ pid, name })
var { pid, name } = result

See 4.2.18 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

saveQueue parameters:

clearQueue

var result = await heos_lib.clearQueue (pid)
// or: var result = await heos_lib.clearQueue ({ pid })
var { pid } = result

See 4.2.19 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

clearQueue parameters:

moveQueueItem

var result = await heos_lib.moveQueueItem (pid, sqid, dqid)
// or: var result = await heos_lib.moveQueueItem ({ pid, sqid, dqid })
var { pid, sqid, dqid } = result

See 4.2.20 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

moveQueueItem parameters:

Movement behavior

Moving to a greater qid shifts items between the source qid and destination qid forward (up). Moving to a lesser qid pushes items between the source qid and destination qid backward (down).

playNext

var result = await heos_lib.playNext (pid)
// or: var result = await heos_lib.playNext ({ pid })
var { pid } = result

See 4.2.21 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

playNext parameters:

playPrevious

var result = await heos_lib.playPrevious (pid)
// var result = await heos_lib.playPrevious ({ pid })
var { pid } = result

See 4.2.22 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

playPrevious parameters:

getMusicSources

var [ source_info ] = await heos_lib.getMusicSources ()
// or: var [ source_info ] = await heos_lib.getMusicSources ()
var { name, type, sid } = source_info

See 4.4.1 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getSourceInfo

var [ source_info ] = await heos_lib.getSourceInfo (sid)
// or: var [ source_info ] = await heos_lib.getSourceInfo ({ sid })
var { name, type, sid } = source_info

See 4.4.2 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getSourceInfo parameters:

browseSource

var { count, items } = await heos_lib
  .browseSource (sid, range)
// or:
// var { count, items } = await heos_lib
//   .browseSource ({ sid, range })
var [{ name, type, cid }] = items

See 4.4.3 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

browseSource parameters:

browseSourceContainers

var { count, items } = await heos_lib
  .browseSourceContainers (sid, cid, range)
// or: 
// var { count, items } = await heos_lib
//   .browseSourceContainers ({ sid, cid, range })
var [{ name, type, cid }] = items

See 4.4.4 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

browseSourceContainers parameters:

getSourceSearchCriteria

var criterias_list = await heos_lib
  .getSourceSearchCriteria (sid)
// or:
// var criterias_list = await heos_lib
//   .getSourceSearchCriteria (sid)
var [{ name, scid, cid }] = criterias_list

See 4.4.5 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getSourceSearchCriteria parameters:

browseSearch

var { count, items } = await heos_lib
  .browseSearch (sid, search, scid, range)
// or:
// var { count, items } = await heos_lib
//   .browseSearch ({ sid, search, scid, range })
var [{ name, type, mid }] = items

See 4.4.6 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

browseSearch parameters:

Properties of the returned items may vary depending on the source identifier and search criteria identifier parameters.

playStation

var result = await heosLib
  .playStation (sid, cid, mid, pid, name)
// or:
// var result = await heosLib
//   .playStation ({sid, cid, mid, pid, name })
var { cid, cid, mid, pid, name } = result

See 4.4.7 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

playStation parameters:

playPresetStation

var preset = 1
var result = await heos_lib.playPresetStation (pid, preset)
// or: var result = await heos_lib.playPresetStation ({ pid, preset })
var { pid, preset } = result

See 4.4.8 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

playPresetStation parameters:

playInputSource

var result = await heos_lib.playInputSource (pid, input_name)
// or: var result = await heos_lib.playInputSource ({ pid, input_name })
var { pid, input } = result

See 4.4.9 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

playInputSource parameters:

playInputSourceFrom

var result = await heos_lib
  .playInputSourceFrom (pid, spid, input_name)
// or:
// var result = await heos_lib
//   .playInputSourceFrom (pid, spid, input_name)
var { pid, spid, input } = result

See 4.4.9 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

playInputSourceFrom parameters:

playUrl

var result = await heos_lib.playUrl (pid, url)
// or: var result = await heos_lib.playUrl (pid, url)
var { pid, url } = result

See 4.4.10 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

playUrl parameters:

addContainerToQueue

var result = await heos_lib
  .addContainerToQueue (sid, cid, aid, pid)
// or:
// var result = await heos_lib
//  .addContainerToQueue ({ sid, cid, aid, pid })
var { sid, cid, aid, pid } = result

See 4.4.11 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

addContainerToQueue parameters

addTrackToQueue

var result = await heos_lib
  .addTrackToQueue (sid, cid, mid, aid, pid)
// or:
// var result = await heos_lib
//  .addTrackToQueue ({ sid, cid, mid, aid, pid })
var { sid, cid, mid, aid, pid } = result

See 4.4.12 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

addTrackToQueue parameters

getHeosPlaylists

var { count, items } = await heos_lib
  .getHeosPlaylists (range)
// or:
// var { count, items } = await heos_lib
//  .getHeosPlaylists ({ range })
var [{ name, type, cid }] = items

See 4.4.13 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getHeosPlaylists parameter:

renameHeosPlaylist

var result = await heos_lib
  .renameHeosPlaylist (sid, cid, name)
// or:
// var result = await heos_lib
//   .renameHeosPlaylist ({ sid, cid, name })
var { sid, cid, name } = result

See 4.4.14 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

renameHeosPlaylist parameters:

deleteHeosPlaylist

var result = await heos_lib
  .deleteHeosPlaylist (sid, cid)
// or:
// var result = await heos_lib
//   .deleteHeosPlaylist ({ sid, cid })
var { sid, cid } = result

See 4.4.15 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

deleteHeosPlaylist parameters:

getHeosHistory

var { count, items } = await heos_lib
  .getHeosHistory (type, range)
// or:
// var { count, items } = await heos_lib
//   .getHeosHistory ({ type, range })
var [{ name, type, cid }] = items

See 4.4.16 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getHeosHistory parameters:

getHeosFavorites

var { count, items } = await heos_lib
  .getHeosFavorites (range)
// or:
// var { count, items } = await heos_lib
//   .getHeosFavorites ({ range })
var [{ name, type }] = items

See 4.4.3 and 1.1 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

getHeosFavorites parameters:

retrieveAlbumMetadata

const { count, items } = await heos_lib
  .retrieveAlbumMetadata (sid, cid)
// or:
// const { count, items } = await heos_lib
//  .retrieveAlbumMetadata ({ sid, cid })

See 4.4.17 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

retrieveAlbumMetadata parameters:

Napster and Rhapsody only

setServiceOption

const option = 11 // See HEOS protocol spec
const { count, items } = await heos_lib
  .setServiceOption (sid, option, pid)
// or:
// const { count, items } = await heos_lib
//   .setServiceOption ({ sid, option, pid })

See 4.4.18 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

setServiceOption parameters:

Options that require 'cid', 'mid' or 'name' are currently not supported by the setServiceOption method. The command method can be used as a workaround.

command

Send a direct command:

heos_lib.command ({
  command: 'player/get_volume',
  params:  { pid: player_id }
})

See 3.1 in HEOS CLI Protocol Specification v1.13. ^ list of methods.

Currently, the command method does not directly return a value. The result can be obtained with an event listener.

Events

data

Receives all events and results. Note that data that could not be determined to be a result or an event will be included here.

event

Receives all events

event:[event name]

Receives results for a specified event. Note event names exclude the 'event/' prefix.

result

Receives all results

result:[command name]

Receives results for a specified command

Links

Notice

This unsponsored software is provided, subject to a MIT license, unofficially and independently of Sound United, LLC, its affiliates, subsidiaries and brands (such as HEOS, Denon and any such not listed here).