@dsebastien/music-notation 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastien Dubois
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# Music Notation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Chord diagrams, piano keyboards, fretboards and ChordPro charts, rendered as SVG and HTML from small text blocks. No framework, no build step for pages that load the browser bundle. Made for [Obsidian](https://obsidian.md) (the [Music Practice](https://github.com/dsebastien/obsidian-music-practice) plugin and Obsidian Publish), usable on any web page.
+
+![Chord diagrams, a piano chord, a keyboard, a fretboard and a chord chart](docs/images/overview.png)
+
+## Blocks
+
+Each block is a fenced code block whose language says what it draws:
+
+````markdown
+```chord
+A x02220 x01230
+```
+
+```chord
+C/G
+instrument: piano
+fingering: 5-1-2-4
+```
+
+```keyboard
+D dorian
+labels: degrees
+```
+
+```fretboard
+scale: A minor pentatonic
+frets: 5-8
+labels: intervals
+```
+
+```chords
+{title: Example}
+{key: G}
+[G]Hello [D/F#]little [Em]world
+```
+````
+
+The full syntax is in the [guide](https://dsebastien.github.io/music-notation/). Mistakes show an inline message and leave the source untouched.
+
+## Install
+
+```bash
+npm install @dsebastien/music-notation
+```
+
+```ts
+import { renderBlock, injectStyles } from '@dsebastien/music-notation'
+import { lookupGuitarVoicing } from '@dsebastien/music-notation/voicings'
+
+injectStyles(document)
+const result = renderBlock('chord', 'Am', container, { voicings: lookupGuitarVoicing })
+if (!result.ok) console.warn(result.error)
+```
+
+- `renderBlock(language, source, host, options)` appends the rendering to `host` and never throws. It returns `{ ok, el, error, destroy() }`.
+- `@dsebastien/music-notation/voicings` adds about 2,000 guitar voicings (`chord` blocks with only a symbol). It's a separate entry point because the data weighs about 230 KB.
+- The renderers (`renderGuitarDiagram`, `renderKeyboard`, `renderFretboard`, `renderChart`), the parsers and the theory helpers (`parseChord`, `transposeChord`, `chordNoteSet`, `scaleNoteSet`…) are exported too.
+- Styles: `injectStyles(document)`, or ship `@dsebastien/music-notation/music-notation.css`. Colors follow Obsidian's theme variables, with fallbacks for any page.
+
+## Obsidian Publish
+
+Add this to your site's `publish.js`. It loads the bundle only on pages that have notation blocks:
+
+```js
+;(() => {
+    const VERSION = '0.1.0'
+    const SELECTOR = ['chord', 'chords', 'keyboard', 'fretboard']
+        .map((l) => `pre > code.language-${l}`)
+        .join(', ')
+    let requested = false
+    const load = () => {
+        if (requested || !document.querySelector(SELECTOR)) return
+        requested = true
+        const script = document.createElement('script')
+        script.src = `https://cdn.jsdelivr.net/npm/@dsebastien/music-notation@${VERSION}/dist/music-notation.publish.min.js`
+        document.head.appendChild(script)
+    }
+    load()
+    new MutationObserver(load).observe(document.body, { childList: true, subtree: true })
+})()
+```
+
+The bundle renders every block, now and as you navigate, and hides a block's source only once it rendered.
+
+## Roadmap
+
+- 0.1: chord diagrams (guitar, piano), keyboards, fretboards, ChordPro charts, the Publish bundle.
+- 0.2: tabs and scores (alphaTab) with playback, imports (Guitar Pro, MusicXML, text tabs, chords over lyrics).
+
+## Credits and licenses
+
+MIT. Built on [tonal](https://github.com/tonaljs/tonal) (MIT) for music theory and [chords-db](https://github.com/tombatossals/chords-db) (MIT) for guitar voicings.
+
+## News & support
+
+To stay up to date about this library, Obsidian in general, personal knowledge management and note-taking:
+
+- Subscribe to [my newsletter](https://dsebastien.net/newsletter)
+- Subscribe to [my YouTube channel](https://youtube.com/@dsebastien)
+- Join the [Knowii community](https://www.store.dsebastien.net/product/knowii-community/)
+
+If this is useful to you:
+
+- [Become a GitHub Sponsor](https://github.com/sponsors/dsebastien)
+- [Buy me a coffee](https://www.buymeacoffee.com/dsebastien)
+- [Check out my products](https://store.dsebastien.net)

package/dist/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,57 @@
+# Third-party licenses
+
+## tonal
+
+Shipped in: music-notation.publish.min.js
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015 danigb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## @tombatossals/chords-db
+
+Shipped in: voicings/index.js, music-notation.publish.min.js
+
+```
+MIT License
+
+Copyright (c) 2016 David Rubert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/blocks/block-source.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Block sources: `key: value` lines, with an optional first line that has no key (the shorthand:
+ * "A x02220 x01230"). Keys are case-insensitive; the last value wins.
+ */
+export interface BlockSource {
+    /** The first line when it has no `key:`; null otherwise. */
+    head: string | null;
+    fields: Map<string, string>;
+}
+export declare function parseBlockSource(source: string): BlockSource;
+/** "5-8", "5", "0 - 12" → [from, to]; null when invalid. */
+export declare function parseRange(text: string): [number, number] | null;

