From ba2aa98a23ba2044e26accb9e052bcbd1fb18440 Mon Sep 17 00:00:00 2001 From: V1ck3s Date: Fri, 2 Jan 2026 17:31:20 +0100 Subject: [PATCH] docs: reorganize README, add Docker quick start and tested clients --- .env.example | 12 +++++ README.md | 150 ++++++++++++++++++++++++++++++++------------------- 2 files changed, 107 insertions(+), 55 deletions(-) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..87fca43 --- /dev/null +++ b/.env.example @@ -0,0 +1,12 @@ +# Navidrome/Subsonic server URL +SUBSONIC_URL=http://localhost:4533 + +# Path where downloaded songs will be stored on the host +DOWNLOAD_PATH=./downloads + +# Deezer ARL token (required) +# See README.md for instructions on how to get this token +DEEZER_ARL=your-deezer-arl-token + +# Fallback ARL token (optional) +DEEZER_ARL_FALLBACK= diff --git a/README.md b/README.md index d8ca453..fed88b5 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. +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. ## Why "Octo-Fiesta"? @@ -17,6 +17,98 @@ The name was randomly generated by GitHub when creating the repository. We found - **Album Enrichment**: Local albums are enriched with missing tracks from Deezer - **Cover Art Proxy**: Serves cover art for external content transparently +## Tested Clients + +### PC + +- [Aonsoku](https://github.com/victoralvesf/aonsoku) +- [Subplayer](https://github.com/peguerosdc/subplayer) +- [Aurial](https://github.com/shrimpza/aurial) + +### Android + +- [Tempus](https://github.com/eddyizm/tempus) +- [Symfonium](https://symfonium.app/) (works as a standard Subsonic client, but Octo-Fiesta specific features like Deezer search are not supported) +- [Chora](https://github.com/CraftWorksMC/Chora) (works as a standard Subsonic client, but Octo-Fiesta specific features like Deezer search are not supported) + +> **Want to improve client compatibility?** Pull requests are welcome! + +## Requirements + +- A running Subsonic-compatible server (developed and tested with [Navidrome](https://www.navidrome.org/)) +- A Deezer ARL token (for downloading) +- Docker and Docker Compose (recommended) **or** [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) for manual installation + +## Quick Start (Docker) + +The easiest way to run Octo-Fiesta is with Docker Compose. + +1. **Create your environment file** + ```bash + cp .env.example .env + ``` + +2. **Edit the `.env` file** with your configuration: + ```bash + # Navidrome/Subsonic server URL + SUBSONIC_URL=http://your-navidrome-server:4533 + + # Path where downloaded songs will be stored on the host + DOWNLOAD_PATH=./downloads + + # Deezer ARL token (required) + DEEZER_ARL=your-deezer-arl-token + ``` + +3. **Start the container** + ```bash + docker-compose up -d + ``` + + The proxy will be available at `http://localhost:5274`. + +4. **Configure your Subsonic client** + + Point your Subsonic client to `http://localhost:5274` instead of your Navidrome server directly. + +> **Tip**: Make sure the `DOWNLOAD_PATH` points to a directory that Navidrome can scan, so downloaded songs appear in your library. + +## Configuration + +### Subsonic Settings + +| Setting | Description | +|---------|-------------| +| `Subsonic:Url` | URL of your Navidrome/Subsonic server | + +### Library Settings + +| Setting | Description | +|---------|-------------| +| `Library:DownloadPath` | Directory where downloaded songs are stored | + +### Deezer Settings + +| Setting | Description | +|---------|-------------| +| `Deezer:Arl` | Your Deezer ARL token (required for downloads) | +| `Deezer:ArlFallback` | Backup ARL token if primary fails | + +### Getting a Deezer ARL Token + +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 + +> **Note**: ARL tokens expire periodically and need to be refreshed. + +## 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. + ## Architecture ``` @@ -34,13 +126,9 @@ The name was randomly generated by GitHub when creating the repository. We found └─────────────────┘ ``` -## Requirements +## Manual Installation -- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) -- A running [Navidrome](https://www.navidrome.org/) server -- A Deezer ARL token (for downloading) - -## Installation +If you prefer to run Octo-Fiesta without Docker: 1. **Clone the repository** ```bash @@ -83,36 +171,6 @@ The name was randomly generated by GitHub when creating the repository. We found Point your Subsonic client to `http://localhost:5274` instead of your Navidrome server directly. -## Configuration - -### Subsonic Settings - -| Setting | Description | -|---------|-------------| -| `Subsonic:Url` | URL of your Navidrome/Subsonic server | - -### Library Settings - -| Setting | Description | -|---------|-------------| -| `Library:DownloadPath` | Directory where downloaded songs are stored | - -### Deezer Settings - -| Setting | Description | -|---------|-------------| -| `Deezer:Arl` | Your Deezer ARL token (required for downloads) | -| `Deezer:ArlFallback` | Backup ARL token if primary fails | - -### Getting a Deezer ARL Token - -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 - -> **Note**: ARL tokens expire periodically and need to be refreshed. - ## API Endpoints The proxy implements the Subsonic API and adds transparent Deezer integration to: @@ -210,24 +268,6 @@ octo-fiesta.Tests/ - **TagLibSharp** - ID3 tag and cover art embedding - **Swashbuckle.AspNetCore** - Swagger/OpenAPI documentation -## Tested Clients - -### PC - -- [Aonsoku](https://github.com/victoralvesf/aonsoku) -- [Subplayer](https://github.com/peguerosdc/subplayer) -- [Aurial](https://github.com/shrimpza/aurial) - -### Android - -- [Symfonium](https://symfonium.app/) (works as a standard Subsonic client, but Octo-Fiesta specific features like Deezer search are not supported) - -## 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. - ## License MIT