159 lines
12 KiB
Plaintext
159 lines
12 KiB
Plaintext
|
<div id="readability-page-1" class="page"><div data-hpc="true"><article>
|
||
|
|
<p dir="auto">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.</p>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Why "Octo-Fiesta"?</h2><a id="user-content-why-octo-fiesta" aria-label="Permalink: Why "Octo-Fiesta"?" href="#why-octo-fiesta"></a><p></p>
|
||
|
|
<p dir="auto">The name was randomly generated by GitHub when creating the repository. We found it amusing and somewhat fitting for a music application. After all, "fiesta" evokes a party atmosphere, which goes well with music streaming. So we kept it!</p>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Features</h2><a id="user-content-features" aria-label="Permalink: Features" href="#features"></a><p></p>
|
||
|
|
<ul dir="auto">
|
||
|
|
<li><strong>Multi-Provider Architecture</strong>: Pluggable music service system supporting multiple streaming providers</li>
|
||
|
|
<li><strong>Transparent Proxy</strong>: Acts as a middleware between Subsonic clients and your Navidrome server</li>
|
||
|
|
<li><strong>Seamless Integration</strong>: Automatically searches and streams music from your configured provider when not available locally</li>
|
||
|
|
<li><strong>Automatic Downloads</strong>: Songs are downloaded on-the-fly and cached for future use</li>
|
||
|
|
<li><strong>External Playlist Support</strong>: Search, discover, and download playlists with automatic M3U generation</li>
|
||
|
|
<li><strong>Hi-Res Audio Support</strong>: Up to 24-bit/192kHz FLAC quality</li>
|
||
|
|
<li><strong>Full Metadata Embedding</strong>: Complete ID3 tags and embedded cover art</li>
|
||
|
|
<li><strong>Organized Library</strong>: Downloads saved in clean <code>Artist/Album/Track</code> folder structure</li>
|
||
|
|
</ul>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Supported Music Providers</h2><a id="user-content-supported-music-providers" aria-label="Permalink: Supported Music Providers" href="#supported-music-providers"></a><p></p>
|
||
|
|
<table>
|
||
|
|
<thead>
|
||
|
|
<tr>
|
||
|
|
<th>Provider</th>
|
||
|
|
<th>Credentials Required</th>
|
||
|
|
<th>Max Quality</th>
|
||
|
|
<th>Playlist Support</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<td><a href="https://squid.wtf/" rel="nofollow">SquidWTF</a></td>
|
||
|
|
<td>No</td>
|
||
|
|
<td>FLAC 24-bit</td>
|
||
|
|
<td>No</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><a href="https://www.qobuz.com/" rel="nofollow">Qobuz</a></td>
|
||
|
|
<td>Yes</td>
|
||
|
|
<td>FLAC 24-bit/192kHz</td>
|
||
|
|
<td>Yes</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><a href="https://www.deezer.com/" rel="nofollow">Deezer</a></td>
|
||
|
|
<td>Yes</td>
|
||
|
|
<td>FLAC 16-bit</td>
|
||
|
|
<td>Yes</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><a href="https://music.yandex.ru/" rel="nofollow">Yandex Music</a></td>
|
||
|
|
<td>Yes</td>
|
||
|
|
<td>FLAC 16-bit</td>
|
||
|
|
<td>Yes</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
<p dir="auto">See the <a href="https://github.com/V1ck3s/octo-fiesta/wiki/Supported-Music-Providers">Supported Music Providers</a> wiki page for detailed information.</p>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Compatible Clients</h2><a id="user-content-compatible-clients" aria-label="Permalink: Compatible Clients" href="#compatible-clients"></a><p></p>
|
||
|
|
<table>
|
||
|
|
<thead>
|
||
|
|
<tr>
|
||
|
|
<th>Platform</th>
|
||
|
|
<th>Clients</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody>
|
||
|
|
<tr>
|
||
|
|
<td><strong>Desktop</strong></td>
|
||
|
|
<td><a href="https://github.com/victoralvesf/aonsoku">Aonsoku</a>, <a href="https://github.com/jeffvli/feishin">Feishin</a>, <a href="https://github.com/dweymouth/supersonic">Supersonic</a>, <a href="https://github.com/peguerosdc/subplayer">Subplayer</a>, <a href="https://github.com/shrimpza/aurial">Aurial</a></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><strong>Android</strong></td>
|
||
|
|
<td><a href="https://github.com/paigely/Navic">Navic</a>, <a href="https://github.com/eddyizm/tempus">Tempus</a>, <a href="https://substreamerapp.com/" rel="nofollow">Substreamer</a>, <a href="https://github.com/eftpmc/yuzic">Yuzic</a></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td><strong>iOS</strong></td>
|
||
|
|
<td><a href="https://github.com/paigely/Navic">Navic</a>, <a href="https://www.reddit.com/r/NarjoApp/" rel="nofollow">Narjo</a>, <a href="https://apps.apple.com/fr/app/beatsx/id6745130542" rel="nofollow">BeatsX</a>, <a href="https://github.com/eftpmc/yuzic">Yuzic</a></td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
<p dir="auto">See the <a href="https://github.com/V1ck3s/octo-fiesta/wiki/Compatible-Clients">Compatible Clients</a> wiki page for details and incompatible clients.</p>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Quick Start</h2><a id="user-content-quick-start" aria-label="Permalink: Quick Start" href="#quick-start"></a><p></p>
|
||
|
|
<p dir="auto"></p><h3 tabindex="-1" dir="auto">Requirements</h3><a id="user-content-requirements" aria-label="Permalink: Requirements" href="#requirements"></a><p></p>
|
||
|
|
<ul dir="auto">
|
||
|
|
<li>A running <a href="https://www.navidrome.org/" rel="nofollow">Navidrome</a> server (or other Subsonic-compatible server)</li>
|
||
|
|
<li>Docker and Docker Compose (recommended) or <a href="https://dotnet.microsoft.com/download/dotnet/9.0" rel="nofollow">.NET 9.0 SDK</a></li>
|
||
|
|
</ul>
|
||
|
|
<p dir="auto"></p><h3 tabindex="-1" dir="auto">Docker Installation</h3><a id="user-content-docker-installation" aria-label="Permalink: Docker Installation" href="#docker-installation"></a><p></p>
|
||
|
|
<div dir="auto"><pre><span><span>#</span> Clone the repository</span>
|
||
|
|
git clone https://github.com/V1ck3s/octo-fiesta.git
|
||
|
|
<span>cd</span> octo-fiesta
|
||
|
|
|
||
|
|
<span><span>#</span> Configure</span>
|
||
|
|
cp .env.example .env
|
||
|
|
nano .env <span><span>#</span> Edit with your settings</span>
|
||
|
|
|
||
|
|
<span><span>#</span> Start</span>
|
||
|
|
docker-compose up -d</pre></div>
|
||
|
|
<p dir="auto">The proxy will be available at <code>http://localhost:5274</code>. Point your Subsonic client to this URL instead of your Navidrome server.</p>
|
||
|
|
<p dir="auto">See the <a href="https://github.com/V1ck3s/octo-fiesta/wiki/Installation">Installation</a> wiki page for detailed instructions including manual installation.</p>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Configuration</h2><a id="user-content-configuration" aria-label="Permalink: Configuration" href="#configuration"></a><p></p>
|
||
|
|
<p dir="auto">See the <a href="https://github.com/V1ck3s/octo-fiesta/wiki/Configuration">Configuration</a> wiki page for all available settings.</p>
|
||
|
|
<p dir="auto"></p><h3 tabindex="-1" dir="auto">Getting Credentials</h3><a id="user-content-getting-credentials" aria-label="Permalink: Getting Credentials" href="#getting-credentials"></a><p></p>
|
||
|
|
<ul dir="auto">
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Deezer-Credentials-(ARL-Token)">Getting Deezer Credentials (ARL Token)</a></li>
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/Getting-Qobuz-Credentials-(User-ID-&-Token)">Getting Qobuz Credentials (User ID & Token)</a></li>
|
||
|
|
<li><strong>SquidWTF</strong>: No credentials needed!</li>
|
||
|
|
<li><strong>Yandex</strong>: credentials may be obtained by authorizing official Yandex Music OAuth client <a href="https://oauth.yandex.ru/authorize?response_type=token&client_id=23cabbbdc6cd418abb4b39c32c41195d" rel="nofollow">here</a>. After authorization OAuth token will appear in the address bar in <code>#access_token=</code> fragment</li>
|
||
|
|
</ul>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Architecture</h2><a id="user-content-architecture" aria-label="Permalink: Architecture" href="#architecture"></a><p></p>
|
||
|
|
<div><pre><code>┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||
|
|
│ Subsonic │────▶│ Octo-Fiesta │────▶│ Navidrome │
|
||
|
|
│ Client │◀────│ (Proxy) │◀────│ Server │
|
||
|
|
│ (Aonsoku) │ │ │ │ │
|
||
|
|
└─────────────────┘ └────────┬─────────┘ └─────────────────┘
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
┌─────────────────┐
|
||
|
|
│ Music Providers │
|
||
|
|
│ - Deezer │
|
||
|
|
│ - Qobuz │
|
||
|
|
│ - SquidWTF │
|
||
|
|
└─────────────────┘
|
||
|
|
</code></pre></div>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Limitations</h2><a id="user-content-limitations" aria-label="Permalink: Limitations" href="#limitations"></a><p></p>
|
||
|
|
<ul dir="auto">
|
||
|
|
<li><strong>Playlist Search</strong>: Streaming provider playlists appear in global search but may not show in the Playlists tab due to client-side filtering.</li>
|
||
|
|
<li><strong>Playlist Display</strong>: Due to Subsonic API limitations, playlists appear at the end of the album list with a music note icon. See <a href="https://github.com/V1ck3s/octo-fiesta/wiki/Playlists">Playlists</a> for details.</li>
|
||
|
|
<li><strong>Token Expiration</strong>: Provider authentication tokens expire and need periodic refresh.</li>
|
||
|
|
</ul>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Documentation</h2><a id="user-content-documentation" aria-label="Permalink: Documentation" href="#documentation"></a><p></p>
|
||
|
|
<p dir="auto">Full documentation is available in the <a href="https://github.com/V1ck3s/octo-fiesta/wiki">Wiki</a>:</p>
|
||
|
|
<ul dir="auto">
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/Installation">Installation</a></li>
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/Configuration">Configuration</a></li>
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/Compatible-Clients">Compatible Clients</a></li>
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/Supported-Music-Providers">Supported Music Providers</a></li>
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/Playlists">Playlists</a></li>
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/API-Endpoints">API Endpoints</a></li>
|
||
|
|
<li><a href="https://github.com/V1ck3s/octo-fiesta/wiki/Development-and-Contributing">Development & Contributing</a></li>
|
||
|
|
</ul>
|
||
|
|
<blockquote>
|
||
|
|
<p dir="auto"><strong>Need help?</strong> Please check the <a href="https://github.com/V1ck3s/octo-fiesta/wiki">Wiki</a> before opening an issue.</p>
|
||
|
|
</blockquote>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Contributing</h2><a id="user-content-contributing" aria-label="Permalink: Contributing" href="#contributing"></a><p></p>
|
||
|
|
<p dir="auto">Contributions are welcome! See the <a href="https://github.com/V1ck3s/octo-fiesta/wiki/Development-and-Contributing">Development & Contributing</a> guide.</p>
|
||
|
|
<div dir="auto"><pre><span><span>#</span> Build</span>
|
||
|
|
dotnet build
|
||
|
|
|
||
|
|
<span><span>#</span> Run tests</span>
|
||
|
|
dotnet <span>test</span></pre></div>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">License</h2><a id="user-content-license" aria-label="Permalink: License" href="#license"></a><p></p>
|
||
|
|
<p dir="auto">GPL-3.0</p>
|
||
|
|
<p dir="auto"></p><h2 tabindex="-1" dir="auto">Acknowledgments</h2><a id="user-content-acknowledgments" aria-label="Permalink: Acknowledgments" href="#acknowledgments"></a><p></p>
|
||
|
|
<ul dir="auto">
|
||
|
|
<li><a href="https://www.navidrome.org/" rel="nofollow">Navidrome</a> - The excellent self-hosted music server</li>
|
||
|
|
<li><a href="https://www.deezer.com/" rel="nofollow">Deezer</a> - Music streaming service</li>
|
||
|
|
<li><a href="https://www.qobuz.com/" rel="nofollow">Qobuz</a> - Hi-Res music streaming service</li>
|
||
|
|
<li><a href="https://squid.wtf/" rel="nofollow">SquidWTF</a> - Third-party music API service</li>
|
||
|
|
<li><a href="https://music.yandex.com/" rel="nofollow">Yandex Music</a> - Music streaming service</li>
|
||
|
|
<li><a href="http://www.subsonic.org/pages/api.jsp" rel="nofollow">Subsonic API</a> - The API specification</li>
|
||
|
|
</ul>
|
||
|
|
</article></div></div>
|