A Node.js library for HEOS device interaction
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})
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
- 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
A pid property value of an item returned by getPlayers. ^ recurring method parameters
A sid property value of an item returned by getMusicSources, browseSource. ^ recurring method parameters
A cid property value of an item returned by browseSource, browseSourceContainers, browseSearch. ^ recurring method parameters
A scid property value of an item returned by getSourceSearchCriteria. ^ recurring method parameters
Static constants are available for:
- HeosLib.SEARCH_CRITERIA_ARTIST
- HeosLib.SEARCH_CRITERIA_ALBUM
- HeosLib.SEARCH_CRITERIA_TRACK
- HeosLib.SEARCH_CRITERIA_STATION
- HeosLib.SEARCH_CRITERIA_SHOWS
- HeosLib.SEARCH_CRITERIA_PLAYLIST
- 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
A mid property value of an item returned by browseSourceContainers, browseSearch. ^ recurring method parameters
A value available as static constants:
- HeosLib.QUEUE_PLAY_NOW
- HeosLib.QUEUE_PLAY_NEXT
- HeosLib.QUEUE_PLAY_LAST
- HeosLib.QUEUE_REPLACE_AND_PLAY
A qid property value on an item returned by getQueue.. ^ recurring method parameters
A comma separated pair of start and end paging index values; inclusive (e.g. '0,9'). ^ recurring method parameters
A value of on or off. ^ recurring method parameters
An input name from 4.4.9 of the HEOS CLI Protocol Specification v1.13. ^ recurring method parameters
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:
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.
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
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.
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.
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.
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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).
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
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
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.
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
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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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.
Receives all events and results. Note that data that could not be determined to be a result or an event will be included here.
Receives all events
Receives results for a specified event. Note event names exclude the 'event/' prefix.
Receives all results
Receives results for a specified command
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).