plainscore 0.1.0 → 0.1.1

package/README.md

@@ -1,18 +1,25 @@
 # plainscore
 
-A plain-text score format that a musician can read without docs and an AI can edit line by line. One file holds the music; plainscore turns it into timed note events, MIDI and ABC notation.
+> A plain-text music score. One `.score` file reads like a composer's sketch, edits line by line, and compiles to ABC notation, MIDI and timed note events. TypeScript, no runtime dependencies.
+
+![Manuscript paper and a fountain pen](docs/images/hero.jpg)
+
+![song.score on the left; the sheet plainscore engraves from it on the right](docs/images/score-to-sheet.png)
+
+<details>
+<summary><code>song.score</code> as text</summary>
 
 ```
 score 0.1
 
-title   Small Waltz in 4
+title   Evening Song
 by      You
 
 instruments
   piano  piano
   cello  cello
 
-piece waltz  Small Waltz
+piece song  Evening Song
   tempo  q = 72
   key    G major
 
@@ -41,71 +48,38 @@ piece waltz  Small Waltz
       tune, comp p, pad 80%, pedal
 ```
 
-## What it can say
-
-- **Pitches as written**, durations `w h q e s` with dots and ties, bars separated by `|`.
-- **Chord-relative patterns**: write a figure once with `bass`, `t1`–`t4`, `top`, `upper`, and it follows the chords.
-- **Form as an orchestration table**: each section row names the parts that play and how loud (`85%`, `92%-75%`, `bars 3-4`, `on 1 and 3`, `8va`, `in E`).
-- **Loop**: `form loop`, or `form loop from A1` for an intro that plays once.
-- **Variants**: versions of one piece that share a timeline (`drop P`, `Q for P`, `P <options>`).
-- **Doubles**: `part strings violins doubles tune 8vb` plays another part's notes on its own instrument.
-- **Pedal, rolls, staggered entries, ad lib.** (seeded random notes), and a **mix** block for playback balance that notation and MIDI ignore.
+</details>
 
-The full reference is [docs/grammar.md](docs/grammar.md). Every score can carry the standard legend (`plainscore legend`) so a reader never needs this README.
+![The form of examples/bgm.score: each section row names the parts that play, and how loud](docs/images/form.png)
 
-## Use
+![One file, four outputs: check, events, ABC, MIDI](docs/images/outputs.png)
 
-```bash
-pnpm add -D plainscore
-```
-
-```bash
-plainscore check song.score
-plainscore abc song.score --piece waltz > song.abc
-plainscore midi song.score --piece waltz -o song.mid
-plainscore events song.score --variant quiet --seed 7 --passes 2
-plainscore legend
-```
+- Install: `pnpm add -D plainscore` (Node 20+).
+- CLI: `plainscore check|abc|midi|events|legend <file> [--piece id] [--variant v] [--seed n] [--passes n] [-o out.mid]`.
+- API: `render(parseScore(text, file), piece, { variant, seed })`, then `toAbc(r)` or `toMidi(r)`.
+- Staves follow `instruments`. The family (`piano harp violins violas cello bass flute oboe clarinet bassoon horn trumpet voice synth`) sets clef, MIDI program and pedal. A piano `lead` gets a Melody staff; `pizz.` gets its own staff.
+- Not in 0.1: meters other than 4/4, tuplets, ties across barlines, tempo changes, hairpins, repeats with endings, imports, percussion.
 
-```ts
-import { parseScore, render } from 'plainscore'
-import { toAbc } from 'plainscore/abc'
-import { toMidi } from 'plainscore/midi'
+## Docs
 
-const score = parseScore(text, 'song.score')
-const rendering = render(score, 'waltz', { variant: null, seed: 1 })
-const abc = toAbc(rendering)
-const midi = toMidi(rendering)
-```
+- [Grammar](docs/grammar.md): every keyword of score 0.1, with examples
+- [Legend](src/legend.ts): the legend a score can carry so readers need no docs; `plainscore legend`
+- [llms.txt](llms.txt): this index, for agents
 
-`render` returns plain data: metadata, sections, key changes, every note with its onset in eighths, offset, length, level and velocity, pedal changes, and the ad lib. rules. A player only needs that.
+## Examples
 
-## Notation and MIDI
+- [bgm.score](examples/bgm.score): two pieces with variants, loop, ad lib. and mix
+- [road.score](examples/road.score): a full single for piano, harp and strings
 
