Skip to content

REST API

Jump to bottom
Elijah Lopez edited this page Apr 24, 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.).

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 main window

POST ?play

  • the is_api flag is used to return API messages. If you don't supply it, you will get redirected to / instead of receiving a API response
  • 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 for playlists

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/

  • scan for Chromecasts on the network

GET/POST /timer/

  • GET the current timer
  • POST possible_args = 'cancel', minutes, 'HH:MM'

Clone this wiki locally