funoteka 0.1.0

package/dist/tags/encode.js

@@ -0,0 +1,164 @@
+/**
+ * The tags of a song, as bytes a container can carry.
+ *
+ * A cue track is not a file — it is a stretch of an image — so when this server
+ * serves one it *builds* the file, and the file it built had no tags at all:
+ * measured on the live collection, a cut segment arrived with one `STREAMINFO`
+ * block and nothing else, and a client that saved it for offline use had a file
+ * whose own player could show nothing but the file name (task:2895). What is
+ * here is the missing half of that answer.
+ *
+ * **The tags come from the meta layer, not from the image.** Copying the
+ * image's own blocks was the obvious fix and the measurement refused it: of the
+ * 156 FLAC images that hold split tracks, 27 carry tags — and those tags are the
+ * *disc's*. `Кино - Ночь (MKK861CD1).flac` states `title = Ночь (MKK861CD1)` and
+ * `album = lossless-galaxy.ru`; put on a cut track, the first is the name of a
+ * disc the track is one song of, and the second is the site it was downloaded
+ * from. A track wearing those is worse off than a track wearing nothing, because
+ * a player shows them with confidence. The meta layer is the only thing that
+ * knows what this track is, so it is the only thing asked.
+ *
+ * Names are the ones the collection already states — `title`, `artist`, `album`,
+ * `albumartist`, `tracknumber`, `discnumber`, `date`, `genre` are the eight most
+ * common names in `file_tag` (measured: 1943–3220 rows each, ahead of `comment`
+ * at 745) — so what a file this server wrote states is what a file it read
+ * states, and the reader needed no new spelling to understand its own output.
+ */
+/**
+ * What this writer calls itself, which is what the vendor field is for.
+ *
+ * Vorbis I §5.2.1 defines the vendor string as identifying the *software*, not
+ * the collection, and it is written for the same reason a `TENC` frame is: a
+ * file that says who wrote it can be asked why it looks the way it does.
+ */
+const VENDOR = 'funoteka';
+/** The fields to write, in a fixed order, each as `NAME=value` — Vorbis I §5.2.2. */
+function fields(tags) {
+    const wanted = [
+        ['TITLE', tags.title],
+        ['ARTIST', tags.artist],
+        ['ALBUMARTIST', tags.albumArtist],
+        ['ALBUM', tags.album],
+        ['TRACKNUMBER', tags.trackNumber],
+        ['DISCNUMBER', tags.discNumber],
+        ['DATE', tags.date],
+        ['GENRE', tags.genre],
+    ];
+    return wanted
+        .filter((entry) => entry[1] !== null && entry[1] !== '')
+        .map(([name, value]) => [name, String(value)]);
+}
+/**
+ * The body of a `VORBIS_COMMENT` metadata block (Vorbis I §5.2.1, RFC 9639
+ * §8.6, which is the same layout).
+ *
+ * A 32-bit vendor length and its bytes, a 32-bit field count, then each field as
+ * its own length and bytes — every length little-endian, every string UTF-8. The
+ * block *header* is not here: that is the container's, and `stream/flac.ts`
+ * writes it, because a block header is three bytes of type and size that only a
+ * FLAC file has.
+ *
+ * A field is written even when it is the only one, and the block is written even
+ * when there are none — an empty comment list is a valid block that says the
+ * file states nothing, which is a different statement from a file with no
+ * comment block at all, and the one this server can make.
+ */
+export function vorbisComment(tags) {
+    const vendor = Buffer.from(VENDOR, 'utf8');
+    const written = fields(tags).map(([name, value]) => Buffer.from(`${name}=${value}`, 'utf8'));
+    const at = (length) => {
+        const buffer = Buffer.alloc(4);
+        buffer.writeUInt32LE(length, 0);
+        return buffer;
+    };
+    return Buffer.concat([
+        at(vendor.length),
+        vendor,
+        at(written.length),
+        ...written.map((field) => Buffer.concat([at(field.length), field])),
+    ]);
+}
+/**
+ * A whole ID3v2.4 tag, which is what an mp3 segment is served behind.
+ *
+ * **Version 2.4 and not 2.3, and the reason is the collection.** 2.3 has two
+ * encodings and neither is UTF-8 — a title with one Cyrillic letter in it needs
+ * UTF-16 with a byte-order mark, and this collection is full of them. 2.4 added
+ * UTF-8 as a third encoding, and every reader that matters — this project's own
+ * (`tags/id3v2.ts`) and ffmpeg's — reads it. The alternative is writing a
+ * byte-order mark into every song whose name is not ASCII and hoping the reader
+ * guesses the endianness, which is the guess the reader's own comments spend a
+ * page explaining.
+ *
+ * The frame sizes are **syncsafe** here, which is 2.4's other change: four bytes
+ * of seven bits each, so that a size can never contain a byte that looks like a
+ * frame sync. That is the trap in writing 2.4 by hand, and the test reads the
+ * result back through this project's own reader rather than asserting the bytes.
+ */
+export function id3v2(tags) {
+    const frames = [];
+    for (const [name, value] of fields(tags)) {
+        frames.push(textFrame(FRAMES[name] ?? name, value));
+    }
+    return Buffer.concat([header(frames), ...frames]);
+}
+/**
+ * The frame identifiers a name is written under.
+ *
+ * 2.4's own set, and the date is the one worth stating: `TYER` is 2.3's frame
+ * for a year and 2.4 replaced it with `TDRC`, which carries a whole timestamp —
+ * so a year goes in `TDRC` because that is the frame a 2.4 reader looks for, and
+ * the value is short rather than wrong. `tags/id3v2.ts` reads both and prefers
+ * the one that states more, so a file this server wrote and a file a ripper
+ * wrote are read by the same rule.
+ */
+const FRAMES = {
+    TITLE: 'TIT2',
+    ARTIST: 'TPE1',
+    ALBUMARTIST: 'TPE2',
+    ALBUM: 'TALB',
+    TRACKNUMBER: 'TRCK',
+    DISCNUMBER: 'TPOS',
+    DATE: 'TDRC',
+    GENRE: 'TCON',
+};
+/** Four bytes of id, four of syncsafe size, two of flags — the informal 2.4 §4. */
+function textFrame(id, value) {
+    const text = Buffer.concat([Buffer.from([0x03]), Buffer.from(value, 'utf8')]);
+    const frame = Buffer.alloc(10);
+    frame.write(id, 0, 'latin1');
+    syncsafe(text.length).copy(frame, 4);
+    // Flags are zero: no compression, no encryption, no grouping, no unsynchronisation.
+    return Buffer.concat([frame, text]);
+}
+/** The tag header: `ID3`, version, flags, and the size of what follows (2.4 §3.1). */
+function header(frames) {
+    const body = frames.reduce((total, frame) => total + frame.length, 0);
+    const head = Buffer.alloc(10);
+    head.write('ID3', 0, 'latin1');
+    head[3] = 0x04;
+    head[4] = 0x00;
+    head[5] = 0x00;
+    syncsafe(body).copy(head, 6);
+    return head;
+}
+/**
+ * A length as four seven-bit bytes, most significant first (2.4 §6.2).
+ *
+ * The top bit of every byte is clear, so no byte of a size can be mistaken for a
+ * frame sync or a terminator by a scanner that is looking for one. A length that
+ * does not fit in 28 bits is refused rather than truncated: it cannot happen for
+ * a tag this writer builds, and the failure of getting it wrong silently is a
+ * tag whose frames are read from the wrong offsets.
+ */
+function syncsafe(value) {
+    if (!Number.isInteger(value) || value < 0 || value >= 1 << 28) {
+        throw new Error(`a tag length must fit in four syncsafe bytes: ${value}`);
+    }
+    return Buffer.from([
+        (value >> 21) & 0x7f,
+        (value >> 14) & 0x7f,
+        (value >> 7) & 0x7f,
+        value & 0x7f,
+    ]);
+}

