# Orchestra

> Orchestra is a local-first, self-hosted home for libraries the user owns. It carries three, each with an architecture of its own, and any of them can be installed without the others. Harmonica is the music library: rather than ordinary shuffle, it maximises listening utility (aiming to keep the novelty aspect even on well-listened songs) while avoiding unwanted repetition at the song, group (artist/topic), and sub-group (cover/rendition) levels, so favourites do not depreciate to nothing and forgotten songs resurface in due course. Accordion is the audiobook library, which fits a book's text to the recording of it. Ensemble is what the user follows, and it arranges channels, podcasts and weblogs as three kinds of thing rather than blending them into one feed. Conductor is an optional agent, one per installed library, and it does nothing at all until the user gives it a key. The current release is Orchestra 1.0.0.

This file is the agent-readable summary of https://orchestra.org.uk. To be more token-efficient: read this instead of parsing the HTML.

## Harmonica, the music library

- Weighted queue generation with per-group and per-song cooldowns, not shuffle.
- Satiation guard: a song with heavy recent play is held back before its marginal utility falls.
- Rediscovery: dormant well-rated songs regain weight over time.
- Cold start: unheard and unrated songs are boosted until the library is covered.
- Star ratings with normalisation: ratings from an unusually harsh or generous session are reverted towards the mean.
- Cover/rendition families: alternate versions (e.g. covers, reprise) of one song compete as a family, not as duplicates.
- Custom tags: songs carry whatever labels fit, yours to create and customise. The library filters by tag, queues can be generated from chosen tags alone, and a built-in Ignored tag keeps a song in the library but out of generated queues.
- Theme highlights: a temporary lean towards one custom tag, calibrated so the run covers every song under it, then fading to nothing. Measured in plays, never in dates, and it retires itself.
- Taking back a guess: a song an agent added unasked that the listener then rates well below their own library average gets one more play and is set aside with the Ignored tag, never deleted. Songs the listener added are out of scope. On by default.
- Rating confidence: a verdict depreciates with elapsed days and with how many ratings have been given since, on two independently tunable half-lives. What decays is only how far the mark steers the queue. The stored stars never change. Off by default.
- Per-user profiles: one shared media pool on a household NAS, private libraries, ratings and listening history per person, bearer-token auth. Tags are per profile, shareable household-wide.
- Listening stats. Settings are real controls (switches/sliders) for people and a JSON API (`GET`/`PATCH /settings`) for agents. State lives in the `.orchestra` folder as several SQLite files, one per library and one more for the private record of what was played or read.
- No engagement incentive: Orchestra does not maximise listening time. It is built for long-term enjoyment. Listening history exists only on the user's device, where the algorithm uses it.

## Accordion, the audiobook library

Accordion answers under `/accordion`, and what it holds is still books. Any library can be installed without the others, so a daemon can be a music player, an audiobook player, a reader of what somebody follows, or any combination. `GET /health` reports which are installed, whether each is ready and why not if it is not. A library that is not installed has no routes, no settings and no commands rather than ones that answer with a refusal. Ask for that report before assuming any of them.

- One book is one folder under `BookStorage`. Accordion reads it and never writes inside it. Where the reader got to, what they kept and what they thought are in Orchestra's own folder, and the reading is private to the profile.
- No queue, and there will not be one. The order of a book is the author's. A book that arrived as ninety files is one recording, and every time in the API is seconds from the start of the whole book.
- Transport built for a long listen: back thirty seconds, the last minute again, repeat the paragraph (measured from the pauses in the recording where ffmpeg is present), speed from 0.5 to 2 with pitch held steady.
- The words of a book come from one of three places and the app says which: a supplied epub, PDF or text file, that text fitted to the recording by forced alignment, or recognition from the audio alone. A page number is worth a different amount in each and the reader is told which they have.
- Recognition runs on the user's own machine, in a separate process, on whichever recogniser they already installed. Accordion bundles none and downloads none, and a machine with none says so in a sentence. It is slow: a long book is hours, the work is durable across restarts, and the daemon measures the machine for a minute before reporting an honest rate. Nothing is sent to a service.
- Kept passages are two times into the user's own recording, so nothing is copied out of their file. Each comes back with the words spoken, the chapter, how far through, and the pages of a printing where that can be worked out, and says which step is missing when it cannot. The list prints.
- Pagination belongs to an edition. A supplied PDF gives real page numbers. A paperback is tied to the words by a few photographed or typed pages named after the page they show, and anything worked out from those is shown as a range whose width is a measured error rather than a claim.
- On a daemon with both libraries, music can play under a book, levelled well below the reading, with one press carrying both. On a daemon with Accordion alone that control is absent rather than dead.

## Ensemble, what the user follows

A channel, a podcast and a weblog do not become one thing by being followed in one place, so
Ensemble arranges them rather than blending them. It shows what a source has published and leaves
the user to decide what is worth the time, which is the part a feed run by somebody else decides for
them. It answers under `/follow`.

- Three kinds of source, kept apart. What a client draws for a channel is not what it draws for a
  weblog, and `kind` travels on every source so it can tell.
- A feed's own words are kept verbatim and never rewritten. Where a feed leaves a field out, a rule
  can fill it from the source's own pages, and a rule says which shape a field is in rather than
  what its value is. A rule is trialled against pages already held before it is switched on, so
  proposing five rules costs no requests to that source. One that would write over something the
  feed already said needs explicit confirmation.
