RPC Documentation

All of the endpoints are paths that point to http://localhost:10769, we've observed that sometimes using 127.0.0.1 when IPv4 is disabled (don't do that btw) tends to break and not connect. We're not fixing this as it's user error for turning off IPv4, but if you cannot do anything about it, try using [::1]:10769.

GET /active

This will respond as quickly as possible with an empty 204: No Content response, it can be used to quickly check that the RPC is still active.

GET /currentPlayingSong

This will respond with an Apple Music API Response for the currently playing song, the following is an example response.

{
  "info": {
    "albumName": "Skin",
    "artistName": "Flume",
    "artwork": {
      "bgColor": "aa96c7",
      "height": 600,
      "textColor1": "040a06",
      "textColor2": "1b1937",
      "textColor3": "25262c",
      "url": "https://is1-ssl.mzstatic.com/image/thumb/Music122/v4/20/84/1b/20841bcf-a7c1-8048-08ba-ea03e33dbdce/3614598524069.png/{w}x{h}bb.jpg",
      "width": 600
    },
    "audioLocale": "en-US",
    "audioTraits": ["atmos", "lossless", "lossy-stereo", "spatial"],
    "composerName": "Harley Streten, Amanda Warner & Peter Wade Keusch",
    "currentPlaybackProgress": 0.63,
    "currentPlaybackTime": 123.059955,
    "discNumber": 1,
    "durationInMillis": 193633,
    "endTime": 1686069277080,
    "genreNames": ["Electronic"],
    "hasLyrics": true,
    "hasTimeSyncedLyrics": true,
    "isAppleDigitalMaster": false,
    "isMasteredForItunes": false,
    "isPlaying": true,
    "isVocalAttenuationAllowed": true,
    "isrc": "MtheoryLLCAUFF01600807",
    "kind": "song",
    "name": "Like Water (feat. MNDR)",
    "playParams": {
      "id": "1481729389",
      "kind": "song"
    },
    "previews": [
      {
        "url": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview112/v4/9d/12/c3/9d12c393-bc10-14ba-b70b-a8ad27fb21b7/mzaf_1376031537628674471.plus.aac.ep.m4a"
      }
    ],
    "releaseDate": "2016-05-27T12:00:00Z",
    "remainingTime": 70573.04500000001,
    "songId": "1481729389",
    "startTime": 1686069083447.045,
    "status": "playing",
    "trackNumber": 14,
    "url": {
      "appleMusic": "https://music.apple.com/au/song/1481729389",
      "cider": "https://cider.sh/link?play/s/1481729389",
      "songLink": "https://song.link/i/1481729389"
    }
  }
}

GET /addToLibrary

This will save the currently playing track to the user's library. If no music is playing, this will do nothing.

GET /isPlaying

This will return a JSON string stating if the player is currently actively playing a song or not.

These are the only 2 potential responses to this request, if it is anything else, it's safe to assume something broke.

{/*

IMO the next 3 endpoints should be PUT or POST but they're GET because why not. (playPause, play, pause -Amaru8)

-d3rpp

*/}

GET /toggleAutoplay

This will change the autoplay setting to its opposite value and return the updated value in a JSON string.

These are the only 2 potential responses to this request, if it is anything else, it's safe to assume something broke.

GET /playPause

This is functionally equivalent to clicking the play/pause button within the application.

GET /play

This is functionally equivalent to clicking the play button within the application, if music is already playing, this will do nothing.

GET /pause

This is functionally equivalent to clicking the pause button within the application, if music is already paused, this will do nothing.

GET /stop

This is functionally equivalent to clicking the STOP button within the application, if nothing is happening, this will do nothing

GET /next

This will skip to the next song, behaviour is identical to clicking the button within the application.

GET /previous

This will skip to the previous song, behaviour is identical to clicking the button within the application.

GET /seekto/{t}

Where

• t is the time you'd like to skip to in seconds

Set the playhead to this time in the song, you can use /currentPlayingSong to get the time, (using the durationInMillis property divided by 1,000 to get the duration in seconds).

This will always return 204 and if the call fails or the song is too long, it will silently fail, it is recommended that you check the song's actual length before running this function.

GET /show

Will show the window and demand user attention on the screen

GET /hide

Will hide the window, if enabled this will minise it to the system tray as well.

GET /album/{id}

Where

• id is the ID of the album you'd like to lookup

This will run a query of the Apple Music API using the signed in user's account and will pipe the response back to here.

This will always return a 200 but with a different JSON Structure

For More information on the structure of this response, consult the Apple Music API Docs

PUT /rating/{type}/{id}/{rating}

Since Cider version 2.1.3

Where

• type is the type of content you're submitting a rating for, this can be song, music-video, album, or playlist
• id is the ID of the content in question, you can get it from /currentPlayingSong
• rating is the rating you'd like to push
  • -1 is a dislike
  • 0 resets the rating
  • 1 is a like

GET /audio

Get the current volume, this will return plain-text as a floating point number between 0 and 1 inclusive

GET /audio/{volume}

Set the volume slider, will set the in-app volume, not the system volume.

requires a floating point value between 0 and 1, (e.g. /audio/0.8).

GET /rating/{type}/{id}

Since Cider version 2.1.3

Where

• type is the type of content you're submitting a rating for, this can be song, music-video, album, or playlist
• id is the ID of the content in question, you can get it from /currentPlayingSong