README.md

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:

• Register for Change Events
• HEOS Account Check
• HEOS Account Sign In
• HEOS Account Sign Out
• HEOS System Heart Beat
• Get Players
• Get Player Info
• Get Play State
• Set Play State
• Get Now Playing Media
• Get Volume
• Set Volume
• Volume Up
• Volume Down
• Get Mute
• Set Mute
• Toggle Mute
• Get Play Mode
• Set Play Mode
• Get Queue
• Play Queue Item
• Remove Item(s) From Queue
• Save Queue as Playlist
• Clear Queue
• Move Queue Item(s)
• Play Next
• Play Previous
• Get Music Sources
• Get Source Info
• Browse Source
• Browse Source Containers
• Get Source Search Criteria
• Search
• Play Station
• Play Preset Station
• Play Input Source
• Play URL
• Add Container to Queue
• Add Track to Queue
• Get HEOS Playlists
• Rename HEOS Playlist
• Delete HEOS Playlist
• Get HEOS History
• Get HEOS Favorites
• Retrieve Album Metadata
• Set Service Option
• Command

Recurring Method Parameters

• pid - Player Identifier
• sid - Source Identifier
• cid - Container Identifier
• scid - Search Criteria Identifier
• mid - Media Identifier
• aid - Add Criteria Identifier
• qid - Queue Item Identifier
• range - Range Specifier
• onoff - On Off State
• input_name - Input Name

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:

• On Off State

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:

• pid: Player Identifier

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:

• pid: Player Identifier

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:

• pid: Player Identifier
• state: must be play, pause, or stop.

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:

• pid: Player Identifier

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:

• pid: Player Identifier

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:

• pid: Player Identifier
• level

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:

• pid: Player Identifier
• step: must be in range 1 to 10; inclusive

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:

• pid: Player Identifier
• step: must be in range 1 to 10; inclusive

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:

• pid: Player Identifier

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:

• pid: Player Identifier
• state: On Off State

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:

• pid: Player Identifier

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:

• pid: Player Identifier

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:

• pid: Player Identifier
• range: Range Specifier

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:

• pid: Player Identifier
• qid: Queue Item Identifier

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:

• pid: Player Identifier
• qid: Queue Item Identifier

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:

• pid: Player Identifier
• name

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:

• pid: Player Identifier

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:

• pid: Player Identifier
• sqid: (source queue item ID) is the Queue Item Identifier of the item to be moved
• dqid: (destination queue item ID) is the Queue Item Identifier at the location to move to.

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:

• pid: Player Identifier

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:

• pid: Player Identifier

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:

• sid: Source Identifier

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:

• sid: Source Identifier
• range: Range Specifier

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:

• sid: Source Identifier
• cid: Container Identifier
• range: Range Specifier

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:

• sid: Source Identifier

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:

• sid: Source Identifier
• search
• scid: Search Criteria Identifier
• range: Range Specifier

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:

• sid: Source Identifier
• cid: Container Identifier
• mid: Media Identifier
• pid: Player Identifierr
• name: a name from an item returned from browseSource, browseSourceContaienrs, browseSearch, or getHeosFavorites

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:

• pid: Player Identifier
• preset: is the name of an item from getHeosFavorites

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:

• pid: Player Identifier
• input_name: Input Name

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:

• pid: Player Identifier
• spid: a source Player Identifier to play music from
• input_name: Input Name

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:

• pid: Player Identifier
• url

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

• sid: Source Identifier
• cid: Container Identifier
• aid: Add Criteria Identifier
• pid: Player Identifier

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

• sid: Source Identifier
• cid: Container Identifier
• mid: Media Identifier
• aid: Add Criteria Identifier
• pid: Player Identifier

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:

• range: Range Specifier

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:

• sid: Source Identifier
• cid: Container Identifier
• name

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:

• sid: Source Identifier
• cid: Container Identifier

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:

• type: must be tracks or stations
• range: Range Specifier

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:

• range: Range Specifier

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:

• sid: Source Identifier
• cid: Container Identifier

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:

• sid: Source Identifier
• option: an option identifier in section 4.4.19 of the specification (v1.13)
• pid: Player Identifier

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

• HEOS by Denon
• HEOS CLI Protocol Specification

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).