CLI tool
scribbletune/scribbletune avatar
scribbletune/scribbletune

Scribbletune accepts five progression formats and ignores two

Create music with JavaScript

3,783 stars237 forksTypeScriptMIT

At a glance

What is it?
A JavaScript library and command line tool that write MIDI from pattern strings, where one positional argument accepts five input formats and two of them make the other positional arguments no-ops, the documentation recommends one-based note ordering while the library's own example uses zero-based, and the manifest sits one patch ahead of the newest tag.
Who is it for?
Scribbletune is worth a look if you want to generate MIDI programmatically rather than draw it, because the notation is five characters and the command line tool reaches the same features without a build step. Two things to know first.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 94 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • scribbletune/scribbletune3,783 ★ · +11
Star history
Repository2026-09-242026-11-21
scribbletune/scribbletune3.8k3.8k

11 Stars in the last 58 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One argument takes five formats, and two of them make the others no-ops

The chord and arpeggio commands share a positional shape, root then mode then pattern then subdivision, and then a progression field that is not a pattern and not a chord list in any single sense. Five things are accepted there.

bash
1645            # degree digits
"I IV vi V"     # roman numerals (space separated)
I,IV,vi,V       # roman numerals (comma separated)
random          # generated progression
CM-FM-Am-GM     # explicit chord names (`root` and `mode` are ignored)

The last line's comment is the finding. With explicit chord names, the first two positional arguments you had to supply are discarded, so `C3 major xxxx 1m CM-FM-Am-GM` parses the root and the mode and throws them away. That is a reasonable design and a poor error surface, because nothing in the grammar tells you which of your four leading arguments just stopped mattering, and a mistyped root produces output rather than a complaint.

The documentation recommends one-based ordering and the example uses zero-based

Arpeggio note order inside each chord is controlled by an `--order` argument, and the page is careful about it. One-based order is supported, with `1234` and `2143` given as examples, and it is recommended. Zero-based order is also accepted for backward compatibility, with `0123` and `1032`. The problem is what the library section does. The arpeggio example there calls the function with `order: "0123"`, which is the form the command line documentation discourages, so the shortest example on the page teaches the compatibility path rather than the recommended one. It is a small thing, and it is exactly the kind of drift that a compatibility promise tends to produce, because nothing breaks when the old form is used.

The manifest is one patch ahead of the newest tag

The package manifest reads version 5.5.5. The newest release tag is v5.5.4, published at the end of February 2026, and the last commit to the default branch is dated 2026-08-20, so roughly six months of commits sit past that tag with the version already incremented once. The older tags are further apart still: v5.0.1 from September 2022 and v5.0.2 from January 2024. That is a patch line that went quiet and then resumed, which fits a library whose releases follow the feature set rather than a calendar. The two descriptions also differ slightly, with the repository summary reading Create music with JavaScript and the npm manifest reading Create music with JavaScript and Node.js, so the published metadata is the more specific of the two.

Travis and nyc are still in the tree beside Biome and Vitest

The root carries configuration from at least three eras of the JavaScript toolchain, and they are not consistent with each other. There is a `.travis.yml`, which belongs to a continuous integration service this project does not appear to use, and a `.nycrc.json`, which configures a coverage tool that is not in the scripts. The test script runs Vitest, and coverage runs `vitest run --coverage`, which uses Vitest's own coverage provider rather than nyc. Meanwhile the current configuration is coherent: Biome supplies the linter, the formatter and the checker, with one `biome.json` and three scripts over it, Vitest supplies the tests through `vitest.config.ts`, and tsup supplies the build through `tsup.config.ts`. So the project has clearly modernised, and has not deleted the evidence of what it replaced.

Two dependencies, one of them the author's own, and Tone.js is not among them

The runtime dependency list has two entries. One is a MIDI package scoped to the project's own organisation, so the file format handling is split out. The other is a separate `harmonics` package, and the page credits it explicitly for scales and chords, linking to its own repository, so the music theory layer is a second split. Everything else is a development dependency: Biome, tsup, typedoc, TypeScript and Vitest. The gap worth noticing is the browser path. The browser entry point adds Session, Channel and live clip support on top of Tone.js, both browser examples use it, and the standalone sample clip fetches a sound file from the project's own site, yet Tone.js does not appear anywhere in the manifest. A browser consumer has to bring it themselves.

