Harmony

Off you go!

# for good measure
npm run songs
npm run dev
# open: http://localhost:5173/demo/chord-search/

Generating the song dataset locally

Chord data lives in the sibling harmony-data repo and is not committed to this project. The app reads static/data/songs.json (gitignored).

To build or refresh the dataset from harmony-data:

npm run songs

This runs tasks/build-songs.js, which:

• reads corrected Top-10 songs from ../harmony-data/songs/corrected/
• joins Billboard flags and chart year from ../harmony-data/data/tracker.csv and billboard.csv
• converts chord data into the format used by the chord-search matcher
• writes static/data/songs.json (full corrected Top-10 corpus, used by all /demo/ pages)

Note: src/data/hand-corrected-songs.ts holds handCorrectedSongs; src/data/hand-reviewed-songs.ts holds problematicSongs and trickySongsToMatchCorrectly for reviewing song data before use in the UI. Hand corrections are applied at runtime when loading songs.json.

When harmony-data is updated (e.g. after pulling fresh scrapes):

cd ../harmony-data && git pull
cd ../harmony && npm run songs
npm run dev

The /demo/chord-search route fetches /data/songs.json at runtime. If the file is missing, run npm run songs first.

Coverage cache (IndexedDB)

All /demo/ pages that run the core-progression coverage algorithm (define-chord-progression, core-progressions, harmony-map, artists) cache the result in the browser's IndexedDB so the worker-pool computation only runs once.

The cache key is a SHA-256 fingerprint of:

• Core progression matching fields — each progression's name, chordProgression, and scale (not group names, descriptions, or colors)
• Song corpus — sorted songKey + section count + roman-token count per song, so re-running npm run songs or editing hand-corrected-songs.ts automatically invalidates the cache
• Schema version — COVERAGE_CACHE_SCHEMA_VERSION in coverageCacheKey.ts

When to bump COVERAGE_CACHE_SCHEMA_VERSION: if you change matching algorithm logic (files under progression-matching-logic/) in a way that would produce different SongCoverageEntry results for the same input data, increment the constant to force all browsers to recompute.

Naming map clusters

/harmony-map circles dense groups of songs and can label them (e.g. "doo wop", "axis"). Those names are shared, hand-curated data committed in src/data/named-clusters.ts — not browser storage — so everyone who pulls the repo sees the same names.

Each entry is { anchorSongKey, name }. A cluster is identified by one representative song, not by its exact membership — membership shifts a little every time the embedding re-runs, but as long as that one song is still grouped there, the name still resolves. This also means there should only ever be one entry per name (and per anchor song); naming a cluster from a newly highlighted song replaces its existing entry rather than adding a second one.

To name or rename a cluster:

