Command line
Control a running Sonora from a terminal, a script or a key binding. The commands are part of the sonora binary, so there is nothing else to install.
sonora toggle sonora current | jq -r .track.title sonora play -s "What's Up?" sonora search daft punk --json | jq -r '.[0].link'
A command never starts Sonora. With none running it exits with code 3. Run sonora --help for the full list, or sonora <command> --help for one
command.
With Flatpak, run commands through the sandbox: flatpak run io.github.nolight132.sonora next.
Playback
sonora play / pause / toggle | Resume, pause, or switch between the two |
sonora next / prev | Skip to the next song, or go back |
sonora seek 50 | 1:30 | +10 | Jump to a percent, to a time, or by a number of seconds |
sonora volume [N | +N | -N] | Print the volume, set it from 0 to 100, or step it |
sonora shuffle [on | off | toggle] | Print or switch shuffle |
sonora repeat [off | all | one] | Print or set repeat |
Queue and search
sonora play <file or link>... | Play now, then carry on with the queue |
sonora play -s <query> | Play the best search hit now |
sonora add <file or link>... | Queue after the songs you queued by hand |
sonora play-next <file or link>... | Queue right after the current song |
sonora add -s <query> | Queue the best search hit |
sonora search <query> [-n N] | Search the current provider |
Status and the rest
sonora current | Print what plays now as JSON |
sonora watch [--position] | Print a line of JSON on every change |
sonora providers | List the providers and which one is current |
sonora provider [slug] | Print the current provider, or switch |
sonora session [start | join CODE | leave] | Print, start, join or leave a Session |
sonora completions <shell> | Print a completion script |
sonora --version | Print the version |
Details
-s picks a song. Add -t album, -t artist or -t playlist for another kind. Quote a query only when it has characters your shell
reads, such as ', ? or &.
Links have to belong to the current provider. Switch first with sonora provider.
Relative file paths start from the folder you run the command in. If one item fails, nothing is
queued.
While Sonora controls another Spotify device, playback commands go to that device.
A step with seek fits a key binding, for example in Hyprland:
bind = SUPER, right, exec, sonora seek +10 bind = SUPER, left, exec, sonora seek -10
Scripts and status bars
Add --json to any command for one line of JSON. current always prints
JSON, or null when nothing is loaded. It has the state, the song, the position in seconds,
the volume as a percent, shuffle, repeat, the provider, whether the song is liked and what it plays
from.
watch prints the same JSON again whenever the song, state, volume, shuffle or repeat
changes. --position adds a line every second while a song plays.
sonora watch | jq --unbuffered -r '.track.title // ""'
| Exit code | Meaning |
|---|---|
| 0 | Done |
| 1 | Sonora refused the command or didn't answer |
| 2 | The command line is wrong. Nothing was sent. |
| 3 | Sonora isn't running |
Shell completions
Completions exist for bash, zsh, fish, elvish and PowerShell.
sonora completions bash > ~/.local/share/bash-completion/completions/sonora
sonora completions zsh > "${fpath[1]}/_sonora"
sonora completions fish > ~/.config/fish/completions/sonora.fish