# Navidrome

> Browse your Navidrome music library: search it, list new, most played and top rated albums, pick random songs and read lyrics. Manage favourites, ratings and playlists, see what's playing and record plays. Also works with other servers that speak the same Subsonic and OpenSubsonic API, such as Airsonic-Advanced, Gonic and Ampache.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/navidrome

## Actions

### Add to favourites

Mark a song, album or artist as a favourite: the heart in Navidrome, a star in other Subsonic apps.

**Inputs**

- What it is (`item_type`, text): Whether it's a song, an album or an artist. One of: `song`, `album`, `artist`. Default: `song`.
- Song (`song_id`, text): The song: its song_id from an earlier step, such as Search the library, Get an album or Get random songs. Only when What it is is Song.
- Album (`album`, text): The album. Pick it from the list, or use an album_id from an earlier step. Only when What it is is Album.
- Artist (`artist`, text): The artist. Pick them from the list, or use an artist_id from an earlier step. Only when What it is is Artist.

**Outputs**

- `artist` (text): Who it's by.
- `favourite` (true/false): Whether it's one of your favourites.
- `item_id` (text): Its ID.
- `item_type` (text): What it is: song, album or artist.
- `name` (text): The song's title, or the album's or artist's name.
- `rating` (number): Your rating from 1 to 5 stars, or 0 when it has none.
- `url` (text): Its page in Navidrome (a song's album page). Null on other Subsonic servers.
- `was_favourite` (true/false): Whether it was a favourite already.

**Example output**

```json
{
  "artist": "Diablo Swing Orchestra",
  "favourite": true,
  "item_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
  "item_type": "song",
  "name": "Heroines",
  "rating": 3,
  "url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
  "was_favourite": false
}
```

### Create a playlist

Create a playlist, optionally filled with songs from an earlier step, with a comment, and public or private.

**Inputs**

- Name (`name`, text, required): What to call the playlist.
- Songs (`songs`, list): Song IDs, such as the song_ids an earlier step returns (Get random songs, Get an album, Search the library). Leave empty for an empty playlist.
- Comment (`comment`, text): A note shown with the playlist.
- Public (`public`, true/false): Let everyone on the server see and play it. Default: `false`.

**Outputs**

- `can_edit` (true/false): Whether it's yours, so you can change or delete it.
- `comment` (text): The playlist's comment. Null when it has none.
- `created_at` (text): When it was made.
- `duration` (text): Its length as minutes and seconds, e.g. 5:22.
- `duration_seconds` (number): Its length in seconds.
- `name` (text): The playlist's name.
- `owner` (text): The username of whoever owns it.
- `playlist_id` (text): The playlist's ID.
- `public` (true/false): Whether everyone on the server can see it.
- `song_count` (number): How many songs it has.
- `song_ids` (list): The songs' IDs in order, ready for a playlist step.
- `songs` (list): Its songs in order.
- `updated_at` (text): When it last changed.
- `url` (text): The playlist's page in Navidrome. Null on other Subsonic servers.

**Example output**

```json
{
  "can_edit": true,
  "comment": "Made by Lodol",
  "created_at": "2026-10-16T02:22:25Z",
  "duration": "5:22",
  "duration_seconds": 322,
  "name": "Friday mix",
  "owner": "demo",
  "playlist_id": "5ht5jj61nTBTyEUipS7Oqb",
  "public": false,
  "song_count": 1,
  "song_ids": [
    "7C5bQ7Xk1VhCQ2db0bpucJ"
  ],
  "songs": [
    {
      "album": "netBloc Vol. 24: tiuqottigeloot",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "bit_rate_kbps": 192,
      "disc_number": null,
      "duration": "5:22",
      "duration_seconds": 322,
      "favourite": false,
      "favourited_at": null,
      "file_format": "mp3",
      "genre": "Netlabel",
      "last_played_at": "2026-10-15T17:02:51Z",
      "play_count": 1334,
      "rating": 3,
      "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
      "title": "Heroines",
      "track_number": 1,
      "year": 2009
    }
  ],
  "updated_at": "2026-10-16T02:22:25Z",
  "url": "https://demo.navidrome.org/app/#/playlist/5ht5jj61nTBTyEUipS7Oqb/show"
}
```

### Delete a playlist

Delete one of your playlists. The songs in it stay in your library.

**Inputs**

- Playlist (`playlist`, text, required): One of your playlists. Other people's can't be changed.

**Outputs**

- `deleted` (true/false): True once the playlist is gone.
- `name` (text): The deleted playlist's name.
- `playlist_id` (text): The deleted playlist's ID.

**Example output**

```json
{
  "deleted": true,
  "name": "Friday mix",
  "playlist_id": "5ht5jj61nTBTyEUipS7Oqb"
}
```

### Get a playlist

Get a playlist's details and its songs in order.

**Inputs**

- Playlist (`playlist`, text, required): The playlist: yours, or someone else's public one.

**Outputs**

- `can_edit` (true/false): Whether it's yours, so you can change or delete it.
- `comment` (text): The playlist's comment. Null when it has none.
- `created_at` (text): When it was made.
- `duration` (text): Its length as minutes and seconds, e.g. 5:22.
- `duration_seconds` (number): Its length in seconds.
- `name` (text): The playlist's name.
- `owner` (text): The username of whoever owns it.
- `playlist_id` (text): The playlist's ID.
- `public` (true/false): Whether everyone on the server can see it.
- `song_count` (number): How many songs it has.
- `song_ids` (list): The songs' IDs in order, ready for a playlist step.
- `songs` (list): Its songs in order.
- `updated_at` (text): When it last changed.
- `url` (text): The playlist's page in Navidrome. Null on other Subsonic servers.

**Example output**

```json
{
  "can_edit": true,
  "comment": "Made by Lodol",
  "created_at": "2026-10-16T02:22:25Z",
  "duration": "5:22",
  "duration_seconds": 322,
  "name": "Friday mix",
  "owner": "demo",
  "playlist_id": "5ht5jj61nTBTyEUipS7Oqb",
  "public": false,
  "song_count": 1,
  "song_ids": [
    "7C5bQ7Xk1VhCQ2db0bpucJ"
  ],
  "songs": [
    {
      "album": "netBloc Vol. 24: tiuqottigeloot",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "bit_rate_kbps": 192,
      "disc_number": null,
      "duration": "5:22",
      "duration_seconds": 322,
      "favourite": false,
      "favourited_at": null,
      "file_format": "mp3",
      "genre": "Netlabel",
      "last_played_at": "2026-10-15T17:02:51Z",
      "play_count": 1334,
      "rating": 3,
      "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
      "title": "Heroines",
      "track_number": 1,
      "year": 2009
    }
  ],
  "updated_at": "2026-10-16T02:22:25Z",
  "url": "https://demo.navidrome.org/app/#/playlist/5ht5jj61nTBTyEUipS7Oqb/show"
}
```

### Get a song

Get one song's details: title, artist, album, length, plays, rating and whether it's a favourite.

**Inputs**

- Song (`song_id`, text, required): The song: its song_id from an earlier step, such as Search the library, Get an album or Get random songs.

**Outputs**

- `album` (text): The album it's on.
- `album_id` (text): The album's ID.
- `album_url` (text): The album's page in Navidrome. Null on other Subsonic servers.
- `artist` (text): Who performs it.
- `artist_id` (text): The artist's ID.
- `bit_rate_kbps` (number): The file's quality in kilobits a second, e.g. 320.
- `disc_number` (number): Which disc of the album it's on. Null if unknown.
- `duration` (text): Its length as minutes and seconds, e.g. 5:22.
- `duration_seconds` (number): Its length in seconds.
- `favourite` (true/false): Whether it's one of your favourites.
- `favourited_at` (text): When you made it a favourite. Null if it isn't one.
- `file_format` (text): The file type, e.g. mp3 or flac.
- `genre` (text): Its genre. Null if unknown.
- `last_played_at` (text): When you last played it, e.g. 2026-10-15T20:43:22Z. Null if never.
- `play_count` (number): How many times you've played it.
- `rating` (number): Your rating from 1 to 5 stars, or 0 when it has none.
- `song_id` (text): The song's ID.
- `title` (text): The song's title.
- `track_number` (number): Its track number on the album. Null if unknown.
- `year` (number): The year it came out. Null if unknown.

**Example output**

```json
{
  "album": "netBloc Vol. 24: tiuqottigeloot",
  "album_id": "6oq0g9th4iTM8a0y0T88tr",
  "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
  "artist": "Diablo Swing Orchestra",
  "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
  "bit_rate_kbps": 192,
  "disc_number": null,
  "duration": "5:22",
  "duration_seconds": 322,
  "favourite": false,
  "favourited_at": null,
  "file_format": "mp3",
  "genre": "Netlabel",
  "last_played_at": "2026-10-15T17:02:51Z",
  "play_count": 1334,
  "rating": 3,
  "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
  "title": "Heroines",
  "track_number": 1,
  "year": 2009
}
```

### Get a song's lyrics

Get a song's lyrics as text, and line by line with the time each line is sung when the server has timed lyrics.

**Inputs**

- Song (`song_id`, text, required): The song: its song_id from an earlier step, such as Search the library, Get an album or Get random songs.

**Outputs**

- `artist` (text): Who performs it.
- `has_lyrics` (true/false): Whether the server has lyrics for it.
- `language` (text): The lyrics' language, e.g. eng. Null if unknown.
- `lines` (list): The lyrics line by line.
- `lyrics` (text): The whole lyrics, one line per line. Empty when there are none.
- `song_id` (text): The song's ID.
- `synced` (true/false): Whether the lines come with their times.
- `title` (text): The song's title.

**Example output**

```json
{
  "artist": "pornophonique",
  "has_lyrics": true,
  "language": "eng",
  "lines": [
    {
      "start_seconds": null,
      "text": "sometimes i fear the reaper"
    },
    {
      "start_seconds": null,
      "text": "sometimes i'm afraid to die"
    }
  ],
  "lyrics": "sometimes i fear the reaper\nsometimes i'm afraid to die",
  "song_id": "4PyP4nlXRSySf1XwZNf6f1",
  "synced": false,
  "title": "lemmings in love"
}
```

### Get an album

Get an album's details and its songs in order, with each song's length, plays and rating.

**Inputs**

- Album (`album`, text, required): The album. Pick it from the list, or use an album_id from an earlier step. Its link from Navidrome works too.

**Outputs**

- `added_at` (text): When it was added to the library, e.g. 2025-03-26T22:26:49Z.
- `album_id` (text): The album's ID.
- `artist` (text): The album's artist.
- `artist_id` (text): The artist's ID.
- `duration` (text): Its length as minutes and seconds, e.g. 5:22.
- `duration_seconds` (number): Its length in seconds.
- `favourite` (true/false): Whether it's one of your favourites.
- `favourited_at` (text): When you made it a favourite. Null if it isn't one.
- `genre` (text): Its main genre. Null if unknown.
- `genres` (list): Every genre it's tagged with.
- `is_compilation` (true/false): Whether it's a compilation of several artists.
- `last_played_at` (text): When you last played it, e.g. 2026-10-15T20:43:22Z. Null if never.
- `name` (text): The album's title.
- `play_count` (number): How many times you've played it.
- `rating` (number): Your rating from 1 to 5 stars, or 0 when it has none.
- `song_count` (number): How many songs it has.
- `song_ids` (list): The songs' IDs in order, ready for a playlist step.
- `songs` (list): Its songs in order.
- `url` (text): The album's page in Navidrome. Null on other Subsonic servers.
- `year` (number): The year it came out. Null if unknown.

**Example output**

```json
{
  "added_at": "2025-03-26T22:26:49Z",
  "album_id": "6oq0g9th4iTM8a0y0T88tr",
  "artist": "Various Artists",
  "artist_id": "63sqASlAfjbGMuLP4JhnZU",
  "duration": "43:35",
  "duration_seconds": 2615,
  "favourite": true,
  "favourited_at": "2026-10-15T03:30:42Z",
  "genre": "Netlabel",
  "genres": [
    "Netlabel"
  ],
  "is_compilation": true,
  "last_played_at": "2026-10-15T19:23:41Z",
  "name": "netBloc Vol. 24: tiuqottigeloot",
  "play_count": 3356,
  "rating": 5,
  "song_count": 12,
  "song_ids": [
    "7C5bQ7Xk1VhCQ2db0bpucJ"
  ],
  "songs": [
    {
      "album": "netBloc Vol. 24: tiuqottigeloot",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "bit_rate_kbps": 192,
      "disc_number": null,
      "duration": "5:22",
      "duration_seconds": 322,
      "favourite": false,
      "favourited_at": null,
      "file_format": "mp3",
      "genre": "Netlabel",
      "last_played_at": "2026-10-15T17:02:51Z",
      "play_count": 1334,
      "rating": 3,
      "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
      "title": "Heroines",
      "track_number": 1,
      "year": 2009
    }
  ],
  "url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
  "year": 2009
}
```

### Get an artist

Get an artist's details and albums, with a short biography and picture when the server has them.

**Inputs**

- Artist (`artist`, text, required): The artist. Pick them from the list, or use an artist_id from an earlier step. Their link from Navidrome works too.

**Outputs**

- `album_count` (number): How many albums they have.
- `albums` (list): Their albums.
- `artist_id` (text): The artist's ID.
- `biography` (text): A short biography, from Last.fm when the server uses it. Null when there's none.
- `favourite` (true/false): Whether it's one of your favourites.
- `favourited_at` (text): When you made it a favourite. Null if it isn't one.
- `image_url` (text): A picture of the artist. Null when the server has none.
- `name` (text): The artist's name.
- `rating` (number): Your rating from 1 to 5 stars, or 0 when it has none.
- `url` (text): The artist's page in Navidrome. Null on other Subsonic servers.

**Example output**

```json
{
  "album_count": 1,
  "albums": [
    {
      "added_at": "2025-03-26T22:26:39Z",
      "album_id": "3Ss0LvMLYHiAOYlMrwcxtj",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "duration": "50:09",
      "duration_seconds": 3009,
      "favourite": false,
      "favourited_at": null,
      "genre": "Rock",
      "genres": [
        "Rock"
      ],
      "is_compilation": false,
      "last_played_at": "2026-10-15T22:43:12Z",
      "name": "The Butcher's Ballroom",
      "play_count": 2771,
      "rating": 5,
      "song_count": 13,
      "url": "https://demo.navidrome.org/app/#/album/3Ss0LvMLYHiAOYlMrwcxtj/show",
      "year": 2009
    }
  ],
  "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
  "biography": "A Swedish avant-garde metal ensemble with a penchant for pairing elements of jazz, swing, classical, and progressive rock with Marshall stack-powered sonic might.",
  "favourite": false,
  "favourited_at": null,
  "image_url": "https://demo.navidrome.org/share/img/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFyLTFId3hGbTM4TXlpNEtHNVdNRURTMktfMTVmOTczYjFlNDk1ZDkzMSIsImlzcyI6Ik5EIn0.Gvu0WCCJM8Y1EbmrUzowjTMc6khTChTf9T0ajSI-3Nk?size=600",
  "name": "Diablo Swing Orchestra",
  "rating": 0,
  "url": "https://demo.navidrome.org/app/#/artist/1HwxFm38Myi4KG5WMEDS2K/show"
}
```

### Get random songs

Pick songs at random from your library, optionally from one genre or a span of years, for a playlist or a daily pick.

**Inputs**

- How many (`count`, number): How many songs to pick. From 1 to 500. Default: `10`.
- Genre (`genre`, text): Only songs in this genre. Leave empty for any.
- From year (`from_year`, number): Only from this year on, such as 1990. Leave empty for any.
- To year (`to_year`, number): Only up to this year, such as 1999. Leave empty for any.

**Outputs**

- `count` (number): How many songs.
- `song_ids` (list): The songs' IDs in order, ready for a playlist step.
- `songs` (list): The songs picked.

**Example output**

```json
{
  "count": 1,
  "song_ids": [
    "7C5bQ7Xk1VhCQ2db0bpucJ"
  ],
  "songs": [
    {
      "album": "netBloc Vol. 24: tiuqottigeloot",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "bit_rate_kbps": 192,
      "disc_number": null,
      "duration": "5:22",
      "duration_seconds": 322,
      "favourite": false,
      "favourited_at": null,
      "file_format": "mp3",
      "genre": "Netlabel",
      "last_played_at": "2026-10-15T17:02:51Z",
      "play_count": 1334,
      "rating": 3,
      "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
      "title": "Heroines",
      "track_number": 1,
      "year": 2009
    }
  ]
}
```

### Get what's playing now

See what everyone on your server is listening to right now, and on which player.

**Inputs**: None.

**Outputs**

- `count` (number): How many players are playing.
- `playing` (list): What's playing, one entry per player.

**Example output**

```json
{
  "count": 1,
  "playing": [
    {
      "album": "netBloc Vol. 24: tiuqottigeloot",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "bit_rate_kbps": 192,
      "disc_number": null,
      "duration": "5:22",
      "duration_seconds": 322,
      "favourite": false,
      "favourited_at": null,
      "file_format": "mp3",
      "genre": "Netlabel",
      "last_played_at": "2026-10-15T17:02:51Z",
      "minutes_ago": 0,
      "play_count": 1334,
      "player_name": "NavidromeUI",
      "rating": 3,
      "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
      "title": "Heroines",
      "track_number": 1,
      "username": "demo",
      "year": 2009
    }
  ]
}
```

### List albums

List albums from your library: recently added, recently played, most played, top rated, favourites, random, A to Z, from a span of years or in one genre.

**Inputs**

- Which albums (`list_type`, text): Which albums to list, and in what order. One of: `recently_added` (Recently added), `recently_played` (Recently played), `most_played` (Most played), `top_rated` (Top rated), `favourites`, `random`, `by_name` (A to Z by album name), `by_artist` (A to Z by artist), `by_year` (Released between two years), `by_genre` (In one genre). Default: `recently_added`.
- Genre (`genre`, text): The genre whose albums to list. Only when Which albums is In one genre.
- From year (`from_year`, number): The earliest year, such as 1990. Only when Which albums is Released between two years.
- To year (`to_year`, number): The latest year, such as 1999. Leave empty for this year. Only when Which albums is Released between two years.
- How many (`limit`, number): At most this many albums. From 1 to 500. Default: `50`.
- Skip (`skip`, number): Skip this many albums first, to read the next page of a long list. Default: `0`.

**Outputs**

- `albums` (list): The albums, in the list's order.
- `count` (number): How many albums.
- `has_more` (true/false): Whether there may be more: skip this many to read the next page.
- `list` (text): Which albums these are, e.g. Recently added.

**Example output**

```json
{
  "albums": [
    {
      "added_at": "2025-03-26T22:26:49Z",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "artist": "Various Artists",
      "artist_id": "63sqASlAfjbGMuLP4JhnZU",
      "duration": "43:35",
      "duration_seconds": 2615,
      "favourite": true,
      "favourited_at": "2026-10-15T03:30:42Z",
      "genre": "Netlabel",
      "genres": [
        "Netlabel"
      ],
      "is_compilation": true,
      "last_played_at": "2026-10-15T19:23:41Z",
      "name": "netBloc Vol. 24: tiuqottigeloot",
      "play_count": 3356,
      "rating": 5,
      "song_count": 12,
      "url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "year": 2009
    }
  ],
  "count": 1,
  "has_more": false,
  "list": "Recently added"
}
```

### List artists

List the artists in your music library, A to Z, with how many albums each has: 50 at a time unless you ask for up to 500.

**Inputs**

- How many (`limit`, number): At most this many artists. From 1 to 500. Default: `50`.
- Skip (`skip`, number): Skip this many first, to read the next page of a long list. Leave at 0 for the start. At least 0. Default: `0`.

**Outputs**

- `artists` (list): The artists, A to Z.
- `count` (number): How many artists are in this list.
- `has_more` (true/false): Whether there are more: skip this many to read the next page.
- `total` (number): How many artists the library has in all.

**Example output**

```json
{
  "artists": [
    {
      "album_count": 1,
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "favourite": false,
      "favourited_at": null,
      "image_url": "https://demo.navidrome.org/share/img/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFyLTFId3hGbTM4TXlpNEtHNVdNRURTMktfMTVmOTczYjFlNDk1ZDkzMSIsImlzcyI6Ik5EIn0.Gvu0WCCJM8Y1EbmrUzowjTMc6khTChTf9T0ajSI-3Nk?size=600",
      "name": "Diablo Swing Orchestra",
      "rating": 0,
      "url": "https://demo.navidrome.org/app/#/artist/1HwxFm38Myi4KG5WMEDS2K/show"
    }
  ],
  "count": 1,
  "has_more": true,
  "total": 26
}
```

### List favourites

List the songs, albums and artists you've marked as favourites (starred, in other Subsonic apps), newest first: 50 of each unless you ask for up to 500.

**Inputs**

- How many (`limit`, number): At most this many songs, albums and artists each. From 1 to 500. Default: `50`.
- Skip (`skip`, number): Skip this many first, to read the next page of a long list. Leave at 0 for the start. At least 0. Default: `0`.

**Outputs**

- `album_count` (number): How many albums are in this list.
- `albums` (list): Favourite albums.
- `artist_count` (number): How many artists are in this list.
- `artists` (list): Favourite artists.
- `has_more` (true/false): Whether there are more of any kind: skip this many to read the next page.
- `song_count` (number): How many songs are in this list.
- `song_ids` (list): The songs' IDs in order, ready for a playlist step.
- `songs` (list): Favourite songs.
- `total_albums` (number): How many favourite albums you have in all.
- `total_artists` (number): How many favourite artists you have in all.
- `total_songs` (number): How many favourite songs you have in all.

**Example output**

```json
{
  "album_count": 1,
  "albums": [
    {
      "added_at": "2025-03-26T22:26:49Z",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "artist": "Various Artists",
      "artist_id": "63sqASlAfjbGMuLP4JhnZU",
      "duration": "43:35",
      "duration_seconds": 2615,
      "favourite": true,
      "favourited_at": "2026-10-15T03:30:42Z",
      "genre": "Netlabel",
      "genres": [
        "Netlabel"
      ],
      "is_compilation": true,
      "last_played_at": "2026-10-15T19:23:41Z",
      "name": "netBloc Vol. 24: tiuqottigeloot",
      "play_count": 3356,
      "rating": 5,
      "song_count": 12,
      "url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "year": 2009
    }
  ],
  "artist_count": 0,
  "artists": [],
  "has_more": false,
  "song_count": 1,
  "song_ids": [
    "7C5bQ7Xk1VhCQ2db0bpucJ"
  ],
  "songs": [
    {
      "album": "netBloc Vol. 24: tiuqottigeloot",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "bit_rate_kbps": 192,
      "disc_number": null,
      "duration": "5:22",
      "duration_seconds": 322,
      "favourite": true,
      "favourited_at": null,
      "file_format": "mp3",
      "genre": "Netlabel",
      "last_played_at": "2026-10-15T17:02:51Z",
      "play_count": 1334,
      "rating": 3,
      "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
      "title": "Heroines",
      "track_number": 1,
      "year": 2009
    }
  ],
  "total_albums": 1,
  "total_artists": 0,
  "total_songs": 1
}
```

### List genres

List the genres in your library with how many songs and albums each has, the biggest first.

**Inputs**: None.

**Outputs**

- `count` (number): How many genres.
- `genres` (list): Every genre, the most songs first.

**Example output**

```json
{
  "count": 2,
  "genres": [
    {
      "album_count": 10,
      "name": "Electronic",
      "song_count": 73
    },
    {
      "album_count": 6,
      "name": "Rock",
      "song_count": 28
    }
  ]
}
```

### List playlists

List your playlists and other people's public ones, with how many songs each has and who owns it.

**Inputs**: None.

**Outputs**

- `count` (number): How many playlists.
- `playlists` (list): The playlists.

**Example output**

```json
{
  "count": 1,
  "playlists": [
    {
      "can_edit": true,
      "comment": "Made by Lodol",
      "created_at": "2026-10-16T02:22:25Z",
      "duration": "5:22",
      "duration_seconds": 322,
      "name": "Friday mix",
      "owner": "demo",
      "playlist_id": "5ht5jj61nTBTyEUipS7Oqb",
      "public": false,
      "song_count": 1,
      "updated_at": "2026-10-16T02:22:25Z",
      "url": "https://demo.navidrome.org/app/#/playlist/5ht5jj61nTBTyEUipS7Oqb/show"
    }
  ]
}
```

### Rate a song, album or artist

Give a song, album or artist a rating from 1 to 5 stars, or clear its rating.

**Inputs**

- What it is (`item_type`, text): Whether it's a song, an album or an artist. One of: `song`, `album`, `artist`. Default: `song`.
- Song (`song_id`, text): The song: its song_id from an earlier step, such as Search the library, Get an album or Get random songs. Only when What it is is Song.
- Album (`album`, text): The album. Pick it from the list, or use an album_id from an earlier step. Only when What it is is Album.
- Artist (`artist`, text): The artist. Pick them from the list, or use an artist_id from an earlier step. Only when What it is is Artist.
- Rating (`rating`, text, required): How many stars to give it. One of: `5` (5 stars), `4` (4 stars), `3` (3 stars), `2` (2 stars), `1` (1 star), `0` (No rating (removes it)).

**Outputs**

- `artist` (text): Who it's by.
- `favourite` (true/false): Whether it's one of your favourites.
- `item_id` (text): Its ID.
- `item_type` (text): What it is: song, album or artist.
- `name` (text): The song's title, or the album's or artist's name.
- `previous_rating` (number): Its rating before, 0 when it had none.
- `rating` (number): Your rating from 1 to 5 stars, or 0 when it has none.
- `url` (text): Its page in Navidrome (a song's album page). Null on other Subsonic servers.

**Example output**

```json
{
  "artist": "Diablo Swing Orchestra",
  "favourite": true,
  "item_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
  "item_type": "song",
  "name": "Heroines",
  "previous_rating": 3,
  "rating": 5,
  "url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show"
}
```

### Record a play

Count a play of a song, or show it as playing now. Navidrome passes plays on to Last.fm or ListenBrainz if you've linked them.

**Inputs**

- Song (`song_id`, text, required): The song: its song_id from an earlier step, such as Search the library, Get an album or Get random songs.
- What happened (`event`, text): Whether the song finished or just started. One of: `finished` (Finished playing: count a play), `started` (Started playing: show as now playing). Default: `finished`.
- Played at (`played_at`, date and time): When it was played. Leave empty for now. Only when What happened is Finished playing: count a play.

**Outputs**

- `album` (text): The album it's on.
- `album_id` (text): The album's ID.
- `album_url` (text): The album's page in Navidrome. Null on other Subsonic servers.
- `artist` (text): Who performs it.
- `artist_id` (text): The artist's ID.
- `bit_rate_kbps` (number): The file's quality in kilobits a second, e.g. 320.
- `disc_number` (number): Which disc of the album it's on. Null if unknown.
- `duration` (text): Its length as minutes and seconds, e.g. 5:22.
- `duration_seconds` (number): Its length in seconds.
- `favourite` (true/false): Whether it's one of your favourites.
- `favourited_at` (text): When you made it a favourite. Null if it isn't one.
- `file_format` (text): The file type, e.g. mp3 or flac.
- `genre` (text): Its genre. Null if unknown.
- `last_played_at` (text): When you last played it, e.g. 2026-10-15T20:43:22Z. Null if never.
- `play_count` (number): How many times you've played it.
- `played_at` (text): When the counted play happened. Null for now playing.
- `rating` (number): Your rating from 1 to 5 stars, or 0 when it has none.
- `recorded_as` (text): play when a play was counted, now_playing when it shows as playing now.
- `song_id` (text): The song's ID.
- `title` (text): The song's title.
- `track_number` (number): Its track number on the album. Null if unknown.
- `year` (number): The year it came out. Null if unknown.

**Example output**

```json
{
  "album": "netBloc Vol. 24: tiuqottigeloot",
  "album_id": "6oq0g9th4iTM8a0y0T88tr",
  "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
  "artist": "Diablo Swing Orchestra",
  "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
  "bit_rate_kbps": 192,
  "disc_number": null,
  "duration": "5:22",
  "duration_seconds": 322,
  "favourite": false,
  "favourited_at": null,
  "file_format": "mp3",
  "genre": "Netlabel",
  "last_played_at": "2026-10-16T02:27:11Z",
  "play_count": 1335,
  "played_at": "2026-10-16T02:27:11Z",
  "rating": 3,
  "recorded_as": "play",
  "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
  "title": "Heroines",
  "track_number": 1,
  "year": 2009
}
```

### Remove from favourites

Take a song, album or artist out of your favourites.

**Inputs**

- What it is (`item_type`, text): Whether it's a song, an album or an artist. One of: `song`, `album`, `artist`. Default: `song`.
- Song (`song_id`, text): The song: its song_id from an earlier step, such as Search the library, Get an album or Get random songs. Only when What it is is Song.
- Album (`album`, text): The album. Pick it from the list, or use an album_id from an earlier step. Only when What it is is Album.
- Artist (`artist`, text): The artist. Pick them from the list, or use an artist_id from an earlier step. Only when What it is is Artist.

**Outputs**

- `artist` (text): Who it's by.
- `favourite` (true/false): Whether it's one of your favourites.
- `item_id` (text): Its ID.
- `item_type` (text): What it is: song, album or artist.
- `name` (text): The song's title, or the album's or artist's name.
- `rating` (number): Your rating from 1 to 5 stars, or 0 when it has none.
- `url` (text): Its page in Navidrome (a song's album page). Null on other Subsonic servers.
- `was_favourite` (true/false): Whether it was a favourite before.

**Example output**

```json
{
  "artist": "Diablo Swing Orchestra",
  "favourite": false,
  "item_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
  "item_type": "song",
  "name": "Heroines",
  "rating": 3,
  "url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
  "was_favourite": true
}
```

### Search the library

Find artists, albums and songs whose names match some words, such as part of a title or an artist's name.

**Inputs**

- Search for (`query`, text, required): Words to look for in names and titles.
- Results of each kind (`limit`, number): At most this many artists, albums and songs each. From 1 to 500. Default: `20`.

**Outputs**

- `album_count` (number): How many albums matched.
- `albums` (list): Matching albums.
- `artist_count` (number): How many artists matched.
- `artists` (list): Matching artists.
- `query` (text): What was searched.
- `song_count` (number): How many songs matched.
- `song_ids` (list): The songs' IDs in order, ready for a playlist step.
- `songs` (list): Matching songs.

**Example output**

```json
{
  "album_count": 1,
  "albums": [
    {
      "added_at": "2025-03-26T22:26:39Z",
      "album_id": "3Ss0LvMLYHiAOYlMrwcxtj",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "duration": "50:09",
      "duration_seconds": 3009,
      "favourite": false,
      "favourited_at": null,
      "genre": "Rock",
      "genres": [
        "Rock"
      ],
      "is_compilation": false,
      "last_played_at": "2026-10-15T22:43:12Z",
      "name": "The Butcher's Ballroom",
      "play_count": 2771,
      "rating": 5,
      "song_count": 13,
      "url": "https://demo.navidrome.org/app/#/album/3Ss0LvMLYHiAOYlMrwcxtj/show",
      "year": 2009
    }
  ],
  "artist_count": 1,
  "artists": [
    {
      "album_count": 1,
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "favourite": false,
      "favourited_at": null,
      "image_url": "https://demo.navidrome.org/share/img/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6ImFyLTFId3hGbTM4TXlpNEtHNVdNRURTMktfMTVmOTczYjFlNDk1ZDkzMSIsImlzcyI6Ik5EIn0.Gvu0WCCJM8Y1EbmrUzowjTMc6khTChTf9T0ajSI-3Nk?size=600",
      "name": "Diablo Swing Orchestra",
      "rating": 0,
      "url": "https://demo.navidrome.org/app/#/artist/1HwxFm38Myi4KG5WMEDS2K/show"
    }
  ],
  "query": "Diablo Swing",
  "song_count": 1,
  "song_ids": [
    "7C5bQ7Xk1VhCQ2db0bpucJ"
  ],
  "songs": [
    {
      "album": "netBloc Vol. 24: tiuqottigeloot",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "bit_rate_kbps": 192,
      "disc_number": null,
      "duration": "5:22",
      "duration_seconds": 322,
      "favourite": false,
      "favourited_at": null,
      "file_format": "mp3",
      "genre": "Netlabel",
      "last_played_at": "2026-10-15T17:02:51Z",
      "play_count": 1334,
      "rating": 3,
      "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
      "title": "Heroines",
      "track_number": 1,
      "year": 2009
    }
  ]
}
```

### Update a playlist

Rename one of your playlists, change its comment or who can see it, and add or remove songs.

**Inputs**

- Playlist (`playlist`, text, required): One of your playlists. Other people's can't be changed.
- New name (`name`, text): A new name. Leave empty to keep the name.
- Comment (`comment`, text): A new comment. Leave empty to keep the comment.
- Who can see it (`public`, text): Make it public or private, or leave it as it is. One of: `unchanged` (Leave as it is), `public` (Public: everyone on the server can see it), `private` (Private: only you). Default: `unchanged`.
- Songs to add (`add_songs`, list): Song IDs, such as the song_ids an earlier step returns (Get random songs, Get an album, Search the library). They go at the end of the playlist.
- Songs to remove (`remove_songs`, list): Song IDs to take out of the playlist, everywhere they appear in it.

**Outputs**

- `can_edit` (true/false): Whether it's yours, so you can change or delete it.
- `comment` (text): The playlist's comment. Null when it has none.
- `created_at` (text): When it was made.
- `duration` (text): Its length as minutes and seconds, e.g. 5:22.
- `duration_seconds` (number): Its length in seconds.
- `name` (text): The playlist's name.
- `owner` (text): The username of whoever owns it.
- `playlist_id` (text): The playlist's ID.
- `public` (true/false): Whether everyone on the server can see it.
- `song_count` (number): How many songs it has.
- `song_ids` (list): The songs' IDs in order, ready for a playlist step.
- `songs` (list): Its songs in order.
- `songs_added` (number): How many songs were added.
- `songs_removed` (number): How many songs were taken out.
- `updated_at` (text): When it last changed.
- `url` (text): The playlist's page in Navidrome. Null on other Subsonic servers.

**Example output**

```json
{
  "can_edit": true,
  "comment": "Made by Lodol",
  "created_at": "2026-10-16T02:22:25Z",
  "duration": "5:22",
  "duration_seconds": 322,
  "name": "Friday mix",
  "owner": "demo",
  "playlist_id": "5ht5jj61nTBTyEUipS7Oqb",
  "public": true,
  "song_count": 1,
  "song_ids": [
    "7C5bQ7Xk1VhCQ2db0bpucJ"
  ],
  "songs": [
    {
      "album": "netBloc Vol. 24: tiuqottigeloot",
      "album_id": "6oq0g9th4iTM8a0y0T88tr",
      "album_url": "https://demo.navidrome.org/app/#/album/6oq0g9th4iTM8a0y0T88tr/show",
      "artist": "Diablo Swing Orchestra",
      "artist_id": "1HwxFm38Myi4KG5WMEDS2K",
      "bit_rate_kbps": 192,
      "disc_number": null,
      "duration": "5:22",
      "duration_seconds": 322,
      "favourite": false,
      "favourited_at": null,
      "file_format": "mp3",
      "genre": "Netlabel",
      "last_played_at": "2026-10-15T17:02:51Z",
      "play_count": 1334,
      "rating": 3,
      "song_id": "7C5bQ7Xk1VhCQ2db0bpucJ",
      "title": "Heroines",
      "track_number": 1,
      "year": 2009
    }
  ],
  "songs_added": 1,
  "songs_removed": 0,
  "updated_at": "2026-10-16T02:22:25Z",
  "url": "https://demo.navidrome.org/app/#/playlist/5ht5jj61nTBTyEUipS7Oqb/show"
}
```