A product from

Helium Web Service API

[Please note that this documentation is currently incomplete]

The Helium Music Manager Web Service is available in Helium Music Manager 7.1 and forth. It enables an API for third party applications and services to get access to many of the features of Helium Music Manager. For example it lets you control the internal player as well as perform searches, looking up artist, album and track details and more.

We have built our own Helium Remote for iPhone using this API and have enabled the Web Service for all Helium Music Manager versions.

The Web Service communicates using a simple RESTful interface which is enabled from Options, under the Advanced section, on the Helium Web Service page. Specify the desired HTTP port to run the Web Service on and click the Start button to start the Web Service. A small icon illustrating a globe at the lower right corner of the Helium Music Manager window identified that the Web Service is running.

Sending commands and getting results is as easy as sending simple GET requests to the service at the following style:

http://<ip-address>:<port>/1.0/?method?<method-name>[&<other-params>=<other-values>]

An example to get information about the currently playing track would be this (given that the IP address and port that Helium Web Service is running at is 192.168.0.100 and 8080):

http://192.168.0.100:8080/1.0/?method=player.GetNowPlayingData

All results are returned in XML format wrapped in an hmm element with a status attribube, like this:

There are a couple of main elements within the <hmm> element that are returned on different API methods:

The tracks element, containing one or more track elements.
The albums element, containing one or more album elements.
The player-command element, containing a command, value, value2 and value3 elements.
The player-state element, containing a position, volume, filename, state, rating and subtrack element.
The album-information element, containing album specific information.
The artist-information element, containing artist specific information.

Below follows a list of the currently available API methods, together with the expected parameters and responses:

Method	Parameters	Response	Description
player.play	None	Default	Starts playing the active track in the Play queue. This is the track with pink background color in Helium Music Manager. If there is no active track available in the Play queue the first track in the list will be played.
player.pause	None	Default	Pauses the playback if the player is currently playing a track. If the player is currently paused the track will start playing.
player.stop	None	Default	Stops the playback.
player.next	None	Default	Proceeds to the next track in the Play queue.
player.previous	None	Default	Skips to the previous track in the Play queue.
player.getVolume	None	Default, player-command
player.setVolume	volume	Default	Volume is set with a value between 0 (silent) and 255 (max).
player.getPosition	None	Default, player-command
player.setPosition	position	Default	Position is set with a value that represents the position in seconds for the current track.
player.getNowPlayingData	None	Default, track (1)
player.getNowPlayingPicture	None	Binary	A binary stream of the album picture for the currently playing track.
player.getState	Default, player-state	player-state	Available player states are: 1 = Playing, 2 = Paused, 3 = Stopped, 4 = Loading
player.getPlayQueue	None	Default, track (0-N)
player.getActiveIndex	None	Default, player-command (active-index)	Gets the index zero based index for the currently playing track (value) and the database id for the track (value2).
player.playFileAtIndex	index	Default	Plays a specific file (index) in the Play Queue
player.getArtistInformation	None	artists	Returns artist information for the artist of the current track.
player.getArtistPicture	None	Binary	A binary stream of the artist picture for the currently playing tracks artist. If this artist does not have an assigned artist picture the default image will be returned. The image format is 128x128 pixels.
player.getSuggestedTracks	None	Default, track (0-N)	Returns a list of suggested tracks based on the track currently loaded in the player (whether playing, paused or stopped).
player.playDatabaseItem	id	Default	Plays a specific track in the database
player.getFavouriteUserTracks	None	Default, track (0-N)
player.enqueueNext	id	Default	Enqueues the specified track after the current track in the Play Queue
player.enqueueLast	id	Default	Enqueues the specified track to the end of the Play Queue
player.enqueueAlbum	id, isalbum	Default	Enqueues a specific album to the Play Queue. If isalbum is set to yes, id is assumed to be an album id otherwise it is assumed to be a file id (album will be looked-up)
player.playAlbum	id, isalbum	Default	Enqueues and plays a specific album to the Play Queue. If isalbum is set to yes, id is assumed to be an album id otherwise it is assumed to be a file id (album will be looked-up)
player.clearPlayQueue	None	Default	Clears Helium Music Manager's Play Queue
player.randomize	None	Default	Randomizes the contents in Helium Music Manager's Play Queue

playlists.getPlaylists	None	Default, playlist (0-N)
playlists.playPlaylist	id	Default
playlists.enqueuePlaylist	id	Default	Enqueues the contents from a specific Helium Music Manager playlist
playlists.getContents	id	Default, track (0-N)	Returns the tracks located in a specific Helium Music Manager playlist

database.search	searcharg, searchtype, exact	Default, track(0-N)	Performs a search and returns the results. Available searchtypes are: all - searches in all fields album artist title genre path recyear relyear publisher exact should be set to "yes" if only exact matches should be returned, otherwise set it to "no" or exclude the argument.
database.getStream	id	Binary	Returns the binary stream for a specific file
database.getInformationForItem	id	Default, track (1)
database.getPictureForItem	id, isalbum	Binary	If isalbum is set to "yes", id is assumed to be an album id otherwise it is assumed to be a file id (album will be looked-up)
database.rateItem	id, rating	Default	Updates the rating for a specific database track. Rating is a value from 0-10 (0 = No rating, 1 = 0.5 star, 2 = 1 star, 3 = 1.5 stars and so on)
database.setFavourite	id, favourite	Default	Sets if a specific track is a favourite or not. Variable favourite should be set to "yes" to mark the track as a favourite.
database.transcodeFile	id, transcodeformat, transcodequality	player-command	Converts a file to a specific format, defined by transcodeformat. Transcodeformat can be "mp3", "flac", "wav" and "ogg". Transcodequality defines the quality of the resulting file, specific to each encoding format. The resulting player-command will contain the filename of the resulting file, in the attribute "Value3". (Use together with method "database.getStreamFromFile). Converts a file to a specific format, defined by transcodeformat. Transcodeformat can be "mp3", "flac", "wav" and "ogg". Transcodequality defines the quality of the resulting file, specific to each encoding format. The resulting player-command will contain the filename of the resulting file, in the attribute "Value3". (Use together with method "database.getStreamFromFile").
database.getStreamFromFile	filename	Binary	Returns the binary stream for a specific file, specified by the filename parameter
database.getAlbum	id, isalbum	album-information, default	Returns the information for a specific album. If isalbum is set to yes, id is assumed to be an album id otherwise it is assumed to be a file id (album will be looked-up).
database.getPictureForAlbum	id, isalbum	Binary	If isalbum is set to "yes", id is assumed to be an album id otherwise it is assumed to be a file id (album will be looked-up)
database.getAlbumTracks	id, isalbum	Default, tracks (0-N)	If isalbum is set to "yes", id is assumed to be an album id otherwise it is assumed to be a file id (album will be looked-up)
database.trackExistsInCache	id	Player-command	Returns the full filename of a database track if it exits in Helium Music Managers internal cache.
database.getArtistPicture	id, isartist	Binary	If isartist is set to "yes", id is assumed to be an artist id otherwise it is assumed to be a file id (artist will be looked-up)
database.getArtistInformation	id, isartist	artist-information, default	If isartist is set to "yes", id is assumed to be an artist id otherwise it is assumed to be a file id (artist will be looked-up)
database.getLyrics	id	Player-command	If id is set to -1, lyrics will be returned for the file currently playing otherwise for the file with the specific id. Lyrics is returned in the value3 attribute.