# Harmony Song Library: attribution and data notice

`harmony-song-library.json` is a teaching-oriented, normalized collection of
1,000 unique popular-song chord charts. It is not presented as one canonical
worldwide ranking of the “most successful” songs; no such single ranking
exists. The catalog combines chart-selected, critic-selected, and
expert-annotated collections and retains source/rank metadata where available.

## Sources and licenses

Licensing is source-specific; the combined teaching index does not replace or
merge the terms attached to each source collection.

- **McGill Billboard Project via CoCoPops** — original harmonic annotations by
  John Ashley Burgoyne, Jonathan Wild, and Ichiro Fujinaga; CoCoPops conversion
  by Claire Arthur and Nathaniel Condit-Schultz. The underlying McGill
  annotations are released under
  [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/).
- **Rolling Stone Corpus via CoCoPops** — annotations by Trevor de Clercq and
  David Temperley; CoCoPops conversion by Claire Arthur and Nathaniel
  Condit-Schultz. Catalog data is used under
  [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
- **Isophonics via ChoCo** — Isophonics annotations by Matthias Mauch and
  collaborators; standardized in ChoCo by Andrea Poltronieri and
  collaborators. This ChoCo partition is released under
  [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
- **Modern hit charts from iReal Pro via ChoCo** — community-created iReal
  charts standardized by Andrea Poltronieri and collaborators in ChoCo, with
  canonical artist, title, and release-year metadata reviewed by the 80/20
  Music School. The 100-chart teaching selection uses the ChoCo standardized
  output under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
  This notice makes no separate licence claim about the upstream public
  playlists beyond ChoCo's published licence for its standardized output.

The current 1,000-song build contains 676 McGill Billboard records, 200
Rolling Stone Corpus records, 24 Isophonics records, and 100 reviewed modern
iReal/ChoCo records.

Direct source, repository, revision, creator, and license links are also stored
in the JSON payload's `sources` array. Chordify, JAAH, Mozart Piano Sonata, and
other non-commercial partitions are not used.

### Chart evidence and licensed editions

The build compares duplicate artist/title recordings wherever the three
independent open analysis collections overlap: McGill Billboard, Rolling Stone
Corpus, and Isophonics. Thirty-two published songs currently have two or three
such source analyses. Their `chartEvidence` records the source count and the
best transposition-invariant overlap of the normalized chord vocabularies. A
high percentage is supporting evidence; a low percentage exposes a source
disagreement instead of hiding it. The remaining 968 songs are explicitly
marked as single-source records.

These comparisons are not official publisher lead sheets. Licensed editions
from [Musicnotes](https://www.musicnotes.com/),
[Hal Leonard](https://www.halleonard.com/), and
[Sheet Music Direct](https://www.sheetmusicdirect.com/) can be useful for
manual, song-by-song checks when a matching arrangement exists. Their
copyrighted charts are not bulk-scraped, copied into this dataset, or claimed
as having verified every song. Arrangement availability and differences from
the original recording must be assessed per title.

## Transformations

For this trainer, chord symbols are normalized to its supported chord
vocabulary, inversions are omitted, and timed annotations are grouped into
bars. Every encoded section occurrence and repeated or held chord/rest bar
remains in source order. The JSON contains chord and
formal-analysis facts only; it does not contain lyrics, melodies, or audio.

In the CoCoPops/Humdrum sources, a null token that carries the preceding chord
through another measure is emitted as another bar with that held chord. Harte
inversions such as `Eb/5` are retained as their root-and-quality chord (`Eb`)
while the inversion itself is omitted. Explicit no-chord events are stored as
the canonical `N.C.` symbol. This retains both complete rest measures and the
source order of rests and chords inside mixed measures; rests consume timeline
duration but produce no pitched sound and no chord identity.

For the modern iReal/ChoCo selection, normalized chord and N.C. events stay in
timestamp order and repeated event labels are not deduplicated. Four events are
grouped into one compact teaching bar. The standardized symbolic event
durations are not treated as recording-aligned timing; playback spaces the
events within each teaching bar evenly.

### Tempo provenance

Tempo values are retained only where the checked-in source provides a usable
timing basis. For CoCoPops charts, `sourceBpm` is the rounded median
quarter-note tempo calculated from the recording-aligned timestamp spine and
the notated meter. The dominant CoCoPops meter is also retained as
`sourceQuarterNotesPerBar`, expressed as quarter-note units per bar (for
example, 12/8 becomes 6), so playback does not force compound or triple meters
into a four-quarter bar. For Isophonics, tempo is the rounded median of the
recording-aligned beat intervals when that annotation exists. For modern
iReal/ChoCo charts, a plausible positive metadata value is labeled separately
as **chart tempo**; it is not represented as an original-recording BPM. The
iReal source time signature is retained in the same quarter-note-unit field.

The current build has a source-backed tempo for 946 songs. The remaining 54
source charts contain no trustworthy tempo or contain a missing, zero, or
implausibly low metadata value. Those records keep `sourceBpm: null`; the web
player visibly starts them at a separate, editable 90 BPM practice fallback.
The current build has a source-backed bar duration for 975 songs. When no
reliable source meter exists, playback uses an explicit four-quarter
practice-bar fallback. Normalized intra-bar chord changes divide the displayed
bar evenly. No web-sourced or guessed BPM values are inserted.

### Practice-beat provenance

The interactive player generates an editable drum loop from each song's
available tempo, meter, release era, artist, and title metadata. It chooses a
broad practice style and applies a small deterministic variation, so reopening
the same song produces the same loop. This is a style-derived practice groove,
not a transcription or reconstruction of the original drum performance. The
source catalogs do not provide drum transcriptions.

## Reproduction

With local CoCoPops and ChoCo checkouts, regenerate the file from the project
root with:

```sh
node scripts/generate-harmony-song-library.mjs \
  --cocopops /path/to/CoCoPops \
  --choco /path/to/choco
```