From 1bf3e17d78a03990a360387dc621fb5351c0174b Mon Sep 17 00:00:00 2001
From: V1ck3s <contact@vickes.fr>
Date: Thu, 15 Jan 2026 23:27:11 +0100
Subject: [PATCH] docs: add external playlists feature documentation

---
 .env.example |  9 +++++++++
 README.md    | 39 +++++++++++++++++++++++++++++++++++++--
 2 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/.env.example b/.env.example
index 6b2dd89..2f4d90a 100644
--- a/.env.example
+++ b/.env.example
@@ -34,6 +34,15 @@ QOBUZ_USER_ID=
 QOBUZ_QUALITY=
 
 # ===== GENERAL SETTINGS =====
+# External playlists support (optional, default: true)
+# When enabled, allows searching and downloading playlists from Deezer/Qobuz
+# Starring a playlist triggers automatic download of all tracks and creates an M3U file
+ENABLE_EXTERNAL_PLAYLISTS=true
+
+# Playlists directory name (optional, default: playlists)
+# M3U playlist files will be created in {DOWNLOAD_PATH}/{PLAYLISTS_DIRECTORY}/
+PLAYLISTS_DIRECTORY=playlists
+
 # Explicit content filter (optional, default: All)
 # - All: Show all tracks (no filtering)
 # - ExplicitOnly: Exclude clean/edited versions, keep original explicit content
diff --git a/README.md b/README.md
index 70e5b31..0038683 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ The name was randomly generated by GitHub when creating the repository. We found
 - **Transparent Proxy**: Acts as a middleware between Subsonic clients (like Aonsoku, Sublime Music, etc.) and your Navidrome server
 - **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
+- **External Playlist Support**: Search, discover, and download playlists from Deezer and Qobuz with automatic M3U generation
 - **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` folder structure
@@ -80,6 +81,10 @@ The easiest way to run Octo-Fiesta is with Docker Compose.
    # Music service provider (Deezer or Qobuz)
    MUSIC_SERVICE=Qobuz
    
+   # === External Playlists (optional) ===
+   ENABLE_EXTERNAL_PLAYLISTS=true  # Enable/disable playlist support (default: true)
+   PLAYLISTS_DIRECTORY=playlists    # Directory name for M3U files (default: playlists)
+   
    # === Qobuz Configuration (if using Qobuz) ===
    QOBUZ_USER_AUTH_TOKEN=your-qobuz-token
    QOBUZ_USER_ID=your-qobuz-user-id
@@ -129,6 +134,29 @@ The easiest way to run Octo-Fiesta is with Docker Compose.
 | `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 |
 
+### External Playlists
+
+Octo-Fiesta supports discovering and downloading playlists from your streaming providers (Deezer and Qobuz).
+
+| Setting | Description |
+|---------|-------------|
+| `Subsonic:EnableExternalPlaylists` | Enable/disable external playlist support (default: `true`) |
+| `Subsonic:PlaylistsDirectory` | Directory name where M3U playlist files are created (default: `playlists`) |
+
+**How it works:**
+1. Search for playlists from Deezer or Qobuz using the global search in your Subsonic client
+2. When you "star" (favorite) a playlist, Octo-Fiesta automatically downloads all tracks
+3. An M3U playlist file is created in `{DownloadPath}/playlists/` with relative paths to downloaded tracks
+4. Individual tracks are added to the M3U as they are played or downloaded
+
+**Environment variable:**
+```bash
+# To disable playlists
+Subsonic__EnableExternalPlaylists=false
+```
+
+> **Note**: Due to client-side filtering, playlists from streaming providers may not appear in the "Playlists" tab of some clients, but will show up in global search results.
+
 ### Getting Credentials
 
 #### Deezer ARL Token
@@ -221,12 +249,13 @@ The proxy implements the Subsonic API and adds transparent streaming provider in
 
 | Endpoint | Description |
 |----------|-------------|
-| `GET /rest/search3` | Merged search results from Navidrome + streaming provider |
+| `GET /rest/search3` | Merged search results from Navidrome + streaming provider (including playlists) |
 | `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 |
+| `GET /rest/star` | Stars items; triggers automatic playlist download for external playlists |
 
 All other Subsonic API endpoints are passed through to Navidrome unchanged.
 
@@ -254,10 +283,16 @@ downloads/
 │   │   └── ...
 │   └── Another Album/
 │       └── ...
-└── Another Artist/
+├── Another Artist/
+│   └── ...
+└── playlists/
+    ├── My Favorite Songs.m3u
+    ├── Chill Vibes.m3u
     └── ...
 ```
 
+Playlists are stored as M3U files with relative paths to downloaded tracks, making them portable and compatible with most music players.
+
 ## Metadata Embedding
 
 Downloaded files include: