note (Aug 31, 2026): at this moment i would not recommend making PRs that interface with the backend, as i've been working on a prototype that allows for logging into multiple OpenSubsonic sources at once, which contains major rewrites to the backend. i'm unsure if i'll actually end up releasing that, as it's definitely not ready for production yet, and i'm unsure if this is a feature anyone actually wants or needs... but just an FYI for any contributors!
tinysub #
tinysub is a simple web-based audio player for OpenSubsonic servers (Navidrome, Gonic, Ampache, etc). it's written in Svelte, aiming to be very performant and lightweight while still offering all the features you'd expect.
a general summary of tinysub and it's features are listed on the website.
for discussion, use the issue tracker or feel free to join my Discord 😃
using #
you can use my hosted build of tinysub at tinysub.devins.page.
tinysub is primarily tested on Chromium during development, but any other modern browser should work fine! tinysub's build target is Baseline Widely Available. if you have any browser-specific issues let me know.
you will need to have access to an OpenSubsonic server to use this app of course, as it is an OpenSubsonic client, not a local music player. there exist many guides to get one set up. i personally use Navidrome.
if you just want to try it out, you could try Navidrome's demo server! enter https://demo.navidrome.org for the server url, and enter demo for the username and password. this is a good way to get a feel for how the app works.
deploying #
i always host the latest copy of tinysub at tinysub.devins.page, but you can self-host it too!
if you would like to customize your build, such as adding a prefilled server URL, see .env.example.
the normal way #
tinysub is just a simple Vite project. to build it, run npm install and npm run build. the output will appear in dist. after building, simply serve the output with a web server like Caddy, Nginx, Apache, etc...
important: it is recommended that you ensure your server is configured properly for the Vite PWA plugin, or else app updates may not work!
the declarative way #
if you're using NixOS/nix-darwin/Nix, i also offer a very simple Nix package in this project's flake. you can import that package into your flake and then hook it up to a web server.
this module in my personal flake is the entire Caddy configuration of tinysub.devins.page, if you're curious and need an example.
frequently asked questions #
i can't log in! #
Firefox and Safari do not allow mixed http/https. if you are trying to connect to your server with http rather than https, it may not work out of the box on non-Chromium-based browsers... you likely need to serve your Subsonic server on https. use Tailscale? consider trying out Tailscale Serve, which handles https automatically!
mobile support? #
tinysub does work on mobile, but it's not a priority. you may experience some weird mobile UX issues... looking for alternative clients for mobile devices? on iOS, i heavily recommend Arpeggi or Amperfy. on Android, i've heard Navic or Symfonium are great.
Jellyfin/Plex support? #
not planned, this client is built around the OpenSubsonic API and supporting other media servers would add a lot of unnecessary complexity to the codebase and would be more difficult to maintain. besides, i personally think OpenSubsonic is a much better suit for a music server.
credits #
- OpenSubsonic API and it's contributors
- Svelte's maintainers for making such a wonderful framework to work with
- Vite's maintainers for making such a wonderful build tool to work with
- Virtua for the virtual scrolling implementation used in the library and queue
- Floating UI for the floating things
- Color Thief for the color extraction utility used for the "Dynamic Colors" feature
- glur for pure-JS gaussian blur impl, used in the background art for performance reasons (#112)
- Heroicons, Lucide, and famfamfam-silk-svg are used as selectable icon packs
- Strawberry Music Player was a major inspiration for this project's UX (if you want something non web-based, check it out!)
- ampcast was another major inspiration for this project
you can see everything else this project depends on in package.json 😃
OpenSubsonic extensions #
apiKeyAuthenticationformPostindexBasedQueuesongLyricssonicSimilaritytopSongsByArtistIdtranscodeOffset
AI/LLMs notice #
i sometimes use LLMs to scan for suggestions on fixing bugs or suggestions to improve/optimize written code.
LLMs are also used to initially write translation locales (/src/lib/languages/locales) as i am not multi-lingual but wanted to provide access to other languages. while i have run multiple passes on these, there may be some minor issues in translation for certain languages, so if you notice issues, please make an issue or PR!