Skip to content

REST API

Jump to bottom
Elijah Lopez edited this page Dec 24, 2024 · 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 trying to call the API (if you want to check if Music Caster is a live process programmatically, you may find the function is_already_running in shared.py useful)
  • returns true

POST /action/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, post requests will receive an API message/error and a GET request will be processed and redirected to / unless &is_api is supplied.

POST /action/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 /action/pause

  • pauses the player

POST /action/next?times=1

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

POST /action/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 /action/repeat

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

POST /action/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/system audio
  • json = {'uris': ['system audio', 'file_path', 'folder_path', 'url', 'playlist_name']}
  • json = {'uri': 'file_path/folder_path/url/playlist_name/systemaudio', '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