package/dist/tags/first.js

@@ -0,0 +1,130 @@
+/**
+ * The tags a song listing asks for, as one row of their own per file.
+ *
+ * A listing builds a `Child` per song, and eight of that payload's fields come
+ * out of `file_tag`: the genre, the track artist, the two advisories that decide
+ * `explicitStatus`, and the four ReplayGain numbers.
+ *
+ * **A page of five hundred songs costs 10.04 ms reading them the obvious way —
+ * one correlated subquery per name — and 6.37 ms reading them off this row**,
+ * measured 2026-09-16 on a copy of the live collection, the two statements
+ * interleaved in one run (task:2925). The saving is 36% of the heaviest listing
+ * route there is.
+ *
+ * **The shape was not the defect, and the measurement is why this is a table and
+ * not a query rewrite.** Every alternative is worse: all eight as one
+ * `json_group_object` is no faster and answers differently; a `LEFT JOIN` to a
+ * derived pivot — the shape `ALBUM_GENRES` uses — cannot be restricted to the
+ * page, so it materialises over the whole tag table and multiplies the page's
+ * cost by an order of magnitude; a covering index `(file_id, name, position,
+ * value)` is **thirteen times** worse when forced, and the planner will not
+ * choose it because it gives up the free ordering; `WITHOUT ROWID` five times
+ * worse. What is left is that eight seeks a song are eight seeks a song.
+ *
+ * So the values move out of the tag table and a file's row is joined the way
+ * `audio_probe` already is: one primary-key lookup, one row a file. The join
+ * itself is not quite free — the page without any tag columns at all is 6.56 ms
+ * in a run that put the eight subqueries at 11.29 — but it is an order of
+ * magnitude cheaper than asking the tag table, and it is what the 36% above is
+ * made of.
+ *
+ * **The rule is the API's own and is written once**, in `SELECT` below: the
+ * *first value by position* of each name, trimmed of the whitespace a tag can
+ * hide in, an empty result counted as no value at all so that a second line
+ * falls through to a first. `migrations/036_file_tag_first.sql` carries the
+ * frozen copy of it for the backfill; this is the one that runs from here on.
+ *
+ * What is deliberately *not* here is a cheaper-looking `MIN(position)` beside a
+ * bare `value`, which reads the value out of whichever row the aggregate
+ * happened to keep — SQLite guarantees that only while the subquery holds
+ * exactly one aggregate, so a later `COUNT(*)` added beside it would silently
+ * turn the genre into an arbitrary row's genre. `albumGenres` in `meta.ts`
+ * declines that form at length, and this declines it for the same reason.
+ */
+/** What a `Child` shows, and the tag each column is read from. */
+const FIRST_TAGS = [
+    ['genre', 'genre'],
+    ['artist', 'track_artist'],
+    ['itunesadvisory', 'advisory_itunes'],
+    ['rtng', 'advisory_mp4'],
+    ['replaygain_track_gain', 'rg_track_gain'],
+    ['replaygain_album_gain', 'rg_album_gain'],
+    ['replaygain_track_peak', 'rg_track_peak'],
+    ['replaygain_album_peak', 'rg_album_peak'],
+];
+const COLUMNS = FIRST_TAGS.map(([, column]) => column);
+/**
+ * The whitespace a tag value is measured through, spelled out.
+ *
+ * Not SQLite's one-argument `TRIM`, which removes spaces and leaves a tab — so a
+ * tag holding `"\t"` would pass the emptiness guard and arrive at a client as a
+ * genre nobody can see. `meta.ts` spells the same set beside `trimmed`, and
+ * `migrations/036_file_tag_first.sql` spells it a third time for the backfill.
+ *
+ * **Three spellings, and only two of them are held together by a test.**
+ * `test/tags-first.test.ts` compares this module against its own oracle, written
+ * in the old subquery form; the migration's copy is compared to neither, and no
+ * test can reach it — on a fresh database `file_tag` is empty, so its `INSERT`
+ * selects nothing. The three were checked against each other by hand on a copy
+ * of the live collection (3280 rows, no drift) and against the eight subqueries
+ * on nineteen awkward synthetic shapes (no drift); what is missing is a way to
+ * keep them honest without a person.
+ */
+const TRIMMED = `TRIM(ft.value, ' ' || CHAR(9) || CHAR(10) || CHAR(13) || CHAR(160) || CHAR(12288))`;
+const NAMES = FIRST_TAGS.map(([name]) => `'${name}'`).join(', ');
+/**
+ * One file's row, from the tags it has now.
+ *
+ * `rn = 1` leaves one row per (file, name), so the `MAX` below has nothing to
+ * choose between and is exact rather than arbitrary — the whole reason for the
+ * window function.
+ */
+const SELECT = `
+  SELECT ft.file_id,
+         ${FIRST_TAGS.map(([name, column]) => `MAX(CASE WHEN ft.name = '${name}' THEN ft.value END) AS ${column}`).join(',\n         ')}
+    FROM (SELECT ft.file_id, ft.name, ${TRIMMED} AS value,
+                 ROW_NUMBER() OVER (PARTITION BY ft.file_id, ft.name ORDER BY ft.position) AS rn
+            FROM file_tag ft
+           WHERE ft.file_id = ? AND ft.name IN (${NAMES}) AND ${TRIMMED} <> '') ft
+   WHERE ft.rn = 1
+   GROUP BY ft.file_id`;
+/**
+ * The two statements the tags stage runs for each file it has just read.
+ *
+ * Prepared once and handed back rather than prepared per file, which is how
+ * every other statement in that stage is treated: it is inside one
+ * `BEGIN IMMEDIATE`, and the compiler is not what this should be spending the
+ * write lock on.
+ *
+ * **Cleared before it is written, and not upserted.** A file whose genre tag was
+ * taken out of it has to lose the genre — and a write that only inserts when
+ * there is something to insert would leave the old row standing, because a file
+ * with no tags of these eight names produces no row at all. Clearing first makes
+ * "no row" and "no tags" the same thing, which is what a file nobody has read
+ * has always been.
+ */
+export function firstTagStatements(db) {
+    return {
+        clear: db.prepare('DELETE FROM file_tag_first WHERE file_id = ?'),
+        write: db.prepare(`INSERT INTO file_tag_first (file_id, ${COLUMNS.join(', ')}) ${SELECT}`),
+    };
+}
+/**
+ * The same pair, prepared and run, for one file.
+ *
+ * For a caller that has one file in hand and no reason to keep a statement
+ * around — a test writing `file_tag` by hand and standing in for the scanner,
+ * which is the only other thing that writes it. Both roads go through `SELECT`
+ * above, so the rule has one spelling either way, and a test that wrote the tags
+ * without writing this row would be describing a collection the scanner cannot
+ * produce.
+ *
+ * It prepares both statements on every call, which is a cost a caller in a loop
+ * should not pay: a fixture rebuilding many files wants `firstTagStatements`
+ * once and its two statements inside the loop. The stage does exactly that.
+ */
+export function refreshFirstTags(db, fileId) {
+    const { clear, write } = firstTagStatements(db);
+    clear.run(fileId);
+    write.run(fileId);
+}