package/dist/blocks/note-set-field.d.ts

@@ -0,0 +1,8 @@
+/** Shared by keyboard and fretboard blocks: which notes to show and how to label them. */
+import type { BlockSource } from './block-source.js';
+import { type NoteLabel, type NoteSet } from '../theory/note-set.js';
+/** `scale:`, `chord:` or `notes:`; a shorthand first line is tried as each, in that order. */
+export declare function noteSetOf(block: BlockSource): NoteSet;
+/** `labels:`; `fingers` only where fingering was given (piano chords). */
+export declare function labelField(block: BlockSource, fallback: NoteLabel, fingers?: boolean): NoteLabel;
+export declare function orFail<T>(value: T | null, message: string): T;

package/dist/blocks/renderers.d.ts

@@ -0,0 +1,16 @@
+import type { VoicingLookup } from '../voicings/index.js';
+export interface RenderOptions {
+    /** Finds guitar voicings for chord blocks that only give a symbol (see `/voicings`). */
+    voicings?: VoicingLookup;
+    /** Semitones to transpose chord charts by. */
+    transpose?: number;
+}
+export type Renderer = (doc: Document, source: string, options: RenderOptions) => Element;
+/** Block languages (code fence names) and their renderers. */
+export declare const RENDERERS: {
+    chord: Renderer;
+    chords: Renderer;
+    keyboard: Renderer;
+    fretboard: Renderer;
+};
+export type NotationLanguage = keyof typeof RENDERERS;

package/dist/chord/guitar.d.ts

@@ -0,0 +1,24 @@
+/** Standard tuning, lowest string first. */
+export declare const STANDARD_TUNING: number[];
+export interface FrettedVoicing {
+    /** Absolute frets, lowest string first: null = muted, 0 = open. */
+    frets: (number | null)[];
+    /** Finger per string ("1".."4", "T"); null = none. */
+    fingers: (string | null)[];
+    /** First fret shown; computed when absent. */
+    baseFret?: number;
+}
+export interface GuitarDiagramOptions {
+    title?: string;
+    /** Chroma of the chord's root: its dots are marked. */
+    root?: number | null;
+    /** Open-string pitches (MIDI), lowest first. */
+    tuning?: number[];
+}
+/** "x02220", "x-10-12-12-11-10", "x 10 12 12 11 10" → frets; null when invalid. */
+export declare function parseFrets(text: string): (number | null)[] | null;
+/** "x01230", "x-1-3-4-2-1", "x 1 3 4 2 1" → fingers; 0 and x mean no finger. */
+export declare function parseFingers(text: string): (string | null)[];
+/** The first fret shown: 1 when the chord fits in the first 4 frets, else its lowest fretted fret. */
+export declare function baseFretOf(frets: (number | null)[]): number;
+export declare function renderGuitarDiagram(doc: Document, voicing: FrettedVoicing, options?: GuitarDiagramOptions): SVGElement;

package/dist/chords/chart.d.ts

@@ -0,0 +1,6 @@
+import type { Song } from './chordpro.js';
+export interface ChartOptions {
+    /** Semitones added to the song's own `{transpose}`. */
+    transpose?: number;
+}
+export declare function renderChart(doc: Document, song: Song, options?: ChartOptions): HTMLElement;

package/dist/chords/chordpro.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A ChordPro subset: metadata directives, sections (verse, chorus, bridge, tab, grid), comments,
+ * `[C]` chords inside lyrics, `{transpose: n}`. Unknown directives are ignored.
+ */
+export interface Segment {
+    chord: string | null;
+    text: string;
+}
+export type Line = {
+    kind: 'lyrics';
+    segments: Segment[];
+} | {
+    kind: 'comment';
+    text: string;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'empty';
+};
+export interface Section {
+    kind: 'verse' | 'chorus' | 'bridge' | 'tab' | 'grid' | 'none';
+    label: string | null;
+    lines: Line[];
+}
+export interface Song {
+    title: string | null;
+    subtitle: string | null;
+    artist: string | null;
+    key: string | null;
+    capo: number | null;
+    tempo: string | null;
+    time: string | null;
+    transpose: number;
+    sections: Section[];
+}
+/** Split "[C]Hello [G]world" into chord/text segments. */
+export declare function parseLyrics(line: string): Segment[];
+export declare function parseChordPro(source: string): Song;