1. On /harmony-map, select a song in the cluster you want to name and hit highlight in the song inspector panel (a song must be highlighted — that's what becomes the anchor).
2. Click an empty area inside the cluster's dashed circle. A text input appears; type the name and hit Enter.
3. This updates the map live in your session, but a browser page can't write to files on disk, so it isn't saved yet. Open the devtools console — naming logs a paste-ready line, e.g.:

   Cluster named — add to src/data/named-clusters.ts to persist:
   { anchorSongKey: "jason-mraz__im-yours", name: "axis" }
   

4. Copy that into the namedClusters array in src/data/named-clusters.ts (replacing the old entry if you're renaming/re-anchoring one that already exists), then commit and push as usual. Your collaborator picks it up on their next git pull.

MIDI input, classification, search

Quick start to use your keyboard

Designed for Reface CP MIDI input set to the keyboard's second octave on the octave slider (next to volume).

You can do common actions directly from the keyboard:

• Clear search: hit lowest three notes
• Toggle search on/off (ie so you can play chords without them scrambling your current results): highest 3 notes

Implementation details: harmony/src/chord-processing/README.md

---

Svelte Starter [default info from the pudding starter repo]

This starter template aims to quickly scaffold a SvelteKit project, designed around data-driven, visual stories at The Pudding.

Notes

• Do not use or reproduce The Pudding logos or fonts without written permission.
• Prettier Formatting: Disable any text editor Prettier extensions to take advantage of the built-in rules.

Features

• ArchieML for micro-CMS powered by Google Docs and Sheets
• Lucide Icons for simple/easy svg icons
• Style Dictionary for CSS/JS style parity
• Runed for svelte5 rune utilities
• CSV, JSON, and SVG imports
• SSR static-hosted builds by default

Quickstart

From Scratch

• Click the green Use this template button above.
• Alternatively: npx degit the-pudding/svelte-starter my-project

Pre-existing Project

• clone the repo

Installation

• In your local repo run pnpm install or npm install

Development

npm run dev

Change the script in package.json to "dev": "svelte-kit dev --host" to test on your local network on a different device.

Deploy

Check out the Makefile for specific tasks.

Staging (on Github)

npm run staging

Production (on AWS for pudding.cool)

npm run prodution

Manual

npm run build

This generates a directory called build with the statically rendered app.

Password-Protected

To create a password-protected build:

Make sure you have a .env file in your root with a value of PASSWORD=yourpassword

make protect

Then run either make github or make pudding.

Style

There are a few stylesheets included by default in src/styles. Refer to them in app.css, the place for applying global styles.

For variable parity in both CSS and JS, modify files in the properties folder using the Style Dictionary API.

Run npm run style to regenerate the style dictionary.

Some css utility classes in reset.css

• .sr-only: makes content invisible available for screen reader
• .text-outline: adds a psuedo stroke to text element

Custom Fonts

For locally hosted fonts, simply add the font to the static/assets folder and include a reference in src/styles/font.css, making sure the url starts with "assets/...".

Google Docs and Sheets

• Create a Google Doc or Sheet
• Click Share -> Advanced -> Change... -> Anyone with this link
• In the address bar, grab the ID - eg. "...com/document/d/1IiA5a5iCjbjOYvZVgPcjGzMy5PyfCzpPF-LnQdCdFI0/edit"
• paste in the ID above into google.config.js, and set the filepath to where you want the file saved
• If you want to do a Google Sheet, be sure to include the gid value in the url as well

Running npm run gdoc at any point (even in new tab while server is running) will fetch the latest from all Docs and Sheets.

Structural Overview

Pages

The src/routes directory contains pages for your app. For a single-page app (most cases) you don't have to modify anything in here. +page.svelte represents the root page, think of it as the index.html file. It is prepopulated with a few things like metadata and font preloading. It also includes a reference to a blank slate component src/components/Index.svelte. This is the file you want to really start in for your app.

Embedding Data

For smaller datasets, it is often great to embed the data into the HTML file. If you want to use data as-is, you can use normal import syntax (e.g., import data from "$data/file.csv"). If you are working with data but you want to preserve the original or clean/parse just what you need to use in the browser to optimize the front-end payload, you can load it via +page.server.js, do some work on it, and return just what you need. This is passed automatically to +page.svelte and accessible in any component with getContext("data").

Pre-loaded helpers

Components

Located in src/components.

// UsageimportExamplefrom"$components/Example.svelte";

• Footer.svelte: Pudding recirculation and social links.
• Header.svelte: Pudding masthead.

Helper Components

Located in src/components/helpers.

// UsageimportExamplefrom"$components/helpers/Example.svelte";

Available

• Scrolly.svelte: Scrollytelling.

Need to migrate

• ButtonSet.svelte: Accessible button group inputs.
• Chunk.svelte: Split text into smaller dom element chunks.
• Countdown.svelte: Countdown timer text.
• DarkModeToggle.svelte: A toggle button for dark mode.
• Figure.svelte: A barebones chart figure component to handle slots.
• MotionToggle.svelte: A toggle button to enable/disable front-end user motion preference.
• Range.svelte: Customizable range slider.
• ShareLink.svelte: Button to share link natively/copy to clipboard.
• SortTable.svelte: Sortable semantic table with customizable props.
• Slider.svelte (and Slider.Slide.svelte): A slider widget, especially useful for swipe/slide stories.
• Tap.svelte: Edge-of-screen tapping library, designed to integrate with slider.
• Tip.svelte: Button that links to Strip payment link.
• Toggle.svelte: Accessible toggle inputs.

Headless Components

bits UI comes pre-installed. It is recommended to use these for any UI components.

Layercake Chart Components

Starter templates for various chart types to be used with LayerCake. Located in src/components/layercake.

Note: You must install the module layercake first.

// UsageimportExamplefrom"$components/layercake/Example.svelte";

Actions

Located in src/actions.

// Usageimportexamplefrom"$actions/action.js";

• canTab.js: enable/disable tabbing on child elements.
• checkOverlap.js: Label overlapping detection. Loops through selection of nodes and adds a class to the ones that are overlapping. Once one is hidden it ignores it.
• focusTrap.js: Enable a keyboard focus trap for modals and menus.
• keepWithinBox.js: Offsets and element left/right to stay within parent.
• inView.js: detect when an element enters or exits the viewport.
• resize.js: detect when an element is resized.

Runes

These are located in src/runes. You can put custom ones in src/runes/misc.js or create unique files for more complex ones.

import{example}from"$runes/misc/misc.js";

• useWindowDimensions: returns an object { width, height } of the viewport dimensions. It is debounced for performance.
• useClipboard: copy content to clipboard.
• useFetcher: load async data from endpoints (local or external).
• useWindowFocus: determine if the window is in focus or not.

For more preset runes, use runed which is preloaded.

Utils

Located in src/utils/.

// Usageimportexamplefrom"$utils/example.js";

• checkScrollDir.js: Gets the user's scroll direction ("up" or "down")
• csvDownload.js: Converts a flat array of data to CSV content ready to be used as an href value for download.
• generateId.js: Generate an alphanumeric id.
• loadCsv.js: Loads and parses a CSV file.
• loadImage.js: Loads an image.
• loadJson.js: Loads and parses a JSON file.
• loadPixels.js: Loads the pixel data of an image via an offscreen canvas.
• localStorage.js: Read and write to local storage.
• mapToArray.js: Convenience function to convert a map to an array.
• move.js: transform translate function shorthand.
• transformSvg.js: Custom transition lets you apply an svg transform property with the in/out svelte transition. Parameters (with defaults):
• translate.js: Convenience function for transform translate css.
• urlParams.js: Get and set url parameters.

Tips

Image asset paths

For img tags, use relative paths:

<imgsrc="assets/demo/test.jpg" />

or use base if on a sub route:

<script>import{base}from"$app/paths";</script><imgsrc="{base}/assets/demo/test.jpg" />

For CSS background images, use absolute paths:

background:url("/assets/demo/test.jpg");

View example code in the preloaded demo.