v1.14.0

Additive (MINOR) release: optional recording-identity keys, so a pack can carry a stable,
open, exact identity for the recording it transcribes.

Added

• New optional top-level manifest keys mbid — the
  MusicBrainz Recording MBID of the recording the pack transcribes (lowercase canonical
  UUID) — and isrc — its International Standard
  Recording Code. Both are author-set exact identity keys: a consumer SHOULD prefer them over
  free-text artist/title matching when grouping charts of the same recording or looking up
  external metadata, and SHOULD trust mbid when the two disagree. The stored ISRC is the bare
  12-character code — the hyphens in the common display form are presentation only, stripped
  when writing and before comparing.
  schemas/manifest.schema.json validates both formats.

Compatibility

• Purely additive. Older Readers ignore both keys and still load. Nothing is removed, renamed,
  or repurposed.

v1.13.0

Additive (MINOR) release: an engine-agnostic rig model so a feedpak can carry tone information
natively — a structured, portable alternative to the opaque tones.definitions passthrough.

Added

• New optional side-file rigs.json (§7.9) and manifest rigs
  key: a pack-level library of rigs, each an ordered set of effect blocks. Every block splits
  what it is (intent, engine-independent) from how to render it (realizations — an ordered
  preference list over nam / ir / plugin / builtin engines, extensible to future ones). Open
  role/kind/engine vocabularies, an open normalized params map with optional time
  automation, and an optional graph for non-serial topology (parallel amps, wet/dry, stereo).
  schemas/rigs.schema.json.
• Arrangement tones (§6.9) gains base_rig and
  changes[].rig, referencing a rig id in rigs.json. The legacy opaque tones.definitions
  passthrough is unchanged; a rig-aware Reader prefers the structured references.
• examples/extended.feedpak now ships a rigs.json and a tones block that exercises it.

Compatibility

• Purely additive. Older Readers ignore the rigs key, rigs.json, and the new base_rig/rig
  fields, and still load. Nothing is removed, renamed, or repurposed.

v1.12.0

Additive (MINOR) release: album-grouping and genre metadata. Backward-compatible — a 1.0.0
(or 1.11.0) pack is also a valid 1.12.0 pack, and an older reader ignores the new optional keys.

Added

• Album grouping + genre metadata (spec §5.1):
  four OPTIONAL, author-set top-level keys —

  • album_artist (string) — album artist for the release, so multi-artist / compilation
    albums group under one album identity; absent ⇒ falls back to artist.
  • track (int, 1-based) — track number within the album, for album playback order.
  • disc (int, 1-based, default 1) — disc number for multi-disc releases.
  • genres (list of strings, most specific first; genres[0] is primary) — genre labels.

  A reader predating 1.12.0 ignores all four.

v1.11.0

Additive (MINOR) release: multi-lingual lyric tracks, language tags, and language-tagged vocal
stems. Backward-compatible — a 1.0.0 pack is also a valid 1.11.0 pack, and an older reader ignores
the new optional keys and still loads the single lyrics pointer + stems as before.

Added

• Multi-lingual packs (spec §5.5,
  §5.1, §5.3): three OPTIONAL
  additive keys so a pack can express language and carry more than one lyric representation —

  • a top-level language (BCP 47) naming the song's
    primary sung language;
  • a per-stem language hint tagging a language-specific vocal stem (e.g. vocals_ja /
    vocals_en for a song with two sung-language recordings);
  • a lyric_tracks list of additional lyric files, each with id, file, language, and a
    kind of original / transliteration / translation, plus OPTIONAL lyrics_source,
    lyric_transcription provenance, and a stem pointer pairing a sung original with its vocal
    recording.

  Each track is an ordinary lyrics.json-shaped flat array, so
  no new side-file schema is introduced — only schemas/manifest.schema.json grows (a bcp47
$def, a lyricTrack $def, the lyric_tracks array, and language on the manifest and on
  $defs/stemEntry). The legacy single lyrics pointer is unchanged: when lyric_tracks is absent
  a reader behaves exactly as before, and when present a writer SHOULD still point lyrics at the
  primary-language original track's file for pre-1.11.0 readers. Exercised by the extended example
  (an English original + a Japanese translation + a romaji transliteration, and a language-tagged
  full stem).

