From 651b86694d17cb2c516afae0c740bf70c442d83a Mon Sep 17 00:00:00 2001 From: V1ck3s Date: Thu, 8 Jan 2026 00:13:01 +0100 Subject: [PATCH] docs: update README for multi-provider architecture --- README.md | 136 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 85 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index d4dcddc..d4b82be 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Octo-Fiesta -A Subsonic API proxy server that transparently integrates Deezer as a music source. When a song is not available in your local Navidrome library, it is automatically fetched from Deezer, downloaded, and served to your Subsonic-compatible client. The downloaded song is then added to your library, making it available locally for future listens. +A Subsonic API proxy server that transparently integrates multiple music streaming providers as sources. When a song is not available in your local Navidrome library, it is automatically fetched from your configured provider, downloaded, and served to your Subsonic-compatible client. The downloaded song is then added to your library, making it available locally for future listens. ## Why "Octo-Fiesta"? @@ -8,13 +8,15 @@ The name was randomly generated by GitHub when creating the repository. We found ## Features +- **Multi-Provider Architecture**: Pluggable music service system supporting multiple streaming providers (Deezer, Qobuz, and more to come) - **Transparent Proxy**: Acts as a middleware between Subsonic clients (like Aonsoku, Sublime Music, etc.) and your Navidrome server -- **Deezer Integration**: Seamlessly searches and streams music from Deezer when not available locally +- **Seamless Integration**: Automatically searches and streams music from your configured provider when not available locally - **Automatic Downloads**: Songs are downloaded on-the-fly and cached for future use +- **Hi-Res Audio Support**: Qobuz provider supports up to 24-bit/192kHz FLAC quality - **Full Metadata Embedding**: Downloaded files include complete ID3 tags (title, artist, album, track number, year, genre, BPM, ISRC, etc.) and embedded cover art -- **Organized Library**: Downloads are saved in a clean `Artist/Album/Track.mp3` folder structure -- **Artist Deduplication**: Merges local and Deezer artists to avoid duplicates in search results -- **Album Enrichment**: Local albums are enriched with missing tracks from Deezer +- **Organized Library**: Downloads are saved in a clean `Artist/Album/Track` folder structure +- **Artist Deduplication**: Merges local and streaming provider artists to avoid duplicates in search results +- **Album Enrichment**: Local albums are enriched with missing tracks from streaming providers - **Cover Art Proxy**: Serves cover art for external content transparently ## Compatible Clients @@ -37,12 +39,21 @@ The name was randomly generated by GitHub when creating the repository. We found These clients are **not compatible** with octo-fiesta due to architectural limitations: -- [Symfonium](https://symfonium.app/) - Uses offline-first architecture and never queries the server for searches, making Deezer integration impossible. [See details](https://support.symfonium.app/t/suggestions-on-search-function/1121/) +- [Symfonium](https://symfonium.app/) - Uses offline-first architecture and never queries the server for searches, making streaming provider integration impossible. [See details](https://support.symfonium.app/t/suggestions-on-search-function/1121/) + +## Supported Music Providers + +- **[Deezer](https://www.deezer.com/)** - Quality: FLAC, MP3_320, MP3_128 +- **[Qobuz](https://www.qobuz.com/)** - Quality: FLAC, FLAC_24_HIGH (Hi-Res 24-bit/192kHz), FLAC_24_LOW, FLAC_16, MP3_320 + +Choose your preferred provider via the `MUSIC_SERVICE` environment variable. Additional providers may be added in future releases. ## Requirements - A running Subsonic-compatible server (developed and tested with [Navidrome](https://www.navidrome.org/)) -- A Deezer ARL token (for downloading) +- Credentials for at least one music provider: + - **Deezer**: ARL token from browser cookies + - **Qobuz**: User ID + User Auth Token from browser localStorage ([see Wiki guide](https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token))) - Docker and Docker Compose (recommended) **or** [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) for manual installation ## Quick Start (Docker) @@ -62,12 +73,17 @@ The easiest way to run Octo-Fiesta is with Docker Compose. # Path where downloaded songs will be stored on the host DOWNLOAD_PATH=./downloads - # Deezer ARL token (required) - DEEZER_ARL=your-deezer-arl-token + # Music service provider (Deezer or Qobuz) + MUSIC_SERVICE=Qobuz - # Preferred audio quality (optional): FLAC, MP3_320, MP3_128 - # If not set, the highest available quality for your account will be used - DEEZER_QUALITY= + # === Qobuz Configuration (if using Qobuz) === + QOBUZ_USER_AUTH_TOKEN=your-qobuz-token + QOBUZ_USER_ID=your-qobuz-user-id + QOBUZ_QUALITY=FLAC # FLAC, FLAC_24_HIGH, FLAC_24_LOW, FLAC_16, MP3_320 + + # === Deezer Configuration (if using Deezer) === + DEEZER_ARL=your-deezer-arl-token + DEEZER_QUALITY=FLAC # FLAC, MP3_320, MP3_128 ``` 3. **Start the container** @@ -85,40 +101,45 @@ The easiest way to run Octo-Fiesta is with Docker Compose. ## Configuration -### Subsonic Settings +### General Settings | Setting | Description | |---------|-------------| | `Subsonic:Url` | URL of your Navidrome/Subsonic server | - -### Library Settings - -| Setting | Description | -|---------|-------------| +| `Subsonic:MusicService` | Music provider to use: `Deezer` or `Qobuz` (default: `Deezer`) | | `Library:DownloadPath` | Directory where downloaded songs are stored | ### Deezer Settings | Setting | Description | |---------|-------------| -| `Deezer:Arl` | Your Deezer ARL token (required for downloads) | +| `Deezer:Arl` | Your Deezer ARL token (required if using Deezer) | | `Deezer:ArlFallback` | Backup ARL token if primary fails | | `Deezer:Quality` | Preferred audio quality: `FLAC`, `MP3_320`, `MP3_128`. If not specified, the highest available quality for your account will be used | -### Getting a Deezer ARL Token +### Qobuz Settings -1. Log in to [Deezer](https://www.deezer.com) in your browser -2. Open Developer Tools (F12) -3. Go to Application > Cookies > `https://www.deezer.com` -4. Find the `arl` cookie and copy its value +| Setting | Description | +|---------|-------------| +| `Qobuz:UserAuthToken` | Your Qobuz User Auth Token (required if using Qobuz) - [How to get it](https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token)) | +| `Qobuz:UserId` | Your Qobuz User ID (required if using Qobuz) | +| `Qobuz:Quality` | Preferred audio quality: `FLAC`, `FLAC_24_HIGH`, `FLAC_24_LOW`, `FLAC_16`, `MP3_320`. If not specified, the highest available quality will be used | -> **Note**: ARL tokens expire periodically and need to be refreshed. +### Getting Credentials + +#### Deezer ARL Token + +See the [Wiki guide](https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Deezer-Credentials-(ARL-Token)) for detailed instructions on obtaining your Deezer ARL token. + +#### Qobuz Credentials + +See the [Wiki guide](https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token)) for detailed instructions on obtaining your Qobuz User ID and User Auth Token. ## Limitations -- **Playlist Search**: Subsonic clients like Aonsoku filter playlists client-side from a cached `getPlaylists` call. Deezer playlists appear in global search (`search3`) but not in the Playlists tab filter. -- **Region Restrictions**: Some Deezer tracks may be unavailable depending on your region. -- **ARL Expiration**: Deezer ARL tokens expire and need periodic refresh. +- **Playlist Search**: Subsonic clients like Aonsoku filter playlists client-side from a cached `getPlaylists` call. Streaming provider playlists appear in global search (`search3`) but not in the Playlists tab filter. +- **Region Restrictions**: Some tracks may be unavailable depending on your region and provider. +- **Token Expiration**: Provider authentication tokens expire and need periodic refresh. ## Architecture @@ -131,9 +152,10 @@ The easiest way to run Octo-Fiesta is with Docker Compose. │ ▼ ┌─────────────────┐ - │ Deezer API │ - │ (Metadata + │ - │ Downloads) │ + │ Music Providers │ + │ - Deezer │ + │ - Qobuz │ + │ - (more...) │ └─────────────────┘ ``` @@ -158,14 +180,21 @@ If you prefer to run Octo-Fiesta without Docker: ```json { "Subsonic": { - "Url": "http://your-navidrome-server:4533" + "Url": "http://your-navidrome-server:4533", + "MusicService": "Qobuz" }, "Library": { "DownloadPath": "./downloads" }, + "Qobuz": { + "UserAuthToken": "your-qobuz-token", + "UserId": "your-qobuz-user-id", + "Quality": "FLAC" + }, "Deezer": { "Arl": "your-deezer-arl-token", - "ArlFallback": "" + "ArlFallback": "", + "Quality": "FLAC" } } ``` @@ -184,13 +213,13 @@ If you prefer to run Octo-Fiesta without Docker: ## API Endpoints -The proxy implements the Subsonic API and adds transparent Deezer integration to: +The proxy implements the Subsonic API and adds transparent streaming provider integration to: | Endpoint | Description | |----------|-------------| -| `GET /rest/search3` | Merged search results from Navidrome + Deezer | -| `GET /rest/stream` | Streams audio, downloading from Deezer if needed | -| `GET /rest/getSong` | Returns song details (local or Deezer) | +| `GET /rest/search3` | Merged search results from Navidrome + streaming provider | +| `GET /rest/stream` | Streams audio, downloading from provider if needed | +| `GET /rest/getSong` | Returns song details (local or from provider) | | `GET /rest/getAlbum` | Returns album with tracks from both sources | | `GET /rest/getArtist` | Returns artist with albums from both sources | | `GET /rest/getCoverArt` | Proxies cover art for external content | @@ -199,13 +228,13 @@ All other Subsonic API endpoints are passed through to Navidrome unchanged. ## External ID Format -External (Deezer) content uses typed IDs: +External (streaming provider) content uses typed IDs: | Type | Format | Example | |------|--------|---------| -| Song | `ext-deezer-song-{id}` | `ext-deezer-song-123456` | -| Album | `ext-deezer-album-{id}` | `ext-deezer-album-789012` | -| Artist | `ext-deezer-artist-{id}` | `ext-deezer-artist-259` | +| Song | `ext-{provider}-song-{id}` | `ext-deezer-song-123456`, `ext-qobuz-song-789012` | +| Album | `ext-{provider}-album-{id}` | `ext-deezer-album-789012`, `ext-qobuz-album-456789` | +| Artist | `ext-{provider}-artist-{id}` | `ext-deezer-artist-259`, `ext-qobuz-artist-123` | Legacy format `ext-deezer-{id}` is also supported (assumes song type). @@ -254,18 +283,22 @@ dotnet test ``` octo-fiesta/ ├── Controllers/ -│ └── SubsonicController.cs # Main API controller +│ └── SubsonicController.cs # Main API controller ├── Models/ -│ ├── MusicModels.cs # Song, Album, Artist, etc. -│ └── SubsonicSettings.cs # Configuration model +│ ├── MusicModels.cs # Song, Album, Artist, etc. +│ ├── SubsonicSettings.cs # Configuration model +│ └── QobuzSettings.cs # Qobuz configuration ├── Services/ -│ ├── DeezerDownloadService.cs # Deezer download & decryption -│ ├── DeezerMetadataService.cs # Deezer API integration -│ ├── IDownloadService.cs # Download interface -│ ├── IMusicMetadataService.cs # Metadata interface -│ └── LocalLibraryService.cs # Local file management -├── Program.cs # Application entry point -└── appsettings.json # Configuration +│ ├── DeezerDownloadService.cs # Deezer download & decryption +│ ├── DeezerMetadataService.cs # Deezer API integration +│ ├── QobuzBundleService.cs # Qobuz App ID/secret extraction +│ ├── QobuzDownloadService.cs # Qobuz download service +│ ├── QobuzMetadataService.cs # Qobuz API integration +│ ├── IDownloadService.cs # Download interface +│ ├── IMusicMetadataService.cs # Metadata interface +│ └── LocalLibraryService.cs # Local file management +├── Program.cs # Application entry point +└── appsettings.json # Configuration octo-fiesta.Tests/ ├── DeezerDownloadServiceTests.cs @@ -287,4 +320,5 @@ GPL-3.0 - [Navidrome](https://www.navidrome.org/) - The excellent self-hosted music server - [Deezer](https://www.deezer.com/) - Music streaming service +- [Qobuz](https://www.qobuz.com/) - Hi-Res music streaming service - [Subsonic API](http://www.subsonic.org/pages/api.jsp) - The API specification