Musing listens for incoming connections on localhost:PORT, where PORT is 2137 by default, You can specify any other port either by a command-line argument or by an entry in the config file.
Musing exchanges data with clients through a TCP socket. Every message must consist of the following:
- Exactly 4 bytes representing a 32-bit unsigned integer
N(in big-endian). - Then, exactly
Nbytes representing a string that parses to a JSON object. Because every message in the Musing protocol is a JSON object at its core, whenever we write "a message/request contains the keyfoo" we mean that its JSON object contains the keyfoo.
After a client initiates the connection, it receives a message containing exactly one key version (the protocol's version is not relevant for now, but might be in the future when a breaking change occurs in the API).
Then, the client is free to send requests to Musing. Every request must contain a kind key (which allows Musing to distinguish endpoints) and zero or more additional keys specifying some additional arguments specific to any given request kind. All available requests are described in the next section.
Musing responds to every request with a response, which always contains a status key with a value of either ok or err. If status is err, then there will be a reason key present with a string value which describes why the request failed. Beyond that, responses may contain more keys specyfing details related to the given request. All responses are described in detail in the next section (with the status/reason keys ommitted for brevity). If a request doesn't have its response prototype listed, that means its response contains only the status/reason keys.
{
"kind": "ls",
"dir": string,
}Returns paths of all songs located in dir. The path can either be absolute or relative to the directory where the database is rooted. Only songs contained in the Musing database are taken into account. Returned paths are always absolute.
Should be used only with untagged/badly tagged music collections. With properly tagged collections using select will be more convenient.
Response:
{
"paths": array of strings,
}Example request:
{
"kind": "ls",
"dir": "/some/path",
}Example response:
{
"status": "ok",
"paths": ["/some/path/foo.mp3", "/some/path/bar.wav"],
}{
"kind": "metadata",
"paths": array of strings,
"tags": array of strings,
}or
{
"kind": "metadata",
"paths": array of strings,
"all_tags": bool,
}Returns objects containing key-value pairs representing the metadata of songs located in paths. If tags is specified, returns only the values corresponding to the provided tags. If all_tags is specified and true, returns values of all tags supported by Musing (you can find a list of supported tags at the end of these docs).
Response:
{
"metadata": array of objects,
}Example request:
{
"kind": "metadata",
"paths": ["/some/song.mp3", "/another/song.m4a"],
"tags": ["artist"],
}Example response:
{
"status": "ok",
"metadata": [{"artist": "Foo Bar"}, {"artist": "Baz Qux"}],
}{
"kind": "select",
"tags": array of strings,
"filters": array of objects,
"group_by": array of strings,
"comparators": array of objects,
}Returns paths and values of tags of those songs, which satisfy each of the filters. The results are grouped by the values of tags in group_by and sorted by comparators.
A filter is a JSON object with the following structure:
{
"kind": "regex",
"tag": string,
"regex": string,
}As the name suggests, it allows only songs whose value of tag matches the regular expression regex to "pass through". If a song has no defined value for tag, it doesn't pass the filter. Regexes are parsed by the regex crate, so a reference of their syntax is available here.
A comparator in a JSON object with the following structure:
{
"tag": string,
"order": string,
}Its job is to sort the response values according to the value of tag. The order is determined by the order key, whose only valid values are "ascending" and "descending".
Response:
{
"values": array of objects,
}Example request:
{
"kind": "select",
"tags": ["tracktitle"],
"filters": [
{
"kind": "regex",
"tag": "albumartist",
"regex": "^M.*",
},
{
"kind": "regex",
"tag": "album",
"regex": "^M.*",
},
],
"group_by": ["album"],
"comparators": [
{
"tag": "tracknumber",
"order": "descending",
},
],
}Example response:
{
"status": "ok",
"values": [
{
"album": "Metallica",
"data": [
["Enter Sandman", "tracks/01_enter_sandman.mp3"],
["Sad but True", "tracks/02_sad_but_true.mp3"],
...
]
},
{
"album": "Master of Puppets",
"data": [
["Battery", "tracks/01_battery.mp3"],
["Master of Puppets", "tracks/02_master_of_puppets.mp3"],
...
]
},
],
}{
"kind": "update",
}Updates the music database, that is adds any files that have been created since the previous update, removes songs whose files don't exist anymore and re-adds songs whose metadata has changed.
{
"kind": "volume",
"delta": integer,
}Changes the volume by delta units. The resulting volume is clamped between 0 and 100.
{
"kind": "seek",
"seconds": integer,
}Seeks the audio by seconds seconds, backwards if the value is negative, forwards otherwise.
{
"kind": "speed",
"delta": integer,
}Changes the playback speed by delta percentage points. The resulting speed is clamped between 25 and 400.
{
"kind": "gapless",
}Toggles gapless playback.
{
"kind": "pause",
}Pauses the playback. Does nothing when playback is stopped.
{
"kind": "resume",
}Resumes the playback. Does nothing when playback is stopped.
{
"kind": "toggle",
}Toggles the playback. Does nothing when playback is stopped.
{
"kind": "stop",
}Stops the playback.
{
"kind": "addqueue",
"paths": array of strings
"pos": integer (optional),
}Adds songs from paths to the queue, starting at position pos (zero-indexed). Appends songs to the end if pos is not specified or invalid.
{
"kind": "play",
"id": integer,
}Plays the song present in the queue with id equal to id.
{
"kind": "removequeue",
"ids": array of integers,
}Removes songs with ids ids from the queue.
{
"kind": "clearqueue",
}Clears the queue (removes all songs from it).
{
"kind": "next",
}Plays the next song (the next song is determined by the queue's playback mode). If there is no next song, stops the playback.
{
"kind": "previous",
}Plays the previous song from the queue. If there is no previous song, stops the playback.
{
"kind": "modesingle",
}Switches the queue into single mode: the playback stops after a song is finished.
{
"kind": "moderandom",
}Switches the queue into random mode: the next song will be chosed from a pool of those enqueued songs that haven't been played yet. After the pool is exhausted, it's regenerated with every song from the queue.
{
"kind": "modesequential",
}Switches the queue into sequential (the default) mode: songs are played one after another in order of their positions.
{
"kind": "state",
}Responds with information about the current state of Musing, in particular the response contains:
- the queue (as an array of entries, each entry containing the id and path of the song)
- the (zero-indexed) position in the queue of the current song (or
nullif playback is stopped) - the base64-encoded cover art of the current song (if available)
- the playback state (playing/paused/stopped)
- the playback mode (single/random/sequential)
- the "gaplessness" of playback
- the volume
- the playback speed
- the timer (an object containing the duration of the current song as well as how many seconds elapsed since it started)
- the list of known playlists
- the list of audio devices (and whether they're disabled/enabled)
In order to prevent sending redundant data, the response is "delta-encoded" i.e. every client receives only the keys whose values have changed since the last time it requested state. The first response to any given client will always contain the full state.
Response:
{
"queue": array of objects,
"current": integer or null,
"cover_art": string,
"playback_state": string,
"playback_mode": string,
"gapless": bool,
"volume": integer,
"speed": integer,
"timer": object,
"playlists": array of strings,
"devices": array of objects,
}Example request:
{
"kind": "state",
}Example response:
{
"status": "ok",
"queue": [{"id": 2, "path": "/some/song.mp3"}, {"id": 4, "path": "/another/song.m4a"}],
"current": 1,
"cover_art": "somebase64encodeddataxyz",
"playback_state": "paused",
"playback_mode": "random",
"gapless": false,
"volume": 60,
"speed": 100,
"timer": {"duration": 234, "elapsed": 100},
"playlists": ["/playlist/dir/abc.m3u"],
"devices": [{"device": "pipewire", "enabled": true}],
}{
"kind": "disable",
"device": string,
}Disables the given audio device.
{
"kind": "enable",
"device": string,
}Enables the given audio device.
{
"kind": "addplaylist",
"playlist": string,
"song": string,
}Appends the song to playlist (an .m3u or .m3u8 file).
{
"kind": "listsongs",
"playlist": string,
}Returns an array containing paths of all songs in the playlist file. Paths are relative to the database's root directory.
Response:
{
"songs": array of strings
}Example request:
{
"kind": "listsongs",
"playlist": "/playlist/dir/foobar.m3u",
}Example response:
{
"songs": ["song_one.mp3", "song_two.mp3"],
}{
"kind": "load",
"playlist": string,
"range": [integer, integer] (optional),
"pos": integer (optional),
}Loads the playlist to the queue. If range = [i, j] is provided, only songs from the i-th to the j-th one (zero-indexed) are loaded.
If pos is provided, then songs are inserted at position pos (also zero-indexed), otherwise they're appended to the end.
This command can succeed partially - all songs that were found in the database will be loaded, and the ones that weren't will be returned inside the reason key.
A status of ok will be returned only if all songs were found.
{
"kind": "removeplaylist",
"playlist": string,
"pos": integer,
}Removes the song at position pos (zero-indexed) from the playlist file.
{
"kind": "save",
"path": string,
}Saves the current queue as file at the given path. The created file conforms to the M3U format (one song per line).
Song paths are saved as relative to the database's root directory (which makes this operation cross-platform as relative paths are parsed as the same on UNIX and Windows).
Musing supports the following tags (valid in all requests that require tag names):
albumalbumartistarrangerartistbpmcomposerconductordatediscnumberdisctotalensemblegenrelabellanguagelyricistmoodmovementnamemovementnumberpartparttotalperformerproducerscriptsortalbumsortalbumartistsortartistsortcomposersorttracktitletracknumbertracktitle