Changed

• CI (no format change): the version-consistency guard (tools/check_versions.py) now covers
  every place the current version is written — the spec header, the §4.1 feedpak_version
  example + writer-SHOULD line, the README table and citation, and the extended example
  manifest, in addition to the newest CHANGELOG.md version. A missed spot during a bump now
  fails CI with a precise diff instead of drifting silently.
• Docs (no format change): the hand-editing guide's .jsonc section now spells out the two
  caveats — comments are the only relaxation (no trailing commas / JSON5), and a comment-bearing
  .jsonc needs a JSONC-aware reader, so keep distributed packs as comment-free .json.

v1.10.0

Additive (MINOR) release: a song-level harmony track. Backward-compatible — a 1.0.0 pack is also a
valid 1.10.0 pack, and older readers ignore the new optional manifest key + side-file.

Added

• Song-level harmony track — harmony.json (spec §7.8,
  manifest harmony key): the song's intended chord progression (the chords the song is,
  independent of what any arrangement plays) — reference/teaching data for fretboard-theory
  overlays, chord lyric lines, and practice-alongs. Time-ordered events applying until the next
  (same shape as keys.json): t (required), root (absolute note name; null marks a
  no-chord/N.C. event), quality, rn (Roman numeral relative to the active keys.json key,
  omitted when no key is active), and bass (slash-chord bass). Voicing-free (does not index
  arrangement chord templates) and honesty-ruled — a grader MUST NOT score against it. Defined
  as distinct from per-chord fn (as-played function): a Reader MAY derive one from the other, but
  neither is authoritative. quality/fn.q now reference a shared (recommended, not closed)
  chord-quality vocabulary so they stay interoperable. Schema:
  schemas/harmony.schema.json; exercised by the extended example
  (an Em→C→G→D7/F#→N.C. progression aligned to its Em/G keys.json). Implements #28.

v1.9.0

Additive (MINOR) release: audio stem formats beyond OGG. Backward-compatible — every existing
OGG-only pack stays valid, and a Reader that only decodes the baseline keeps working on any
portable pack.

Added

• Audio stem formats beyond OGG (spec §5.3.2,
  §1): stems are now dispatched by file extension, with a
  normative decoder baseline — a Reader MUST decode OGG (.ogg) and WAV (.wav) and
  SHOULD decode MP3 / FLAC / Opus. A new OPTIONAL codec hint on each stems[] entry
  disambiguates when an extension doesn't determine the codec (schema: codec on
  $defs/stemEntry in schemas/manifest.schema.json; exercised
  by the extended example's full stem as codec: vorbis). A portability rule requires a
  distributable pack to carry at least one baseline-format stem, so non-baseline stems are
  opportunistic enhancements rather than hard dependencies; a Reader MUST raise a clear error
  or fall back rather than fail silently on a format it can't decode. Proprietary/game formats
  (e.g. Wwise .wem) are explicitly not in the baseline, get no reference decoder, and
  MUST NOT be a distributable pack's only stem.

Changed

• §4.2 compatibility carve-out now lists two opt-in file-format relaxations — the existing
  .jsonc extension and (new) audio stem formats beyond OGG (1.9.0 widens the baseline
  OGG→OGG+WAV and allows formats above it; since OGG was the only pre-1.9.0 guarantee, even a
  baseline WAV-only pack needs a 1.9.0 Reader) — both kept MINOR on the same "strictly opt-in,
  per-file; only a pack that actually uses it needs a supporting Reader" justification.

v1.8.0

Additive (MINOR) release: the two deferred per-chord harmony descriptors from the §6.3.1 FEP.
Backward-compatible — a 1.0.0 pack is also a valid 1.8.0 pack, and older readers ignore the new
optional fields.

Added

• Chord-template harmony descriptors (spec §6.6): two
  OPTIONAL template fields that annotate the chord shape for teaching/display, never grading (the
  honesty rule — a grader MUST NOT score them) — caged (the CAGED-system shape the fingering
  derives from: one of C/A/G/E/D) and guideTones (chromatic semitone offsets 0–11
  above the chord root marking the quality-defining tones, typically the 3rd and 7th, e.g. a
  dominant-7 → [4, 10]). Both are key-independent shape properties, so they ride the template
  alongside voicing. Schema: caged (enum) + guideTones (int array) on $defs/template in
  schemas/arrangement.schema.json; exercised by the extended
  example (the Em template → caged: "E", guideTones: [3]). Completes the §6.3.1 FEP, whose
  caged/guideTones were deferred in 1.7.0.

v1.7.0

Additive (MINOR) release: per-chord harmony annotations. Backward-compatible — a 1.0.0 pack is also
a valid 1.7.0 pack, and older readers ignore the new optional fields.

Added

• Per-chord harmony annotations (spec §6.3.1,
  §6.6): two OPTIONAL fields that annotate a chord's
  harmony for teaching/display, never grading (the honesty rule — a grader MUST NOT score
  them) — fn on the chord instance ({rn, q, deg}: Roman-numeral label, quality token, and
  the chord root's chromatic offset 0–11 above the active keys.json
  tonic, mirroring sd; the chord's as-played function, derivable so a Reader MAY compute it),
  and voicing on the chord template (a key-independent voicing-type string, e.g. open /
  shell / drop2). Function rides the instance and voicing the template because the same shape
  recurs across keys. fn's prose notes its boundary with a future song-level harmony track (the
  intended progression). Schema: fn on $defs/chord and voicing on $defs/template in
  schemas/arrangement.schema.json; exercised by the extended
  example (an Em chord as vi in G major). caged and guideTones from the FEP are deferred.

v1.6.0

MINOR release under the new §4.2 opt-in file-format relaxation carve-out: the .jsonc
data-file extension (comment-annotated JSON), plus a docs-site version banner. No existing pack is
affected, and a comment-free .jsonc file is plain JSON — but a .jsonc file that actually
contains comments is not readable by a strict-JSON-only Reader; it requires a JSONC-aware
Reader. This is why .jsonc ships under an explicit, bounded carve-out rather than the ordinary
"older Readers keep working" minor rule (see the JSONC bullet below and spec §4.2 / §8).

Added

• Docs site (no format change): a build-time version banner. The site now stamps the newest
  released CHANGELOG.md version (SPEC_VERSION env → mkdocs.yml extra.spec_version →
  overrides/main.html) into a top announcement bar, so the displayed version is deterministic
  and no longer depends on Material's client-side GitHub-release widget (which is cached in the
  browser's localStorage and could lag a release).
• JSONC support (§2.2,
  §3,
  §8): .jsonc files (C-style-commented JSON) are
  now accepted anywhere .json files are specified. Hand-edited data files MAY use the .jsonc
  extension to signal that they contain comments; Readers strip comments before parsing, and
  Writers SHOULD preserve them on round-trip. Only comments are permitted — trailing commas and
  other JSON5-style relaxations are not; after comment removal a .jsonc file MUST be strict JSON.
  The reference validator (tools/validate.py) parses .jsonc files accordingly. Shipped as a
  MINOR bump under the §4.2 opt-in-relaxation carve-out: no existing pack is affected, and a
  comment-free .jsonc file is plain JSON, but a .jsonc file that contains comments is readable
  only by Readers that implement the comment-stripping step (a plain JSON parser errors on //),
  so a Writer needing maximum reader compatibility SHOULD keep data files as comment-free .json.

v1.5.0

Additive (MINOR) release: per-note teaching marks. Backward-compatible — a 1.0.0 pack is also a
valid 1.5.0 pack, and older readers ignore the new optional note fields.

Added

• Per-note teaching marks (spec §6.2.2):
  three OPTIONAL note fields that annotate how a note is taught or displayed, never whether it was
  played correctly (the honesty rule — graders MUST NOT score them) — fg (fret-hand finger,
  -1 unset / 0 thumb / 1–4 index→pinky, same convention as template.fingers), ch
  (strum-group key: notes sharing a value ≥ 0 are one strum/rake gesture, with pkd giving
  direction), and sd (scale degree as a chromatic offset 0–11 above the active
  keys.json tonic; derivable, so a Reader MAY compute it).
  Schema: fg / ch / sd on $defs/note in
  schemas/arrangement.schema.json; exercised by the extended
  example pack (an Em-triad rake grouped by ch).