quine-global/quintodrome.git

<img src="desktop/src-tauri/icons/128x128@2x.png" alt="Quintodrome logo" align="right" height="96" />

# Quintodrome

A [Tauri](https://tauri.app) desktop app that wraps
[Navidrome](https://www.navidrome.org) — your self-hosted music server — into a
native macOS/Windows application.

<img width="1179" height="904" alt="Screenshot of Quintodrome music player" src="./screenshot.png" />


The server is bundled as a sidecar binary and managed automatically, so there's
nothing to install, configure, or keep running: launch the app and it starts
(and later shuts down) its own Navidrome instance for you.

> This repository is a fork of [Navidrome](https://github.com/navidrome/navidrome).
> Everything outside `desktop/` is the upstream server + web UI; `desktop/` is
> the Quintodrome wrapper around it.

## What it does

Batteries included:

- **Auto-provisioning** — on a fresh install the app creates the initial admin
  user (`admin` / `admin`) and logs in as it automatically, skipping both the
  "create an admin user" and login screens.
- **Opted-out telemetry** — Navidrome's insights collector is disabled by
  default.
- **Masked address bar** — the internal `127.0.0.1:4533` origin is shown as
  `http://quintodrome`.
- **External links** (Last.fm, artist pages, …) open in your default browser.
- **Native editing shortcuts** — Cmd+X/C/V/A/Z work in the web UI.
- **Swipe navigation** — two-finger swipe back/forward on macOS.

## Install

On macOS, with [Homebrew](https://brew.sh):

```sh
brew tap quine/tap https://git.quineglobal.com/quine-global/homebrew-tap.git
brew trust quine/tap
brew install --cask quintodrome
```

The tap URL is required: without one, `brew tap` assumes a GitHub repo. Homebrew
refuses to load casks from a tap you haven't trusted, hence `brew trust`. Update
with `brew upgrade --cask quintodrome`.

Tapped it from the old address (`forge.quinefoundation.com`)? Point it at the
new one:

```sh
brew tap --custom-remote quine/tap https://git.quineglobal.com/quine-global/homebrew-tap.git
```

Or download the `.dmg` from the
[releases page](https://forge.quinefoundation.com/quine-global/quintodrome/releases)
(see [below](#macos-quintodrome-is-damaged-and-cant-be-opened) if macOS refuses
to open it).

## Quick start

```sh
# one-time: Node >= 24 (see .nvmrc), Go >= 1.26, Rust
just run
```

`just run` builds the Navidrome sidecar and launches the app. No `just`? See
the [desktop README](desktop/README.md) for the plain commands, or install it
with `brew install just`.

To wipe Navidrome's persistent state (database, cache) and start fresh:

```sh
just clean-state
```

## Building a distributable

```sh
just bundle          # or: ./desktop/scripts/build.sh
```

This produces the platform's packaged app under
`desktop/src-tauri/target/release/bundle/` (e.g. `macos/Quintodrome.app` on
macOS). Release builds happen in Forgejo CI — see
[`.gitea/workflows/desktop.yml`](.gitea/workflows/desktop.yml), which builds
the macOS `.app`/`.dmg` (arm64 and x86_64) for tagged releases and updates the
Homebrew tap.

> Artifacts are unsigned (no Apple/Windows code-signing certs), so users will
> see Gatekeeper/SmartScreen prompts.

### macOS: "Quintodrome is damaged and can't be opened"

Because the app isn't signed with an Apple Developer ID, macOS blocks
downloaded copies. After moving the app to `/Applications`, run:

```sh
xattr -dr com.apple.quarantine /Applications/Quintodrome.app
```

The Homebrew cask strips the quarantine flag automatically on install. Don't
re-sign the app with `codesign`: it's already ad-hoc signed, and rewriting the
binaries in place can get the library scanner killed with "Code Signature
Invalid".

## Configuration

Environment variables override the defaults:

| Variable                    | Default                        | Purpose                                  |
| --------------------------- | ------------------------------ | ---------------------------------------- |
| `QUINTODROME_HOST`          | `127.0.0.1`                    | Address the webview connects to          |
| `QUINTODROME_PORT`          | `4533`                         | Port for the Navidrome server            |
| `QUINTODROME_MUSIC_FOLDER`  | OS music dir (e.g. `~/Music`)  | Where your music lives                   |
| `QUINTODROME_ADMIN_PASSWORD`| `admin`                        | Password for the auto-created admin user (fresh installs only) |
| `QUINTODROME_PUBLIC_URL`    | `http://quintodrome`           | Friendly origin shown in the address bar |

The data folder (database, cache) is always the OS app-data directory
(e.g. `~/Library/Application Support/com.quineglobal.drome` on macOS).

## Repository layout

```
.
├── desktop/          # Quintodrome: the Tauri wrapper (Rust + toolbar HTML)
│   ├── src-tauri/    #   sidecar spawn/health-check, lifecycle, menu, clipboard
│   ├── src/          #   toolbar.html (nav bar) + index.html (splash)
│   └── scripts/      #   build.sh, icon generator
├── ui/               # Navidrome web UI (React)
├── server/           # Navidrome HTTP server
├── core/             # Navidrome core (scanning, transcoding, …)
├── cmd/              # Navidrome entrypoint / CLI
└── Justfile          # run / bundle / sidecar / clean-state
```

For the details of building and running the desktop app directly, see
[`desktop/README.md`](desktop/README.md).

## Development

Prerequisites:

- Rust (stable)
- Node.js ≥ 24 (pinned in `.nvmrc`)
- Go ≥ 1.26 (for building the Navidrome binary)

The Navidrome server is built with `make build`; the wrapper stages it as
`desktop/src-tauri/binaries/navidrome-<target-triple>` and bundles it as a Tauri
sidecar. See [`desktop/scripts/build.sh`](desktop/scripts/build.sh).

## Acknowledgements

Quintodrome is built on [Navidrome](https://github.com/navidrome/navidrome),
an open-source web-based music collection server and streamer. All credit for
the music server and web UI goes to the Navidrome project.