-Staves come from the declared instruments, in declaration order:
-
-- each instrument gets a staff, and `pizz.` parts get their own staff right after it;
-- a `lead` part on a piano gets a Melody staff on top;
-- pianos get a grand staff with pedal marks, and an `inner` part becomes a voice of its own;
-- clefs, MIDI programs and pedal come from the instrument's family (`piano harp violins violas cello bass flute oboe clarinet bassoon horn trumpet voice synth`).
-
-The ABC targets [abcjs](https://www.abcjs.net/) 6.x. plainscore has no runtime dependencies and does not render; pass the ABC to abcjs, or to any ABC tool.
-
-## Limits of 0.1
-
-4/4 only; the smallest grid is the eighth (with `late s` for sixteenth offsets); no tuplets, ties across barlines, tempo changes, hairpins, articulations beyond `pizz.`/`arco`, repeats with endings, imports or percussion.
-
-## Develop
-
-```bash
-pnpm install
-pnpm test
-pnpm typecheck
-pnpm build
-```
+## API
 
-`fixtures/` holds the expected ABC, MIDI and events for `examples/`. After an intended output change, run `pnpm test -u` and review the fixture diff.
+- [plainscore](src/index.ts): `parseScore`, `render`, `checkScore`, `layout`, `seeded`
+- [plainscore/abc](src/abc/index.ts): `toAbc(rendering)`, ABC for abcjs 6
+- [plainscore/midi](src/midi.ts): `toMidi(rendering)`, SMF type 1, 480 PPQ, pedal as CC64
+- [plainscore/legend](src/legend.ts): `LEGEND`
 
-## License
+## Optional
 
-MIT
+- [Fixtures](fixtures): expected ABC, MIDI and events for the examples; run `pnpm test -u` after an intended change
+- [package.json](package.json): `pnpm test`, `pnpm typecheck`, `pnpm build`
+- [License](LICENSE): MIT

package/docs/grammar.md

@@ -0,0 +1,183 @@
+# score 0.1 grammar
+
+A score is a UTF-8 text file. Indentation carries structure: file-level lines start at column 0, a piece's blocks at 2 spaces, block rows at 4, and form entries deeper than 4. Lines starting with `#` are comments. Anything after ` — ` (an em dash between spaces) on a line is a note to the reader and is ignored.
+
+## File
+
+```
+score 0.1                       the first line, always
+
+title   Small Waltz             optional, file-wide
+by      You                     optional; written as "Music by You"
+after   A song I love           optional; written as "After A song I love"
+
+instruments
+  piano    piano                <name>  <family>
+  strings  violins
+
+piece waltz  Small Waltz        <id>  <title>; a file can hold several pieces
+  …
+```
+
+- Families: `piano harp violins violas cello bass flute oboe clarinet bassoon horn trumpet voice synth`. The family sets the clef, MIDI program, pedal and how notes are engraved. The instrument name is yours.
+- Instrument names and part names must differ.
+
+## Piece header
+
+```
+  meter   4/4          only 4/4 in 0.1
+  tempo   q = 80
+  key     D major      major minor dorian lydian mixolydian
+```
+
+## Pitches, durations, counts
+
+- Pitches sound as written: `C4` is middle C, `F#5`, `Bb3`.
+- Durations: `w h q e s` (whole to sixteenth), `.` dotted (`q.`), `+` ties (`w+s`, `h+q`).
+- `r` is a rest in bar lines.
+- Counts are beats and ands: `1 1& 2 2& 3 3& 4 4&`. `2.3&` means bar 2, the and of 3.
+
+## Chords
+
+```
+  chords theme  — bass | voicing
+    D        D2  | D4 F#4 A4
+    A/C#     C#2 | C#4 E4 A4
+    D                              a symbol alone reuses its last voicing
+
+  chords stars  two bars each      one … four, or a number
+    Dmaj9(#11)  D2 | D3 A3 F#4 C#5 E5 G#5
+```
+
+A section is as long as the chord set it names.
+
+## Parts
+
+Every part has a name and, unless each cue names one, an instrument. Header words, in any order:
+
+| word | meaning |
+|---|---|
+| `piano`, `violins pizz.` | the instrument, optionally with `pizz.` or `arco` |
+| `p`, `mf` … | the part's dynamic |
+| `overlap e` | each note rings an eighth past its value |
+| `ring w` | each note rings for a whole note |
+| `once` | counts are within the section (`3.2&`), not repeated per chord |
+| `lead` | the tune: breaths leave it ringing; on a piano it gets the Melody staff |
+| `inner` | engraved as a voice of its own on its staff |
+| `doubles P [8vb]` | plays part P's notes on this part's instrument |
+| `ad lib.` | random notes from rules (below) |
+
+### Bars
+
+```
+  part tune  piano  mf  overlap e  lead
+    | F#5 h   E5 q   D5 q  | E5 h.   A4 q  |
+    | mp D6 h   B5 q   D6 q | … |               a dynamic before a note applies from there
+```
+
+Each bar must add up to a whole note.
+
+### Cues
+
+One line per entry: `<count> [instrument] <pitches> <duration> [options]`. A cue part repeats with every chord.
+
+```
+  part flow  piano
+    1     bass        w   >
+    1&    fifth       q.  soft
+    2&    t2          q.  soft  late s
+    1     chord       h   soft  roll 30ms
+    1     cello  bass+8va  w+s  f
+```
+
+- Chord tones:
+  - `bass`; `t1`–`t4` / `v1`–`v6` are voicing tones from low to high; `top` is the highest.
+  - `chord` is all of them; `upper` is all but the lowest.
+  - `fifth` is the chord tone nearest a fifth above the bass.
+- Shifts: `+5th` (a perfect fifth up, in the chord or not), `+8va`, `+15ma`, `+8vb`, `+15mb`.
+- Options:
+  - A dynamic, or a rising roll such as `ppp-mf`.
+  - `>` accent, `soft`, `softer`.
+  - `roll X`: the notes enter X apart.
+  - `late X`: enters X after the count.
+  - X is a duration or a time in ms (`30ms`).
+- Pedal: `1  Ped.` presses or changes the sustain pedal; `4&  *` lifts it.
+
+### Ad lib.
+
+```
+  part sparkle  harp  ad lib.
+    chance   22%
+    notes    D lydian, D6 to C#7, 8va 30% of the time
+    dynamic  pppp-pp
+    length   h.
+    timing   anywhere within the eighth        or sixteenth, quarter
+    avoid    quote                             optional: skip eighths where this part plays
+```
+
+## Dynamics
+
+`pppp .10  ppp .16  pp .22  p .32  mp .42  mf .50  f .55`. Accent adds .08, `soft` takes away .07 and `softer` takes away .14.
+
+## Form
+
+```
+  form  loop from A1
+    Intro  prelude  — 序
+      wash mp, stream p 85%, drone pp 85% bars 1-2, pedal, breath
+    A1  theme
+      flow p 85%, theme 85%, pedal
+    A5  theme in E
+      flow mp, theme f 8va, pedal
+```
+
+- Header:
+  - `form`: plays once.
+  - `form loop`: repeats from the top.
+  - `form loop from A1`: plays through, then repeats from A1.
+- Each row is `<mark> <chord set> [in <key>]`, then the parts that play, comma-separated.
+- A part not named in a row is silent there. Every part must play somewhere.
+- Part options:
+  - A dynamic.
+  - `85%` shades the part; `92%-75%` shades it bar by bar.
+  - `bars 3-4`.
+  - `on 1 and 3`: only notes that start on those beats.
+  - A shift: `8va`, `8vb`.
+- `breath`: every part but `lead` and `once` parts stops for the last eighth.
+- `cut`: whatever still rings stops at the downbeat.
+- Both also lift the pedal.
+
+## Variants
+
+```
+  variants
+    overview
+    browse   drop stream
+    read     drop stream, sparse for flow, melody on 1 and 3
+```
+
+The first variant plays the form as written. The others edit every form row:
+
+- `drop P`: P is silent everywhere.
+- `Q for P`: Q plays wherever P was named, with P's options.
+- `P <options>`: adds options to P wherever it plays.
+
+All variants share one timeline.
+
+## Mix
+
+```
+  mix  — playback only; notation and MIDI ignore it
+    violin-theme   +13 dB  attack 200ms
+    piano          75%
+```
+
+Rows name a part or an instrument.
+
+## Errors
+
+Every error names the file and line, and says what to write instead:
+
+```
+song.score line 18: "+3" is mixing; put it in the piece's mix block
+```

package/llms.txt

@@ -0,0 +1,72 @@
+# plainscore
+
+> A plain-text music score. One `.score` file reads like a composer's sketch, edits line by line, and compiles to ABC notation, MIDI and timed note events. TypeScript, no runtime dependencies.
+
+```
+score 0.1
+
+title   Evening Song
+by      You
+
+instruments
+  piano  piano
+  cello  cello
+
+piece song  Evening Song
+  tempo  q = 72
+  key    G major
+
+  chords verse  — bass | voicing
+    G      G2 | B3 D4 G4
+    D/F#   F#2 | A3 D4 F#4
+    Em     E2 | B3 E4 G4
+    C      C3 | C4 E4 G4
+
+  part tune  piano  mf  overlap e  lead
+    | B4 h   A4 q   G4 q | A4 w | G4 h   B4 h | C5 w |
+
+  part comp  piano
+    1    bass   w   >
+    2    upper  q   soft
+    3&   upper  e   softer
+
+  part pad  cello  mp
+    1    bass+8va  w
+
+  part pedal
+    1    Ped.
+
+  form  loop
+    A  verse
+      tune, comp p, pad 80%, pedal
+```
+
+- Install: `pnpm add -D plainscore` (Node 20+).
+- CLI: `plainscore check|abc|midi|events|legend <file> [--piece id] [--variant v] [--seed n] [--passes n] [-o out.mid]`.
+- API: `render(parseScore(text, file), piece, { variant, seed })`, then `toAbc(r)` or `toMidi(r)`.
+- Staves follow `instruments`. The family (`piano harp violins violas cello bass flute oboe clarinet bassoon horn trumpet voice synth`) sets clef, MIDI program and pedal. A piano `lead` gets a Melody staff; `pizz.` gets its own staff.
+- Not in 0.1: meters other than 4/4, tuplets, ties across barlines, tempo changes, hairpins, repeats with endings, imports, percussion.
+
+## Docs
+
+- [Grammar](https://raw.githubusercontent.com/Innei/plainscore/main/docs/grammar.md): every keyword of score 0.1, with examples
+- [Legend](https://raw.githubusercontent.com/Innei/plainscore/main/src/legend.ts): the legend a score can carry so readers need no docs; `plainscore legend`
+- [README](https://github.com/Innei/plainscore#readme): the same index with pictures
+
+## Examples
+
+- [bgm.score](https://raw.githubusercontent.com/Innei/plainscore/main/examples/bgm.score): two pieces with variants, loop, ad lib. and mix
+- [road.score](https://raw.githubusercontent.com/Innei/plainscore/main/examples/road.score): a full single for piano, harp and strings
+
+## API
+
+- [plainscore](https://raw.githubusercontent.com/Innei/plainscore/main/src/index.ts): `parseScore`, `render`, `checkScore`, `layout`, `seeded`
+- [plainscore/abc](https://raw.githubusercontent.com/Innei/plainscore/main/src/abc/index.ts): `toAbc(rendering)`, ABC for abcjs 6
+- [plainscore/midi](https://raw.githubusercontent.com/Innei/plainscore/main/src/midi.ts): `toMidi(rendering)`, SMF type 1, 480 PPQ, pedal as CC64
+- [plainscore/legend](https://raw.githubusercontent.com/Innei/plainscore/main/src/legend.ts): `LEGEND`
+
+## Optional
+
+- [Fixtures](https://github.com/Innei/plainscore/tree/main/fixtures): expected ABC, MIDI and events for the examples; run `pnpm test -u` after an intended change
+- [package.json](https://raw.githubusercontent.com/Innei/plainscore/main/package.json): `pnpm test`, `pnpm typecheck`, `pnpm build`
+- [License](https://raw.githubusercontent.com/Innei/plainscore/main/LICENSE): MIT

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "plainscore",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A plain-text score format a musician can read and an AI can edit, with MIDI and ABC export.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Innei/plainscore.git"
+  },
+  "homepage": "https://github.com/Innei/plainscore#readme",
+  "keywords": [
+    "music",
+    "score",
+    "notation",
+    "abc",
+    "midi",
+    "dsl",
+    "composer"
+  ],
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -17,7 +31,9 @@
     "./legend": "./dist/legend.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs/grammar.md",
+    "llms.txt"
   ],
   "devDependencies": {
     "@types/node": "^24.19.2",