joshpatra/allstarr
1
0
Fork 0
mirror of https://github.com/SoPat712/allstarr.git synced 2026-02-09 23:55:10 -05:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: update README for multi-provider architecture

Browse Source
This commit is contained in:
V1ck3s
2026-01-08 00:13:01 +01:00
parent 275467c5bf
commit 651b86694d
1 changed files with 85 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
README.md
View File

@@ -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