package/dist/tags/flac.js

@@ -0,0 +1,196 @@
+import { pictureBlockAt } from "./picture.js";
+import { betterPicture, noTags } from "./types.js";
+import { readCommentList } from "./vorbis-comment.js";
+/**
+ * Read a FLAC stream's metadata blocks.
+ *
+ * Written against **RFC 9639** — the format's standard (IETF Standards Track,
+ * December 2024) — so that every section number below is a citation and not a
+ * recollection. The other readers in this directory were written the second way,
+ * and on 2026-09-12 one of them turned out to have been misreading real files
+ * since it was written; this is the sweep that followed.
+ *
+ * The comments inside a FLAC block are described by section 8.6 and by Xiph.Org's
+ * `v-comment` page, which is the Vorbis original — where the two differ, section
+ * 8.6 is what a FLAC file does.
+ *
+ * Everything a file has to say about itself lives in this chain: the block walk
+ * that finds the Vorbis comments walks past the duration on the way, which is
+ * why both come out of one pass and why neither costs a process.
+ *
+ * The walk is defensive by design. A truncated download, a block claiming more
+ * bytes than the file holds, a comment block full of nonsense — each ends the
+ * walk with whatever was already gathered, because the caller is a scan over a
+ * whole collection and one damaged file must not be able to stop it.
+ */
+/**
+ * RFC 9639 (FLAC), section 8.1: a metadata block opens with a four-byte header —
+ * a last-block flag, a seven-bit type, and the block's size in bytes as a
+ * three-byte big-endian number *excluding* the header.
+ *
+ * The same section forbids type 127. It is not special-cased here: the walk
+ * steps over any unrecognised block by its declared size, which is the only
+ * thing a reader can do with a block it does not know, and stopping on it would
+ * cost the file its tags.
+ *
+ * The block types this reader needs (Table 2): 0 is the stream information,
+ * 4 the Vorbis comments. A file also carries padding, a seek table, pictures and
+ * an application block, none of which say anything about who made the record.
+ */
+const BLOCK_STREAMINFO = 0;
+const BLOCK_VORBIS_COMMENT = 4;
+const BLOCK_PICTURE = 6;
+function readUInt24BE(bytes, at) {
+    return ((bytes[at] ?? 0) << 16) | ((bytes[at + 1] ?? 0) << 8) | (bytes[at + 2] ?? 0);
+}
+/**
+ * Read the block at `at` — the body, past its four-byte header.
+ *
+ * A zero in any of the four size fields means the encoder did not state it
+ * (section 8.2), which is why they are carried out rather than folded into a
+ * duration here: a caller rebuilding a stream needs to know what was stated and
+ * what was not, and only this function knows the difference.
+ */
+export function flacStreamInfo(bytes, at) {
+    const uint = (index, width) => {
+        let value = 0;
+        for (let i = 0; i < width; i += 1)
+            value = (value << 8) | (bytes[at + index + i] ?? 0);
+        return value;
+    };
+    // 16 + 16 + 24 + 24 bits before the packed tail: rate(20) | channels-1(3) |
+    // bits-1(5) | total samples(36).
+    let packed = 0n;
+    for (let i = 0; i < 8; i += 1)
+        packed = (packed << 8n) | BigInt(bytes[at + 10 + i] ?? 0);
+    return {
+        minBlockSize: uint(0, 2),
+        maxBlockSize: uint(2, 2),
+        minFrameSize: uint(4, 3),
+        maxFrameSize: uint(7, 3),
+        sampleRate: Number(packed >> 44n),
+        channels: Number((packed >> 41n) & 7n) + 1,
+        bitsPerSample: Number((packed >> 36n) & 31n) + 1,
+        totalSamples: Number(packed & ((1n << 36n) - 1n)),
+    };
+}
+function readStreamInfo(bytes, at, into) {
+    const info = flacStreamInfo(bytes, at);
+    into.sampleRate = info.sampleRate;
+    into.channels = info.channels;
+    into.bitsPerSample = info.bitsPerSample;
+    if (info.sampleRate > 0 && info.totalSamples > 0) {
+        into.durationMs = Math.round((info.totalSamples / info.sampleRate) * 1000);
+    }
+}
+/**
+ * Where the metadata ends and the audio begins.
+ *
+ * Section 8: the blocks follow the `fLaC` signature directly and come before any
+ * audio frame, and the last of them says so with a flag in its header — so the
+ * first frame starts where that block ends. Null when the signature is absent or
+ * a block claims more bytes than are here, which is a file whose audio offset is
+ * not knowable rather than one that starts at some other place.
+ *
+ * This walks the same chain `readFlac` walks, which is deliberate and not an
+ * oversight: that one is gathering tags and must keep whatever it found when a
+ * file turns out to be damaged, and this one wants a single number and would
+ * rather have none than a wrong one.
+ */
+export function flacAudioStart(bytes) {
+    if (bytes.length < 4)
+        return null;
+    if (bytes[0] !== 0x66 || bytes[1] !== 0x4c || bytes[2] !== 0x61 || bytes[3] !== 0x43)
+        return null;
+    let at = 4;
+    while (at + 4 <= bytes.length) {
+        const header = bytes[at] ?? 0;
+        const body = at + 4 + readUInt24BE(bytes, at + 1);
+        if (body > bytes.length)
+            return null;
+        at = body;
+        if ((header & 0x80) !== 0)
+            return at;
+    }
+    return null;
+}
+/**
+ * The picture a PICTURE block carries.
+ *
+ * The block's layout is RFC 9639 section 8.8 and lives in `picture.ts`, because
+ * the same block turns up base64-encoded in a Vorbis comment — one parser for
+ * it is one place for the layout to be wrong. What is here is the part that is
+ * this container's own: the block is a contiguous run of the file, so the image
+ * inside it is named by a *file* offset, which is what `TagPicture` means
+ * everywhere except in the one case the type marks.
+ */
+function readPicture(bytes, at, length, into) {
+    const found = pictureBlockAt(bytes, at, at + length);
+    if (found === null)
+        return;
+    into.picture = betterPicture(into.picture, {
+        mime: found.mime,
+        kind: found.kind,
+        offset: found.dataAt,
+        length: found.dataLength,
+    });
+}
+/**
+ * Walk the chain of metadata blocks.
+ *
+ * Section 8: the blocks follow the `fLaC` signature directly and come before any
+ * audio frame, and the first of them must be the stream information. Nothing
+ * here insists on that order — a file that puts its stream information later is
+ * broken, section 8.2 leaves a decoder's behaviour on broken stream information
+ * unspecified, and the reading that costs the collection least is to take what
+ * the blocks say and keep walking. A second stream information block, which the
+ * same section forbids, would be read the same way: last one wins.
+ */
+export function readFlac(bytes) {
+    const result = noTags('flac', 'flac');
+    let at = 4; // past the `fLaC` marker the caller has already checked
+    while (at + 4 <= bytes.length) {
+        const header = bytes[at] ?? 0;
+        const last = (header & 0x80) !== 0;
+        const type = header & 0x7f;
+        const length = readUInt24BE(bytes, at + 1);
+        const body = at + 4;
+        // A block promising more bytes than the file holds means the file is
+        // damaged; what was read before it stands.
+        if (body + length > bytes.length)
+            break;
+        if (type === BLOCK_STREAMINFO && length >= 34)
+            readStreamInfo(bytes, body, result);
+        else if (type === BLOCK_VORBIS_COMMENT)
+            readCommentBlock(bytes, body, length, result);
+        else if (type === BLOCK_PICTURE)
+            readPicture(bytes, body, length, result);
+        at = body + length;
+        if (last)
+            break;
+    }
+    return result;
+}
+/**
+ * The Vorbis comment block (section 8.6), read by the same code an Ogg file's
+ * comments are read by — the block and the packet hold the same list, and
+ * `vorbis-comment.ts` is where that is stated once.
+ *
+ * A picture carried here rather than in a PICTURE block is a `METADATA_BLOCK_PICTURE`
+ * comment: base64 inside the block, so the image is *not* a contiguous range of
+ * the file even though the block is, and the answer says so. No file in this
+ * collection uses that form — a FLAC that carries art carries it as a block —
+ * but the rule is the shared reader's and applies the moment one does.
+ */
+function readCommentBlock(bytes, at, length, into) {
+    const picture = readCommentList(bytes, at, at + length, into);
+    if (picture === null)
+        return;
+    into.picture = betterPicture(into.picture, {
+        mime: picture.mime,
+        kind: picture.kind,
+        indirect: true,
+        offset: at,
+        length,
+    });
+}