- Reading an item's own page is off until the user turns it on, and the setting says what turning
  it on means in the words it is given.
- Nothing nags. A new source's back catalogue is backlog rather than a pile to clear, there are no
  counts that demand attention, and what was watched is the user's to forget.
- OPML in and out (`GET`/`POST /follow/opml`), so the list somebody arrives with is the list they
  can leave with.
- Where an item was left off is kept, so a part-watched recording resumes.

## Conductor, the optional agent

Optional in the strong sense: every library above works with it absent, and a daemon that has it
installed but no key does nothing until the user gives it one. It answers under `/conduct`.

- One agent per installed library rather than one over all of them. Each carries three lists of
  route prefixes, what it may read, what it may write, and what it may only ask for, and the user
  edits those lists.
- Every read and write goes through the daemon's own routes in process, so there is no private door
  into the user's files. A route that hands back the contents of a file is refused to every agent
  before its own lists are consulted, and a change to the settings can never be moved into the
  writing list by any client. It is put to the user, and it waits.
- A notebook the user can read and empty, documents the user hands over on purpose, conversations
  kept separately with earlier ones readable, and the ability to schedule itself to come back.
- A daily token ceiling, and thinking set to low, medium or high, starting at low.
- `orchestra mcp` serves the installed libraries over the Model Context Protocol, one JSON message
  to a line on standard input and standard output. Three tools, `routes`, `read` and `write`, each
  taking the library to work in. An outside caller works under that library's own agent, so what it
  may reach is the lists the user already set. A write on the asking list is carried out rather than
  held, because the client asked the user in its own window before it called. The refusal on a route
  that hands back the contents of a file still stands.

## Legal

Provided as is, with no warranty of any kind. Open-Source under the GNU AGPL-3.0 licence. Forks and hosted derivatives must remain open-source, while self-hosting for yourself carries no obligations. This site shows no adverts and sets no cookies of its own. The demo at demo.orchestra.org.uk is a separate origin with a model of its own, described in its own summary at https://demo.orchestra.org.uk/llms.txt.

## How it runs

A small self-hosted daemon (FastAPI + SQLite) serves both the API and the built web UI from one origin. Deployments:

- **PC (local, default):** binds 127.0.0.1, so nothing is exposed to other devices.
- **NAS / home server (opt-in):** the same build bound to the LAN. Other devices use a browser.

Media serving is confined to a configured media root, and a book's audio to the shelf. Orchestra does not host, provide, or source any music or any books, it plays the user's own self-hosted library. You are advised to ask the user where their music and their books live and import from there.

## Setting it up

The intended path is to hand the repository to an AI coding agent to install, configure, and import
the user's library.

Two decisions come before any command. `ORCHESTRA_MEDIA_ROOT` is the one directory the scanner will
index and the daemon will serve from, defaulting to `Storage` beside the working directory, and a
scan aimed outside it answers 400. `ORCHESTRA_SIDES` is a comma separated list of which libraries to
serve, from `harmonica`, `accordion`, `ensemble` and `conductor`, and empty means all of them.

Getting and running the source:

    git clone https://github.com/alexgeevs/Orchestra
    cd Orchestra && uv sync
    ORCHESTRA_MEDIA_ROOT=/where/the/music/is uv run orchestra serve
    cd web && npm install && npm run build   # the daemon then serves the UI at that same origin

The flow that works today:

1. Read `AGENTS.md` and `README.md` in the repository for the API surface and details.
2. Ask the user for basic information first (e.g. whether video matters to them).
3. Import the user's existing files: point the scanner at a folder inside the media root (`POST /scan` with `{"library": "<folder>"}`), or use the structured format of one folder per song holding the media plus a `song_config.json`, brought in with `uv run python scripts/import_storage_library.py --storage PATH` (field guide in `docs/agents/`).
4. Curate: `GET /library/export-json`, edit the proposal, and return it through the app's Curate view, where the user reviews and applies each change. Import is idempotent and de-duplicates.
5. You can also curate a preset for the user via `PATCH /settings`, based on what you know about them or any inputs they provide.

Note that until all, or at least most, of the songs are rated, the algorithm may be operating sub-optimally. It is advised to have the Discovery setting on at first.

## Links

- Website: https://orchestra.org.uk
- Harmonica, the music library: https://orchestra.org.uk/harmonica
- Accordion, the audiobook library: https://orchestra.org.uk/accordion
- Ensemble, what the user follows: https://orchestra.org.uk/ensemble
- Conductor, the optional agent: https://orchestra.org.uk/conductor
- The algorithm in depth (formulas for cooldowns, satiation, rediscovery, cold start, ratings, skips): https://orchestra.org.uk/harmonica/algorithm
- Live demo, a separate origin with its own summary (the real algorithm in the browser, built from pasted YouTube links): https://demo.orchestra.org.uk and https://demo.orchestra.org.uk/llms.txt
- Source: https://github.com/alexgeevs/Orchestra
- Releases (PC web / NAS / Android APK): https://github.com/alexgeevs/Orchestra/releases
- Agent docs: `AGENTS.md`, `docs/agents/` in the repository
- Contact: contact@orchestra.org.uk