Octo-Fiesta proxies your Subsonic clients to a streaming provider and back
A Subsonic API proxy server that transparently integrates multiple music streaming providers as sources.
At a glance
- What is it?
- Octo-Fiesta is a .NET proxy that sits between a Subsonic client and Navidrome, fetches a track from a streaming provider when the local library does not have it, downloads it and files it into the library as Artist, Album and Track folders. It is GPL-3.0, it ships as a container image, and its own documentation lists the Subsonic API limits and expiring tokens as the things that will bite you.
- Who is it for?
- Adopt Octo-Fiesta if you run Navidrome and want your existing Subsonic clients to fall back to a streaming provider you pay for, with downloads kept locally so the second listen is instant. Do not adopt it if you need playlists to behave like first-class objects in every client, or if you cannot maintain provider credentials, since tokens expire and the README states they need periodic refreshing.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly C#, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 22, 2026, and from our analysis. They are not legal advice.
Editorial analysis
A proxy that fills the gaps in your Navidrome library
Octo-Fiesta is a Subsonic API proxy server that transparently integrates multiple music streaming providers as sources. The workflow it describes is the whole idea in one sentence: 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, and then added to your library so it is available locally for future listens.
The architecture diagram in the README shows the shape. A Subsonic client talks to Octo-Fiesta, Octo-Fiesta talks to the Navidrome server, and the proxy also reaches out to the music providers, which are Deezer, Qobuz, Tidal and Yandex in the diagram.
What that means for a user is that no client needs to know the proxy exists. You point Aonsoku, Feishin, Supersonic, Subplayer or Aurial on the desktop, or Navic, Tempus, Substreamer, Yuzic or Wavio on Android, or Navic, Narjo, BeatsX or Yuzic on iOS, at the proxy, and the client keeps talking the Subsonic protocol it already speaks.
The library side is where the design pays off. A track fetched once is written into your library, so the second play of the same song is a local file. The README describes the storage as clean Artist, Album and Track folder structure, with full ID3 tags and embedded cover art.
The project is C#, the default branch is dev, and the licence is GPL-3.0. The last push to the default branch was on 2026-10-15, and the release history shows v0.9 on 2026-05-15, v0.10 on 2026-06-20 and v0.11 on 2026-09-02.
Docker: five commands and a proxy on port 5274
The quick start assumes you already have a Navidrome server, or another Subsonic-compatible server, running. Beyond that you need either Docker with Docker Compose, which the README recommends, or the .NET 9.0 SDK.
# Clone the repository
git clone https://github.com/V1ck3s/octo-fiesta.git
cd octo-fiesta
# Configure
cp .env.example .env
nano .env # Edit with your settings
# Start
docker-compose up -dThe proxy is then available at http://localhost:5274, and the instruction is to point your Subsonic client at that URL instead of your Navidrome server.
The compose file explains the port mapping. The container is published on port 5274 and maps to an internal port that defaults to 8080, so the port on the host stays fixed while the internal one is configurable:
ports:
- "5274:${INTERNAL_PORT:-8080}"
environment:
- ASPNETCORE_URLS=http://+:${INTERNAL_PORT:-8080}
- Library__DownloadPath=/app/downloadsThe image is ghcr.io/v1ck3s/octo-fiesta, and the Dockerfile shows a two stage build: a .NET SDK 9.0 stage that restores, copies the solution and publishes the project in Release configuration with a version argument, and a runtime stage on the ASP.NET 9.0 image that exposes 8080 and starts the application with dotnet octo-fiesta.dll.
The composition of settings is a visible pattern: everything is an environment variable, and the ASP.NET convention of separating nested option names with a a double separator maps them onto a settings tree, which is why you see Subsonic__MusicService rather than a flat MUSICAL_SERVICE key.
Providers, storage mode and the explicit filter
The configuration file .env.example is the reference for every setting, and the environment names make the options legible.
The music service is chosen with MUSIC_SERVICE, defaulting to Deezer, with the accepted values Deezer, Qobuz, Tidal, Yandex, or the deprecated SquidWTF. The Subsonic side points at your server with SUBSONIC_URL, defaulting to http://localhost:4533, which is Navidrome's default port, and there are optional admin credentials, SUBSONIC_ADMIN_USERNAME and SUBSONIC_ADMIN_PASSWORD, for the operations that need admin permissions.
The storage mode is the setting with the largest consequence. It is Permanent by default, which saves downloads to your library, or Cache, which is temporary with automatic cleanup. In cache mode there is a CACHE_DURATION_HOURS value that defaults to 1, so a cached track is removed an hour later unless you change it.
Two more settings shape what arrives. EnableExternalPlaylists turns the external playlist search and download on by default, with the M3U files written to a directory named by PLAYLISTS_DIRECTORY, default playlists. ExplicitFilter accepts All, ExplicitOnly or CleanOnly and defaults to All, which is the setting to reach for if you are building a family library.
The .env file also carries the download path on the host, DOWNLOAD_PATH, which applies only when the storage mode is Permanent, and per provider download paths, such as DEEZER_DOWNLOAD_PATH, for splitting sources onto separate volumes.
Credentials are account tokens, and one provider is on its way out
Each provider authenticates with a token taken from your own account, and the README links a wiki page for each one.
For Deezer, the credential is an ARL token, with a DEEZER_ARL variable and an optional DEEZER_ARL_FALLBACK for a second token. The preferred quality is set with DEEZER_QUALITY, accepting FLAC, MP3_320 or MP3_128, and if you leave it empty the highest quality available for your account is used.
For Qobuz you need a user authentication token and a user ID, QOBUZ_USER_AUTH_TOKEN and QOBUZ_USER_ID, both described as obtainable from the browser after logging in to play.qobuz.com. The quality list is wider here: FLAC, FLAC_24_HIGH, FLAC_24_LOW, FLAC_16 or MP3_320.
Tidal uses OAuth tokens, and Yandex credentials come from authorising the official Yandex Music OAuth client, after which the token appears in the address bar in the access_token fragment.
The table of supported providers records the quality ceiling and the playlist support per service, with Deezer and Yandex at FLAC 16-bit and Qobuz and Tidal at FLAC 24-bit and 192kHz. The README also states hi-res support up to 24-bit and 192kHz as a feature of the project.
SquidWTF is the entry that shows how fragile this layer is. The README marks it deprecated, explains that the upstream squid.wtf music services are down, that the Qobuz backend no longer resolves, that public Tidal instances only serve search results and 30-second previews, and that the Amazon Music and Deemix backends have been removed. It is kept for users running a self-hosted Tidal instance and may be removed in a future release.
Playlists, lyrics and metadata come along for the ride
The features beyond plain fetching are what separate this from a thin download helper.
External playlist support covers search, discovery and download of playlists with automatic M3U generation, so a playlist found on a provider ends up as a file on disk that your client can read.
Synced lyrics are time-synced and come from LRCLIB, fetched through the OpenSubsonic getLyricsBySongId call. The README says they are shown on the very first listen and saved as .lrc sidecars for downloaded files, which is the right design: the lyric is available immediately for a track that has never been downloaded, and stored next to the file for later.
Metadata handling covers full ID3 tags and embedded cover art, and downloads are organised into Artist, Album and Track folders, which matters because that structure is what Navidrome uses to make a track appear in the right place.
The multi-provider architecture is described as pluggable, so a music service is a component behind a common interface rather than a branch in the request handling. The consequence for you is that adding a provider is an implementation task in the same project, not a configuration change, and the deprecated SquidWTF entry shows both what that interface costs when an upstream disappears and why the native Tidal provider exists alongside it.
The Subsonic API limits what the proxy can show you
The Limitations section in the README is short and specific, and it is the part to read before you build a workflow around playlists.
Playlist search has a wrinkle: streaming provider playlists appear in global search but may not show in the Playlists tab, because of client side filtering in the client application. Playlist display is constrained by the Subsonic API itself, so playlists appear at the end of the album list with a music note icon rather than as their own objects, and the wiki has a page explaining this.
The third limitation is operational: provider authentication tokens expire and need periodic refresh. That is the price of the design. Octo-Fiesta does not ask a provider to authorise the user in the browser at runtime, it takes a token the user obtained and reuses it, so the token's lifetime is the account's lifetime, and something has to refresh it.
A fourth limitation is the one the SquidWTF deprecation documents. This whole approach depends on services whose terms, availability and technical shape are outside the project's control. A proxy can insulate you from the Subsonic API's shape, but it cannot insulate you from a provider changing its API, and the removal of the Amazon Music and Deemix backends shows what happens when that happens.
GPL-3.0, prebuilt images and the client list
The licence is GPL-3.0, with a LICENSE file in the repository. For a server that sits between your client and your music account, that matters if you plan to run a modified version as a service, since GPL obligations attach to distributing modified versions.
Distribution is straightforward, because a prebuilt image is published to the GitHub Container Registry as ghcr.io/v1ck3s/octo-fiesta, and the compose file references it directly. Building from source needs the .NET 9.0 SDK, since the Dockerfile restores and publishes the solution, and there is a separate octo-fiesta.Tests project alongside the main one, with a solution file tying them together.
The client list in the README is long enough to be useful, and it is worth checking against your own client before you deploy. The desktop entries are Aonsoku, Feishin, Supersonic, Subplayer and Aurial. Android has Navic, Tempus, Substreamer, Yuzic and Wavio. iOS has Navic, Narjo, BeatsX and Yuzic. The wiki page on compatible clients also lists the ones that do not work, which is the more useful half of that information.
One last practical note for a self-hosted setup: the README mentions that folders created by another account, or by an agent running in a sandbox, can carry permissions that stop the service from reading them, and the fix is to grant access through the folder's security settings rather than to loosen the whole mount.
Editorial conclusion
Adopt Octo-Fiesta if you run Navidrome and want your existing Subsonic clients to fall back to a streaming provider you pay for, with downloads kept locally so the second listen is instant. Do not adopt it if you need playlists to behave like first-class objects in every client, or if you cannot maintain provider credentials, since tokens expire and the README states they need periodic refreshing. Before you start, read the Limitations section of the README, because the Subsonic API constraints are documented there, and set STORAGE_MODE deliberately, since Permanent writes into your library while Cache keeps files temporarily and cleans them up after the configured number of hours.
Frequently asked questions
What does Octo-Fiesta do with my Subsonic client?
It proxies it. The client keeps speaking the Subsonic protocol to Octo-Fiesta, which forwards requests to Navidrome and, when a track is missing from the local library, fetches it from the configured streaming provider, downloads it and serves it to the client.
How do I install Octo-Fiesta with Docker?
Clone the repository, copy .env.example to .env, fill in your settings, and run docker-compose up -d. The proxy is then available at http://localhost:5274, and you point your Subsonic client at that URL instead of your Navidrome server.
Which streaming providers does Octo-Fiesta support?
Deezer as the default, Qobuz, Tidal and Yandex Music, each needing account credentials, plus the deprecated SquidWTF entry which is kept for self-hosted Tidal users. Deezer and Yandex cap at FLAC 16-bit, while Qobuz and Tidal reach FLAC 24-bit and 192kHz.
What are the limitations of Octo-Fiesta?
Provider playlists may not appear in the Playlists tab because of client side filtering, and the Subsonic API forces playlists to show at the end of the album list with a music note icon. Provider tokens expire and need periodic refresh, and the SquidWTF provider is deprecated because its upstream services are down.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/v1ck3s-octo-fiesta)