Skip to main content

​
Overview

Media actions control music playback on Spotify and Apple Music, plus system volume.
ActionDescriptionEnabled by Default
play_on_spotifySearch and play a song/artist on Spotify✓
play_apple_musicPlay a song on Apple Music by name—
play_pause_musicPlay or pause music (Music.app or Spotify)✓
next_trackSkip to the next track✓
previous_trackGo to the previous track—
get_now_playingGet the currently playing song and artist✓
set_music_volumeSet music app volume (not implemented in current codebase)—

​
play_on_spotify

Search and play a specific song, artist, album, or playlist on Spotify.

​
Parameters

​
query
string
required
Song name, artist, album, or playlist
​
type
string
default:"track"
Search type: track, artist, album, or playlist

​
Examples

rcli listen
# Say: "Play Bohemian Rhapsody on Spotify"
# Say: "Play some jazz on Spotify"
# Say: "Play The Beatles on Spotify"

​
Implementation Details

The action constructs a Spotify search URI and uses AppleScript to open and play:
// Build Spotify search URI
std::string uri = "spotify:search:" + encoded_query;
if (type == "artist") uri = "spotify:search:artist:" + encoded_query;
else if (type == "album") uri = "spotify:search:album:" + encoded_query;
else if (type == "playlist") uri = "spotify:search:playlist:" + encoded_query;

// AppleScript execution
tell application "Spotify"
  activate
  open location "<uri>"
  delay 1.5
  play
end tell
Requirements:
  • Spotify.app must be installed
  • 1.5 second delay allows Spotify to load search results before playing
  • Timeout: 10 seconds
Source: src/actions/media_actions.cpp:70-107

​
Response

{
  "action": "play_on_spotify",
  "query": "Bohemian Rhapsody"
}

​
play_apple_music

Play a song on Apple Music by searching your library.
Disabled by default. Enable in the Actions panel or via CLI if you use Apple Music.

​
Parameters

​
query
string
required
Song name or artist

​
Examples

rcli listen
# Say: "Play The Beatles on Apple Music"
# Say: "Play Here Comes The Sun on Apple Music"

​
Implementation Details

Searches your local Music library (not Apple Music streaming catalog):
tell application "Music"
  activate
  set results to search playlist "Library" for "<query>"
  if length of results > 0 then
    play item 1 of results
    return name of item 1 of results
  else
    error "Song not found in library"
  end if
end tell
Fallback: If song not found in library, opens Apple Music web search.Timeout: 8 secondsSource: src/actions/media_actions.cpp:110-139

​
Response

{
  "action": "play_apple_music",
  "query": "The Beatles",
  "fallback": "web_search"  // Only if song not in library
}

​
play_pause_music

Toggle play/pause on the currently active music app (Music.app or Spotify).

​
Parameters

None — this action takes no parameters.

​
Examples

rcli listen
# Say: "Pause the music"
# Say: "Play"
# Say: "Resume playback"

​
Implementation Details

Tries Music.app first, then Spotify:
# Try Music.app
tell application "Music" to playpause

# If Music fails, try Spotify
tell application "Spotify" to playpause
Source: src/actions/media_actions.cpp:14-25

​
Response

{
  "action": "play_pause_music",
  "app": "Spotify"  // or "Music"
}

​
next_track

Skip to the next track on the currently active music app.

​
Parameters

None.

​
Examples

rcli listen
# Say: "Skip this song"
# Say: "Next track"

​
Implementation Details

tell application "Music" to next track
# Fallback: tell application "Spotify" to next track
Source: src/actions/media_actions.cpp:27-30

​
previous_track

Go back to the previous track on the currently active music app.
Disabled by default. Enable if you frequently use previous track.

​
Parameters

None.

​
Examples

rcli listen
# Say: "Play the previous song"
# Say: "Go back a track"

​
Implementation Details

tell application "Music" to previous track
# Fallback: tell application "Spotify" to previous track
Source: src/actions/media_actions.cpp:32-35

​
get_now_playing

Get the currently playing song and artist from Music.app or Spotify.

​
Parameters

None.

​
Examples

rcli listen
# Say: "What song is playing?"
# Say: "What's this song?"

​
Implementation Details

Checks Music.app first, then Spotify:
tell application "Music"
  if player state is playing then
    set t to name of current track
    set a to artist of current track
    return t & " by " & a
  else
    return "Nothing playing"
  end if
end tell

# Fallback: same logic for Spotify
Source: src/actions/media_actions.cpp:37-68

​
Response

{
  "action": "get_now_playing",
  "track": "Bohemian Rhapsody by Queen"
}
Or if nothing is playing: 
{
  "action": "get_now_playing",
  "track": "none"
}

​
System Volume

For system volume control (not music app volume), use the set_volume action from the System Actions category: 
rcli ask "set the volume to 50 percent"
rcli action set_volume '{"level": "50"}'

​
Voice Examples

You: “Play some jazz on Spotify”RCLI: “Playing jazz on Spotify.”(Spotify opens and starts playing jazz search results)
You: “Pause the music”RCLI: “Toggled play pause on Spotify.”You: “Skip this song”RCLI: “Skipped to next track on Spotify.”
You: “What song is playing?”RCLI: “Now playing: Bohemian Rhapsody by Queen.”

​
Troubleshooting

If you try to use play_on_spotify without Spotify installed:
{"error": "spotify not found"}
Fix: Install Spotify.app or use play_apple_music instead.
If neither Music.app nor Spotify is running:
{"error": "no music app"}
Fix: Open Music.app or Spotify before using playback controls.

​
Managing These Actions

See Managing Actions for details on enabling/disabling actions. 
# List all media actions
rcli actions | grep media

# Enable Apple Music playback
rcli action play_apple_music --enable

# Disable previous_track
rcli action previous_track --disable

Build docs developers (and LLMs) love

Get started for freeTalk to us