Five characters describe a rhythm, and two of them break shell quoting

The notation is small enough to learn in a minute.

js
"x---x---x-x-x---"; // basic kick pattern
"[xx][xx]x-x-"; // hihat with subdivisions
"x___"; // one long sustained note

`x` is a note on, a dash is a rest, the `_` character sustains the previous note, `R` is a random note drawn from a pool, and brackets subdivide a beat. Two conveniences sit on top: a string repeat, and a prefix and suffix repeat shorthand for when you cannot use a method call inside a literal. The cost is shell quoting, and the page says so directly, telling you to quote a pattern in single quotes if it uses brackets, because the shell would otherwise treat them as a glob. A notation that collides with the command line is normal, but it means every riff containing a subdivision has to be quoted, and the examples carry those quotes inconsistently.

A repeated style letter reuses the same random choices

Riff sections are built from a style string of letters, one section per letter, and the page explains the consequence in a detail that is easy to skim past. With a style of AABC and a pattern, you get four sections named A, A, B and C, and repeated letters reuse the exact same generated section, with the same rhythm and the same notes, including the random choices that the `R` symbol made the first time. So the randomness is resolved once per distinct letter rather than per repetition. That is a sensible way to make a riff coherent, and it is also a behaviour you cannot discover from the output alone: a section that sounds deliberately varied on repeat may simply be a single frozen draw.

The published package is the build output and nothing else

The manifest publishes one directory.

code
"files": [
  "dist"
]

So the source, the twelve example scripts, the documentation output and the RunKit shim at the root are all excluded from what npm serves. The package still exposes three surfaces: a main entry with types, an import and a require condition, a separate browser entry with the same pair, and a command line binary pointing at a different file in the same output directory. That is a tidy layout, and it means the CLI is a separate artefact from the library even though they ship as one package. It also means anyone who wants to read the implementation has to come to the repository, since the installed artefact is minified output with type declarations.

Editorial conclusion

Scribbletune is worth a look if you want to generate MIDI programmatically rather than draw it, because the notation is five characters and the command line tool reaches the same features without a build step. Two things to know first. The tool takes root and mode as positional arguments and then ignores both when you supply explicit chord names, which is a trap in a grammar that otherwise feels exact. And the published package contains only the build output, so the source you read in the repository is not what ends up installed.

Frequently asked questions

What is Scribbletune?

A library for creating music with JavaScript, using simple strings and arrays to craft rhythms, melodies and chord progressions. It can export MIDI files, play them live in the browser with Tone.js, and ships a command line tool that emits a MIDI file straight from a terminal.

What is coding music?

The repository does not define the phrase. What it documents is its own notation, where x is a note on, a dash is a rest, a low line holds the note, R is a random note and brackets subdivide a beat, plus a command line taking a root, a mode, a pattern and a subdivision.

How do I install and run the Scribbletune CLI?

Install with npm. A global install gives you a scribbletune command, while a local install means using npx scribbletune instead. The subcommands are riff, chord and arp, sharing the shape root, mode, pattern and subdivision, with the chord and arp forms adding a progression argument.

How do I write a chord progression in Scribbletune?

Five ways in a single argument: degree digits such as 1645, space-separated roman numerals, comma-separated roman numerals, the word random, or explicit chord names such as CM-FM-Am-GM. With explicit chord names the root and mode arguments are currently ignored.

How do I use Scribbletune in a browser?

Import Session from the browser entry point, create a channel with an instrument and a list of clips, then await Tone.start() before starting the transport, because the browser requires a user gesture first. A standalone sample clip form takes a pattern and a sample URL instead of a Session.

Does Scribbletune need Tone.js?

For the browser entry point, yes: that entry adds Session, Channel and live clip support on top of Tone.js, and both browser examples use it. Tone.js does not appear in the manifest. The two declared runtime dependencies are the project's own MIDI package and a separate harmonics package that supplies scales and chords.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. scribbletune/scribbletune on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/scribbletune-scribbletune.svg)](https://hysenlabs.com/projects/scribbletune-scribbletune)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/scribbletune-scribbletune.svg)](https://hysenlabs.com/projects/scribbletune-scribbletune)

Was this useful?