External ID Format

External ID Format

octo-fiesta uses a typed ID format to distinguish between local Navidrome content and external streaming provider content.

---

Format Specification

External IDs follow this pattern:

ext-{provider}-{type}-{id}

Component	Description	Values
ext	Prefix indicating external content	Always ext
{provider}	Streaming provider identifier	deezer, qobuz, squidwtf, tidal, yandex
{type}	Content type	song, album, artist, playlist
{id}	Provider-specific ID	Numeric or alphanumeric

---

Examples

Songs

Provider	Example ID
Deezer	ext-deezer-song-123456789
Qobuz	ext-qobuz-song-54091881
SquidWTF	ext-squidwtf-song-54091881
Tidal	ext-tidal-song-77712242
Yandex	ext-yandex-song-12345678

Albums

Provider	Example ID
Deezer	ext-deezer-album-789012
Qobuz	ext-qobuz-album-abc123xyz
SquidWTF	ext-squidwtf-album-456789
Tidal	ext-tidal-album-77712233
Yandex	ext-yandex-album-3456789

Artists

Provider	Example ID
Deezer	ext-deezer-artist-259
Qobuz	ext-qobuz-artist-123456
SquidWTF	ext-squidwtf-artist-38324
Tidal	ext-tidal-artist-12345
Yandex	ext-yandex-artist-789012

Playlists

Provider	Example ID
Deezer	ext-deezer-playlist-908622995
Qobuz	ext-qobuz-playlist-456789
Tidal	ext-tidal-playlist-1c5d01ed-4f05-40c4-bd28-0f73099e9648
Yandex	ext-yandex-playlist-1023456789

Playlists are also addressed with the shorter pl-{provider}-{externalId} form used by the starring and M3U synchronisation code, for example pl-tidal-1c5d01ed-4f05-40c4-bd28-0f73099e9648.

---

Legacy Format

For backward compatibility, the legacy format is also supported:

ext-deezer-{id}

This format assumes the content type is song. For example:

• ext-deezer-123456 is equivalent to ext-deezer-song-123456

Note: The legacy format only works for Deezer songs. For other providers or content types, use the full format.

---

ID Recognition

octo-fiesta automatically detects external IDs by checking for the ext- prefix:

ID	Type	Action
123456	Local	Passed to Navidrome
ext-deezer-song-123456	External	Handled by streaming provider
al-789012	Local (Navidrome album)	Passed to Navidrome
ext-qobuz-album-789012	External	Handled by streaming provider

---

Provider ID Formats

Each streaming provider uses different ID formats internally:

Deezer

• Songs: Numeric (e.g., 123456789)
• Albums: Numeric (e.g., 789012)
• Artists: Numeric (e.g., 259)
• Playlists: Numeric (e.g., 908622995)

Qobuz

• Songs: Numeric (e.g., 54091881)
• Albums: Alphanumeric (e.g., abc123xyz789)
• Artists: Numeric (e.g., 123456)
• Playlists: Numeric (e.g., 456789)

SquidWTF

SquidWTF uses the same ID format as its backend:

• Qobuz backend: Same as Qobuz IDs
• Tidal backend: Numeric IDs

All SquidWTF content uses the squidwtf provider identifier in external IDs.

Tidal

• Songs: Numeric (e.g., 77712242)
• Albums: Numeric (e.g., 77712233)
• Artists: Numeric (e.g., 12345)
• Playlists: UUID (e.g., 1c5d01ed-4f05-40c4-bd28-0f73099e9648)

Yandex

• Songs: Numeric (e.g., 12345678)
• Albums: Numeric (e.g., 3456789)
• Artists: Numeric (e.g., 789012)
• Playlists: Numeric (e.g., 1023456789)

---

Usage in API Calls

External IDs can be used in any Subsonic API endpoint that accepts an ID:

# Stream an external song
curl "http://localhost:5274/rest/stream?id=ext-deezer-song-123456&u=user&p=pass&v=1.16.1&c=myapp"

# Get external album details
curl "http://localhost:5274/rest/getAlbum?id=ext-qobuz-album-abc123&u=user&p=pass&v=1.16.1&c=myapp"

# Get cover art for external content
curl "http://localhost:5274/rest/getCoverArt?id=ext-squidwtf-album-456789&u=user&p=pass&v=1.16.1&c=myapp"

---

Implementation Details

For developers interested in the implementation:

// Parsing external IDs
public static class PlaylistIdHelper
{
    public static bool IsExternalId(string id)
    {
        return id.StartsWith("ext-");
    }
    
    public static (string provider, string type, string id) ParseExternalId(string externalId)
    {
        // ext-provider-type-id
        var parts = externalId.Split('-');
        // ... parsing logic
    }
}

The helper class PlaylistIdHelper in Services/Common/ handles ID parsing and validation.