mirror of
https://github.com/SoPat712/allstarr.git
synced 2026-02-09 23:55:10 -05:00
docs: reorganize README, add Docker quick start and tested clients
This commit is contained in:
V1ck3s
150
README.md
150
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
|
||||
|
||||
Reference in New Issue
Block a user