Skip to content

REST API

Jump to bottom
Elijah Lopez edited this page Sep 9, 2021 · 36 revisions

This is some of the REST API that you can call to control music caster. The default API endpoint is http://localhost:2001/. In cases where the port 2001 is already being used, Music Caster will keep trying to bind to the next highest port (e.g. 2002, 2003, etc.).

If you want to interact with Music Caster running on another device on the network, take a look at music-caster.html for an example of how to find a Music Caster server. I'm sure there's smarter ways to discover devices on the network but this is a brute force method that works for me.

GET /running/

  • this method is useful for verifying Music Caster is running on the port you assumed it was running on
  • tip check if Music Caster is a live process before iterating port numbers [2001, 2010] and and trying to call the API
  • returns true

POST ?activate

  • activates the native GUI

GET /devices/

  • get all selectable devices with indices

POST /change-device/

  • {'device_index': deviceIndex}
  • selects device at deviceIndex >= 0

For all the below methods, supply &is_api to get return API messages. If the URL does not have &is_api, you will get redirected to / instead of receiving an API response.

POST ?play

  • if paused, resume playback.
  • else if tracks are in the queue, play the first item (index 0).
  • else if there are no tracks in the queue, library is shuffled and played (if any tracks were queued).

POST ?pause

  • pauses the player

POST ?next&times=1

  • try to skip track $times times
  • add &ignore_timestamps to ignore chapter traversing behaviour
  • return value does not indicate success

PSOT ?prev&times=1

  • try to go to the previous track $times times
  • add &ignore_timestamps to ignore chapter traversing behaviour
  • return value does not indicate success

POST ?repeat

  • cycles repeat
  • repeat states include: off, one (repeat current track), and all (plays queue on repeat)

POST ?shuffle

  • toggles shuffle

GET /state/

  • returns the state of Music Caster. Used to auto-refresh the Web GUI.
  • {'artist': '', 'title': '', 'track_number': '', 'album': '', 'lang': '', 'volume': 10, 'queue_length': 0}

POST /play/

  • play or queue files/folders/urls/playlists
  • json = {'uris': ['file_path', 'folder_path', 'url', 'playlist_name']}
  • json = {'uri': 'file_path/folder_path/url/playlist_name', 'queue': true}
  • DEFAULTS: queue: false

POST /exit/

  • stop playing and exit

GET /refresh-devices/

  • tells Music Caster to scan for Chromecasts on the network

GET/POST /timer/

  • GET the current timer
  • POST possible_args = 'cancel', minutes, 'HH:MM'
Clone this wiki locally