engine-dj-mcp 0.9.2 → 0.11.0

package/README.md

@@ -1,168 +1,400 @@
 # engine-dj-mcp
 
+[![npm](https://img.shields.io/npm/v/engine-dj-mcp)](https://www.npmjs.com/package/engine-dj-mcp)
+[![licence](https://img.shields.io/npm/l/engine-dj-mcp)](./LICENSE)
+
 An MCP server that lets an AI assistant search and audit your **Engine DJ**
-libraries — the one on your Mac and the ones on your USB drives.
+libraries — the one on your computer and the ones on your USB drives.
 
 > **Not affiliated with, endorsed by, or sponsored by inMusic Brands, Denon
 > DJ, or the Engine DJ product.** "Engine DJ" is used here only to name the
 > software whose library this tool reads. No logos or brand artwork from
 > inMusic or Denon DJ are used in this project.
 
-## What it does
-
-- **Smart search** (`search_tracks`) — full text with diacritics folded,
-  tempo windows, harmonic key matching, rating, and play history ("what have
-  I not played in six months?").
-- **Track lookup** (`get_tracks`) — full metadata for specific track ids.
-- **Cues, loops and beatgrids** (`get_track_performance`) — decoded from
-  Engine's `PerformanceData`, with a per-field decode status. The cue and
-  beatgrid layouts are reverse-engineered but **validated against a real
-  Engine library**; the loop layout is not fully validated — see
-  [Limitations](#limitations).
-- **Collection audit** (`audit_library`) — missing files, unanalysed tracks,
-  tracks without cues or beatgrids, duplicates, suspicious tempos, orphaned
-  playlist entries.
-- **Read-only SQL** (`run_sql`) — an escape hatch for anything the tools
-  above do not cover.
-- **Library and index introspection** (`list_libraries`, `refresh_index`) —
-  see what was discovered and force a search-index rebuild.
-
-It also exposes two MCP resources: `engine://schema` (the field semantics an
-assistant needs before writing SQL against the library) and
-`engine://libraries` (what was discovered, and whether each library's schema
-is supported).
+Your library is opened **read-only at the operating-system level**. It is
+never written to unless you start the server with `--allow-writes` — see
+[Safety](#safety).
+
+## What you can ask
+
+Once connected, these are ordinary questions in chat:
+
+- *"Something dark around 124 in a minor key I haven't played in six months."*
+- *"Which tracks still have no hot cue set?"*
+- *"Find me anything harmonically compatible with 8A between 138 and 142."*
+- *"What's in my ACID Beach playlist, in order?"*
+- *"Anything around 128 in ACID Beach?"*
+- *"What's broken in my collection — missing files, duplicates, bad tempos?"*
+- *"Where are the cue points on this track, and what tempo did Engine analyse?"*
+- *"Build me a playlist of everything in 5A from 140 BPM up."* (needs `--allow-writes`)
+
+## Install
+
+```bash
+npx engine-dj-mcp
+```
+
+Claude Desktop — add to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp"] }
+  }
+}
+```
+
+To let the assistant create playlists as well, add `--allow-writes` — a flag
+in `args` rather than an environment variable precisely so it is visible in
+the configuration you are reading:
+
+```json
+{
+  "mcpServers": {
+    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp", "--allow-writes"] }
+  }
+}
+```
+
+**Requirements:** Node.js 22.13 or newer (for the unflagged `node:sqlite`;
+there are no native dependencies), and an Engine DJ library at schema 3.0.0
+through 3.0.2 — Engine DJ 4.5 and 5.x.
+
+## Tools
+
+Nine read-only tools, and a tenth — `create_playlist` — that appears only
+when you start the server with `--allow-writes`. Every tool that reads
+library data also accepts an optional `library` argument — see
+[Choosing a library](#choosing-a-library).
+
+### `search_tracks`
+
+The main one. Full-text search with diacritics folded, plus filters for
+tempo, key, rating, when a track was added and when it was last played.
+
+| Argument | What it does |
+| --- | --- |
+| `q` | Full text over title, artist, album, genre, comment and label. Diacritics are folded, so `bjork` matches `Björk` — Engine's own search does not. |
+| `bpm` | `{ min, max }` or `{ around, tolerance_pct }`. Resolved tempo, so an analysed BPM wins over the tag. |
+| `key` | `{ camelot: [...] }` for exact keys, `{ compatible_with: "8A" }` for harmonic neighbours, `{ mode: "minor" }` for a whole side of the wheel. |
+| `rating` | `{ min, max }`, 0–5. |
+| `played` | `{ never: true }`, or `{ before, after }` taking an ISO date or a relative form like `-6 months`. |
+| `added` | `{ before, after }`, same date forms. |
+| `flags` | `analyzed`, `available`, `has_cues`, `has_beatgrid`. `has_cues` means a hot cue is genuinely set — see [Limitations](#limitations). |
+| `playlist` | `{ id }` or `{ name }` — search inside one playlist. Results still come back by relevance or id; `get_playlist_tracks` is what preserves playlist order. |
+| `fields` | Which columns to return. Defaults to `id, artist, title, bpm, camelot, rating`. |
+| `limit`, `cursor` | Page size (default 25, max 200) and an opaque cursor for the next page. |
+| `include_total` | Off by default because counting costs far more than the page. Capped at 1000 — a capped result carries `total_capped: true` and means "at least 1000". |
+
+### `get_tracks`
+
+Full metadata for specific track ids, returned in the order you asked for.
+Unknown ids are omitted rather than failing the call.
+
+`ids` (required), `fields`, `redact_paths`.
+
+### `get_playlists`
+
+Your playlist tree, in the order Engine DJ shows it — folders included.
+
+The list is flat and in the order you would read down the sidebar with every
+folder expanded: `depth` and `path` carry the nesting, `parent_id` names the
+folder a list sits in.
+
+| Field | Meaning |
+| --- | --- |
+| `name`, `id`, `path` | `path` is the full `Folder/Sub/Name`, and is unique — a bare `name` need not be. |
+| `depth`, `parent_id` | The nesting. `parent_id` is `null` at the top level. |
+| `is_folder` | The list has child lists. Engine has no folder flag — a folder *is* a playlist that other playlists sit under — so an emptied folder reads as an empty playlist. |
+| `is_persisted` | Engine's own flag for a list saved to the device. Both values appear on lists Engine displays, so nothing is filtered on it. |
+| `track_count` | Entries in that list alone, never rolled up from its children — the number Engine shows beside it. |
+| `missing_count` | How many of those entries name a track this library does not have. |
+
+`limit` (default 200, max 1000). `warnings` appears if a playlist's link
+chain is damaged; nothing is ever dropped from the list because of one.
+
+### `get_playlist_tracks`
+
+The tracks of one playlist, **in playlist order**.
+
+Name it with `playlist_id` or with `playlist_name` — exactly one of the two.
+Playlist names are unique only within a folder, so a name matching more than
+one is refused with every candidate's id and full path rather than guessed
+at; pass the `path` from `get_playlists` to say which you meant.
+
+Every row carries `position`, its 1-based place in the playlist. Same
+`fields`, `limit` and `cursor` conventions as `search_tracks`.
+
+An entry whose track is not in this library keeps its slot and comes back as
+`{ position, entry_id, track_id, missing: true }`, with `missing_count`
+alongside `entry_count`. That is ordinary rather than corruption — playlist
+entries outlive their tracks and travel between drives — and they are kept in
+place so the number of rows still matches the playlist's own length. On one
+reference library a 43-entry playlist holds exactly one track that library
+can actually play.
+
+### `get_track_performance`
+
+Decodes the binary `PerformanceData` Engine stores per track: hot cues, the
+main cue, saved loops, the beatgrid, and a coarse waveform profile.
+
+Every field carries its own decode status **and** its own `layout` marker.
+`layout: "verified"` means the byte layout was confirmed against a real
+library, so `status: "ok"` is a claim about the values. `layout: "unverified"`
+would mean only that the bytes parsed; no field returns it today.
+
+Positions are sample offsets; cue and loop items also carry seconds.
+`items: []` with `slots: 8` means an analysed track with no cues set.
+
+`id` (required).
+
+### `audit_library`
+
+Ten collection health checks. Returns a count and a small sample of ids per
+check, never the full result set — a library with thousands of unanalysed
+tracks should not fill an assistant's context.
+
+| Check | Finds |
+| --- | --- |
+| `missing_files` | Tracks whose file is gone from disk |
+| `unavailable` | Tracks Engine has marked unavailable |
+| `unanalyzed` | Tracks Engine has not analysed |
+| `no_cues` | Tracks with no hot cue set |
+| `no_beatgrid` | Tracks with no beatgrid data |
+| `missing_key` | Tracks with no key detected |
+| `suspicious_bpm` | Analysed and tagged tempo disagree, or tempo is outside 60–200 |
+| `duplicates` | Same artist and title, or same size and length |
+| `empty_metadata` | No artist or no title |
+| `orphan_entries` | Playlist entries pointing at tracks not in this library — `get_playlist_tracks` shows where each one sits |
+
+`checks` — omit it to run all ten.
+
+### `run_sql`
+
+An escape hatch for questions the tools above do not cover. Read-only is
+enforced by the kernel, not by this tool. Results are bounded whatever the
+query says.
+
+Prefer `side.track_derived.camelot` and `side.track_derived.tempo` in `WHERE`
+clauses over the `camelot()` and `tempo()` SQL functions — the functions run
+per row and defeat the indexes.
+
+`sql` (required), `params`, `limit`.
+
+### `list_libraries`
+
+Every library found, including ones whose schema is unsupported — listed
+with their version, so you can tell a broken server from a missing library.
+Re-scans on every call, so a drive plugged in after the server started shows
+up without a restart. A library that is temporarily unreadable — Engine DJ
+writing to it, say — stays listed with `status: "unreadable"` rather than
+vanishing.
+
+No arguments.
+
+### `refresh_index`
+
+Rebuilds the search index if the library changed. Normally unnecessary; the
+server checks staleness itself before answering.
+
+### `create_playlist`
+
+The only tool that writes, and the only one that is not registered at all
+unless the server was started with `--allow-writes`.
+
+Creates one new top-level playlist from track ids — `track_ids` sets both
+what is in it and the order it is in, so a list built by `search_tracks`
+arrives in Engine DJ in the order the assistant chose. Nothing else changes:
+no playlist is renamed, reordered, emptied or deleted, and no track, cue or
+beatgrid is touched. The one existing row that moves is the previous last
+playlist's link, and Engine's own insert trigger is what moves it.
+
+| Argument | What it does |
+| --- | --- |
+| `title` | Name of the new playlist. Must not already be taken at the top level — Engine allows one name per folder. |
+| `track_ids` | Ids from `search_tracks` or `get_tracks`, in playlist order. May be empty, for an empty playlist. A track may appear at most once, which is Engine's own rule. |
+
+Each entry stores the track's origin identity — `(originDatabaseUuid,
+originTrackId)`, the pair Engine matches on — not the local row id, so a
+playlist built here reads the same way Engine's own does.
+
+The result carries `playlist_id`, `tracks_added` and `backup_path`. **To undo
+it, delete the playlist in Engine DJ**; `backup_path` is a whole-library
+snapshot for the case where something went wrong at a lower level, not an
+undo — see [Restoring a snapshot](#restoring-a-snapshot).
+
+Refusals name themselves: `playlist_exists` for a taken title,
+`unknown_track` for an id this library does not have, `duplicate_track` for
+the same id twice, `library_busy` if something else holds a conflicting lock
+right then, `library_needs_recovery` if Engine DJ left an unrecovered
+journal behind. Every error also carries `detail`: `not_committed` means the
+library is exactly what it was, and `committed_unverified` — the rare one —
+means the write may have landed but could not be verified afterwards, and is
+the only case that hands back a `backup_path`.
+
+## Resources
+
+- **`engine://schema`** — the field semantics an assistant needs before
+  writing SQL: how Engine encodes musical key, why tempo is
+  `COALESCE(bpmAnalyzed, bpm)`, that `Track.path` is relative, where playlist
+  order really lives, and which helper columns are indexed.
+- **`engine://libraries`** — what was discovered at startup and whether each
+  library's schema is supported. A snapshot; `list_libraries` is the live view.
 
 ## Choosing a library
 
 Engine DJ keeps a library on your computer and another on every drive you
-export to, so more than one is usually connected at once. `list_libraries`
-reports each of them with a `uuid` and a `path`, and **every tool that reads
-library data takes an optional `library` argument** — `search_tracks`,
-`get_tracks`, `get_track_performance`, `audit_library`, `run_sql` and
-`refresh_index`. Pass either the `uuid` or the `path` exactly as
-`list_libraries` printed it; the `~/…` form it reports is accepted alongside
-the absolute one. A value matching neither comes back as
-`library_not_found`, listing the libraries you can actually choose from.
-
-Leave `library` out and the server uses **the supported library holding the
-most tracks**, ties broken by the order the drives were scanned in. That
-matters: the local library Engine DJ creates on install is scanned first and
-is often empty, so "the first one found" would hide the drive you actually
-work from.
-
-Each library gets its own search index and its own read-only connection,
-opened the first time you ask that library a question — mounting four drives
-does not cost four connections. Every query, audit and file-path check stays
-inside the library selected for that call. Comparing two libraries against
-each other — "what is on this drive but not that one?" — is **not** something
-this server does.
+export to, so more than one is usually connected. `list_libraries` reports
+each with a `uuid` and a `path`, and every tool that reads library data takes
+an optional `library` argument. Pass either form exactly as printed — the
+`~/…` path is accepted alongside the absolute one. A value matching neither
+comes back as `library_not_found`, listing what you can choose from.
+
+Leave it out and the server uses **the supported library holding the most
+tracks**. That matters: the local library Engine DJ creates on install is
+scanned first and is often empty, so "the first one found" would hide the
+drive you actually work from.
+
+Each library gets its own index and its own connection, opened the first time
+you ask that library something. Comparing two libraries against each other —
+*"what is on this drive but not that one?"* — is **not** something this server
+does.
 
 ## Safety
 
 Your library is opened **read-only at the operating-system level**, not by
-convention or by a `PRAGMA` that a query could turn back off. Writes are
-refused by SQLite itself, and no file is ever created inside your `Engine
-Library` folder. The server keeps its search index in `~/.engine-dj-mcp/`.
+convention and not by a `PRAGMA` a query could turn back off. Writes are
+refused by SQLite itself, and without `--allow-writes` no file is ever
+created inside your `Engine Library` folder. The search index lives in
+`~/.engine-dj-mcp/`.
+
+### Writing
 
-`run_sql` accepts arbitrary SQL, but only ever the first statement of it is
+Without `--allow-writes` the server has no tool that can write, and the
+paragraph above holds exactly as written: SQLite itself refuses.
+
+With the flag, one tool appears — `create_playlist`. It adds a new playlist
+and nothing else: no existing playlist is renamed, reordered, emptied or
+deleted, and no track, cue or beatgrid is touched. The single change to an
+existing row is the previous last playlist's link, made by Engine's own
+trigger.
+
+Before the first write of a session the database is snapshotted to
+`~/.engine-dj-mcp/backups/`, and every write of that session returns its
+path. Ten snapshots are kept per library — per library *file*, so a library
+and its clone on another drive do not share the ten.
+
+One file *is* created inside your `Engine Library` folder while a write is in
+progress: SQLite's rollback journal, `m.db-journal`, next to `m.db`. It is
+removed when the transaction commits, and it is what makes the write
+all-or-nothing. If the process is killed mid-transaction the journal is left
+behind, and both this server and Engine DJ then treat the library as needing
+recovery — this server reports `library_needs_recovery` and refuses to touch
+the library, including for reads, until you have launched Engine DJ once so
+it can roll the journal back. Nothing else is ever written in that folder,
+and without `--allow-writes` not even this.
+
+The write takes SQLite's own write lock for the length of one transaction and
+does not wait for it: if something else — Engine DJ mid-save, a player — is
+holding a conflicting lock at that moment, the write is refused with
+`library_busy` and nothing is changed. Merely having Engine DJ *open* is not
+usually a conflict, and the write normally succeeds with Engine running;
+Engine will show the new playlist after it next re-reads the library.
+
+### Restoring a snapshot
+
+`backup_path` is not an undo. It is a copy of the **whole** `m.db` from
+before the session's first write, so putting it back reverts the entire
+library to that moment: every play count, import, cue, beatgrid and rating
+Engine DJ has written since is discarded along with the playlist you wanted
+gone. Reach for it only if the library itself is damaged — the case where
+`create_playlist` comes back with `detail: "committed_unverified"`.
+
+**To undo a playlist, delete it in Engine DJ.** Engine's own delete trigger
+repairs the playlist chain and cascades the entries away, which is exactly
+what removing it should do and is not something restoring a snapshot does
+better.
+
+`run_sql` accepts arbitrary SQL, but only the first statement is ever
 executed, and `VACUUM`, `ATTACH` and `DETACH` are rejected outright, so a
 chained or exfiltrating statement cannot slip past the read-only connection.
 
 If Engine DJ was closed uncleanly and left an unrecovered journal, this
-server will never open the library writably to "fix" it for you — that
-would break the one guarantee this project makes. It reports
-`library_needs_recovery` instead and asks you to launch Engine DJ once so it
-can recover the library itself.
+server will not open the library to "fix" it, with or without
+`--allow-writes` — rolling a journal forward is a repair on someone else's
+file, and `create_playlist` refuses such a library outright rather than
+letting SQLite do it on the way in. It reports `library_needs_recovery` and
+asks you to launch Engine DJ once so it can recover its own library.
 
 ## Limitations
 
 Read this before deciding what to trust.
 
-- **Cue, beatgrid and waveform layouts are validated; the loop layout is
-  not.** The
-  binary layouts inside `PerformanceData` are reverse-engineered, so every
-  decoded field says which kind it is:
-
-  - `layout: "verified"` — **cues** (including the main cue), the
-    **beatgrid**, and the **waveform summary**. These were derived from and
-    checked against a real Engine DJ 3.0.x library of 281 analysed tracks:
-    cue offsets land inside the track, the beatgrid's implied tempo matches
-    `bpmAnalyzed` on all 281, and the waveform's declared point spacing
-    multiplies back out to the track's sample count on all 281. A
-    `status: "ok"` here is a claim about the values, not just the parse.
-  - `layout: "unverified"` — **loops**. The blob's slot structure is known
-    (eight slots, uncompressed, little-endian) and an empty one decodes
-    correctly, but not one track in that library had a loop saved, so the
-    meaning of a *populated* loop slot is untested. Do not report loop
-    bounds to a user as fact.
-
-  A `layout` marker is a claim about the **bytes** — which offset holds
-  which field, and what the number there means. It is not a claim about
-  every name this server puts on them. Three labels are inferred rather than
-  measured, and the code says so where each is defined: which of a cue's
-  four colour bytes is which channel (they are reported as stored, as one
-  32-bit value, with no channel claim attached); that the second beatgrid is
-  the one Engine calls "adjusted" (that it is the one Engine *plays* is
-  measured — on seven tracks the other grid runs at exactly half the
-  analysed tempo); that `main_cue.is_adjusted` is what its flag byte means;
-  and that the waveform's three bytes per point are the low, mid and high
-  bands in that order. None of these affects a value you get back.
-
-  Everything else the server reports — titles, artists, tempo, key, ratings,
-  play history, file paths — is read straight from the database and carries
-  no such caveat.
-- **`has_cues` and `no_cues` mean "a hot cue is set", and cost a little to
-  say so.** Engine writes a `quickCues` blob to every analysed track whether
-  or not any pad is used, so the cheap SQL test (`quickCues` present and
-  non-empty) answers a question about *analysis*: in the 281-blob reference
-  library all 281 would count as having cues, while two tracks (three rows,
-  one track being exported to a second library) actually do. The blob is
-  therefore decoded when the search index is built, and
-  `search_tracks(flags: { has_cues: true })` and `audit_library`'s `no_cues`
-  both read the decoded answer. That costs about 100 ms of extra rebuild
-  time at 50,000 tracks, and a rebuild only runs when your library changes.
-
-  The track's **main cue** does not count towards it: Engine sets that as a
-  playback start marker rather than the DJ placing it (it is set on 159 of
-  the 281 blobs, including every track the library records as played), so
-  counting it would answer a third question again. `has_beatgrid` and
-  `no_beatgrid` do still test for the blob — a `beatData` blob has no
-  "written but empty" state, and on all 281 real blobs presence and a usable
-  grid have never disagreed.
-- **It never writes to your library.** Not to add a cue, not to fix a tag,
-  not even to recover a journal Engine DJ left behind. The connection is
-  read-only at the kernel level, so a write is refused by SQLite itself
-  rather than by a rule this code could get wrong.
-- **It does not read play history.** `Track.timeLastPlayed` is used to answer
-  "what have I not played in six months?", but the separate Engine history
-  database — individual sessions, decks, what followed what — is not opened
-  at all.
-- **It does not build set lists**, reorder playlists, or suggest transitions.
-  It answers questions about the collection; the mixing is yours.
-- **Schema 3.0.0 through 3.0.2 only** (Engine DJ 4.5 and 5.x). Older and
-  newer libraries are listed with their version and reported as unsupported
-  rather than read on a guess.
-
-## Requirements
-
-- Node.js 22 or newer
-- Engine DJ with library schema 3.0.0–3.0.2 (Engine DJ 4.5 and 5.x)
+**The `PerformanceData` layouts are reverse-engineered**, so every decoded
+field says which kind it is. All four are marked `layout: "verified"` —
+derived from and checked against a real Engine DJ 3.0.x library of 281
+analysed tracks, where cue offsets land inside the track, the beatgrid's
+implied tempo matches `bpmAnalyzed` on all 281, and the waveform's declared
+point spacing multiplies back out to the track's sample count on all 281.
 
-## Install
+Loops were the last to earn it. The slot grid was pinned down by 2248
+sentinels, but no library available had a loop saved in it, so a *populated*
+slot stayed untested and loops carried `layout: "unverified"` through several
+releases. One deliberately saved loop settled it: its slot spans 1.678321678 s
+on a track Engine analysed at 143 BPM, which is four beats to within 4e-15 s.
+Only the right field order, unit and endianness land on a whole beat count.
 
-```bash
-npx engine-dj-mcp
-```
+A `layout` marker is a claim about the bytes, not about every name put on
+them. Four labels are inferred rather than measured, and the code says so
+where each is defined: which of a cue's four colour bytes is which channel
+(they are returned as stored, one 32-bit value, with no channel claim); that
+the second beatgrid is the one Engine calls "adjusted" (that it is the one
+Engine *plays* is measured — on seven tracks the other runs at exactly half
+the analysed tempo); that `main_cue.is_adjusted` is what its flag byte means;
+and that the waveform's three bytes per point are low, mid and high in that
+order. None affects a value you get back.
 
-Claude Desktop configuration:
+Everything else — titles, artists, tempo, key, ratings, play history, file
+paths — is read straight from the database and carries no such caveat.
 
-```json
-{
-  "mcpServers": {
-    "engine-dj": { "command": "npx", "args": ["-y", "engine-dj-mcp"] }
-  }
-}
-```
+**`has_cues` and `no_cues` mean "a hot cue is set".** Engine writes a
+`quickCues` blob to every analysed track whether or not a pad is used, so the
+cheap SQL test would answer a question about *analysis* instead: in the
+reference library all 281 blobs would count as having cues, while two tracks
+actually do. The blob is therefore decoded while the index is built. That
+costs roughly 100 ms extra at 50,000 tracks, and only when your library
+changes. The track's **main cue** does not count towards it — Engine sets
+that as a playback marker rather than the DJ placing it. `has_beatgrid` does
+still test for the blob: `beatData` has no "written but empty" state.
+
+**It writes nothing but playlists, and only when you ask for it.** Without
+`--allow-writes` the library is opened read-only at the OS level and there is
+no tool that could write. With the flag, `create_playlist` adds playlists —
+and that is the whole list. Not a cue, not a tag, not a rating, and not even
+the recovery of a journal Engine DJ left behind.
+
+**It does not read play history.** `Track.timeLastPlayed` answers "what have I
+not played in six months?", but the separate Engine history database —
+sessions, decks, what followed what — is not opened at all.
+
+**Smartlists are not reported.** Engine's rule-based lists live in a separate
+`Smartlist` table with its own ordering and a JSON rule column, and nothing
+here reads it. `get_playlists` reports ordinary playlists and folders only, so
+a smartlist you can see in Engine will not appear.
+
+**An empty folder reads as an empty playlist.** Engine's schema has no folder
+flag — a folder is simply a playlist that other playlists sit under — so
+`is_folder` means "has child lists". A folder you have emptied is
+indistinguishable from a playlist with no tracks.
+
+**Playlists can be created, not edited.** With `--allow-writes` a new
+playlist can be added; there is no reordering, renaming, deleting, or adding
+a track to a playlist that already exists, and no set lists or suggested
+transitions. It answers questions about the collection and writes down the
+answer if you ask; the mixing is yours.
+
+**Schema 3.0.0 through 3.0.2 only.** Older and newer libraries are listed with
+their version and reported as unsupported rather than read on a guess.
 
 ## Licence
 

package/dist/blobs/index.d.ts

@@ -8,10 +8,12 @@
  * sample count. `status: "ok"` on a verified field is a claim about the
  * values, not merely about the parse.
  *
- * `"unverified"` still means what it always did: the bytes parsed without
- * contradicting the layout, and nothing more. It survives on `loops` because
- * no track in the 281 examined has a loop set, so while the slot structure is
- * pinned down, the meaning of a *populated* slot is untested.
+ * `"unverified"` means the bytes parsed without contradicting the layout, and
+ * nothing more. No field carries it today: `loops` was the last one, and it
+ * held the marker only for as long as no library available had a loop saved in
+ * it. One saved loop supplied the missing prediction — see `decodeLoops` — and
+ * the marker is kept here because it is what a future field decoded from an
+ * unpopulated example would deserve.
  *
  * The marker is about the *bytes*: which offset holds which field, and what
  * the numbers there mean. It is not a claim about every English word this
@@ -215,19 +217,23 @@ export declare function hasCueSet(buf: Buffer | null): boolean;
  *                                                (23 bytes with an empty label)
  *
  * Evidence for the framing and the slot grid: 8 + 8×23 = 192, the size of
- * all 281 real blobs, every one of which parsed to exactly its last byte;
+ * every unpopulated real blob, each of which parsed to exactly its last byte;
  * the little-endian count reads as 8, and the little-endian -1.0 sentinel
  * (`000000000000f0bf`) appears at the offsets this layout predicts in all
  * 2248 slots. Reading the count big-endian gives 134217728, which is what
  * made every real track decode as `unsupported` before.
  *
- * This layout keeps `layout: "unverified"`. Not one of the 2248 slots is
- * populated — this library has no saved loops — so while the slot grid is
- * pinned down by 2248 sentinels, the six bytes after each slot's two doubles
- * are zero everywhere, and nothing here distinguishes start/end from
- * end/start, or fixes the order of the flag and colour bytes. A populated
- * loop is the one thing the available data cannot exercise, so it is not
- * claimed as verified.
+ * The sentinels pin the slot grid, but an empty slot cannot say which double
+ * is the start, what unit the doubles are in, or what the six trailing bytes
+ * mean — so this layout carried `unverified` for as long as no library had a
+ * saved loop in it. The `saved-loop` golden fixture is that loop, and it
+ * settles all three at once. Its slot reads label "Loop 1", start 2129416.08
+ * and end 2203430.06, which at the 44100 Hz `beatData` declares for the track
+ * is 1.678321678 s — exactly four beats at the 143 BPM Engine analysed, to
+ * 3.6e-15 s. Nothing but the right field order, the right unit and the right
+ * endianness lands on a whole number of beats, so the layout is verified.
+ * The trailing bytes read `01 01` (start set, end set) and four colour bytes,
+ * which is the same tail `quickCues` slots carry.
  */
 export declare function decodeLoops(buf: Buffer | null, sampleRate?: number | null): LoopsResult;
 /**