package/dist/tags/genres.js

@@ -0,0 +1,123 @@
+/**
+ * The ID3v1 genre list, and the references that point into it.
+ *
+ * An ID3v2 genre is not always a word. Section 4.2.1 lets it be a reference to
+ * this list — `"(17)"` means Rock, and v2.4 writes the same reference as a bare
+ * number — so a reader that stores the string stores a number where a genre
+ * belongs. The collection is full of them: of 700 mp3 files here, 105 carry
+ * `"(52)Electronic"` or `"(17)"`, and a FLAC beside them states its genre in
+ * plain words, so the reference would be the one shape of genre the meta layer
+ * could not read.
+ *
+ * The table is taken from the sources and not retyped, and three of them are
+ * compared against each other: Appendix A of v2.3 (0..125, labelling 80..125
+ * "Winamp extensions"), Appendix A of v2.4 (0..79), and the official ID3v1 test
+ * suite's generation log (0..255) — Martin Nilsson's generator, by the author of
+ * the specification. They agree on 124 of the first 126 entries word for word.
+ * The two exceptions are spelling: entry 67, where v2.3 repeats ID3v1's original
+ * misspelling and v2.4 corrects it, and entry 123, where the appendix has
+ * A cappella and the suite A capella. The appendix's spelling is kept where the
+ * two appendices agree, and v2.4's where they do not.
+ *
+ * 126..147 come from the suite alone, which is the only source here that names
+ * them. Past 147 it names nothing, and the one list that goes further is
+ * ffmpeg's own — an implementation, not a text — so the table stops where the
+ * sources do and a reference it cannot answer stays the string the file wrote.
+ */
+/**
+ * Index is the reference: `ID3V1_GENRES[17]` is Rock.
+ *
+ * Exported because the list is not ID3's alone — an MP4 carries the same
+ * numbering in its `gnre` atom, one-based, and a reader of it needs this table
+ * rather than a second copy of it.
+ */
+export const ID3V1_GENRES = [
+    'Blues', 'Classic Rock', 'Country',
+    'Dance', 'Disco', 'Funk',
+    'Grunge', 'Hip-Hop', 'Jazz',
+    'Metal', 'New Age', 'Oldies',
+    'Other', 'Pop', 'R&B',
+    'Rap', 'Reggae', 'Rock',
+    'Techno', 'Industrial', 'Alternative',
+    'Ska', 'Death Metal', 'Pranks',
+    'Soundtrack', 'Euro-Techno', 'Ambient',
+    'Trip-Hop', 'Vocal', 'Jazz+Funk',
+    'Fusion', 'Trance', 'Classical',
+    'Instrumental', 'Acid', 'House',
+    'Game', 'Sound Clip', 'Gospel',
+    'Noise', 'AlternRock', 'Bass',
+    'Soul', 'Punk', 'Space',
+    'Meditative', 'Instrumental Pop', 'Instrumental Rock',
+    'Ethnic', 'Gothic', 'Darkwave',
+    'Techno-Industrial', 'Electronic', 'Pop-Folk',
+    'Eurodance', 'Dream', 'Southern Rock',
+    'Comedy', 'Cult', 'Gangsta',
+    'Top 40', 'Christian Rap', 'Pop/Funk',
+    'Jungle', 'Native American', 'Cabaret',
+    'New Wave', 'Psychedelic', 'Rave',
+    'Showtunes', 'Trailer', 'Lo-Fi',
+    'Tribal', 'Acid Punk', 'Acid Jazz',
+    'Polka', 'Retro', 'Musical',
+    'Rock & Roll', 'Hard Rock', 'Folk',
+    'Folk-Rock', 'National Folk', 'Swing',
+    'Fast Fusion', 'Bebob', 'Latin',
+    'Revival', 'Celtic', 'Bluegrass',
+    'Avantgarde', 'Gothic Rock', 'Progressive Rock',
+    'Psychedelic Rock', 'Symphonic Rock', 'Slow Rock',
+    'Big Band', 'Chorus', 'Easy Listening',
+    'Acoustic', 'Humour', 'Speech',
+    'Chanson', 'Opera', 'Chamber Music',
+    'Sonata', 'Symphony', 'Booty Bass',
+    'Primus', 'Porn Groove', 'Satire',
+    'Slow Jam', 'Club', 'Tango',
+    'Samba', 'Folklore', 'Ballad',
+    'Power Ballad', 'Rhythmic Soul', 'Freestyle',
+    'Duet', 'Punk Rock', 'Drum Solo',
+    'A cappella', 'Euro-House', 'Dance Hall',
+    'Goa', 'Drum & Bass', 'Club-House',
+    'Hardcore', 'Terror', 'Indie',
+    'BritPop', 'Negerpunk', 'Polsk Punk',
+    'Beat', 'Christian', 'Heavy Metal',
+    'Black Metal', 'Crossover', 'Contemporary',
+    'Christian Rock', 'Merengue', 'Salsa',
+    'Thrash Metal', 'Anime', 'JPop',
+    'Synthpop',
+];
+/**
+ * The two content types the list does not number.
+ *
+ * Section 4.2.1 defines them beside the numeric references and says they work
+ * the same way; v2.4 writes them without brackets. ffprobe leaves `(RX)` as
+ * typed, which is a difference this reader takes deliberately: the
+ * specification gives the string a meaning, and a reader that ignored it would
+ * be storing a keyword as though it were a genre.
+ */
+const KEYWORD_GENRES = {
+    RX: 'Remix',
+    CR: 'Cover',
+};
+/**
+ * A genre reference resolved to the genre, or the value unchanged.
+ *
+ * Unchanged is the answer for everything the specification does not describe:
+ * a genre already written as a word, a reference the table cannot answer, a
+ * bracket that does not close. Returning the value as it arrived is what keeps
+ * this a decoding step rather than a guess — a reader with nothing to decode
+ * must not be able to alter what it read.
+ *
+ * Everything after the closing bracket goes, refinement and all. That is
+ * ffprobe's style — `"(4)Eurodisco"` reads Disco — and this project compares
+ * itself against ffprobe, so the divergence is worth less than the agreement.
+ */
+export function resolveGenre(value) {
+    const bracketed = /^\(([^)]*)\)/.exec(value);
+    const inner = bracketed?.[1] ?? value;
+    const name = /^\d+$/.test(inner)
+        ? ID3V1_GENRES[Number(inner)]
+        : KEYWORD_GENRES[inner];
+    // A bracket that opened but resolved to nothing leaves the whole value alone,
+    // which is also what happens to a value with no bracket at all.
+    if (name === undefined)
+        return value;
+    return name;
+}