Introduction

Pro music tools sound real because real drummers don't play to grid: every hit moves a few milliseconds, every velocity drifts. This repo is a plain-text drum-tab format that compiles to humanized MIDI and streams it into Logic (or any DAW) over a virtual MIDI bus. You write five lines of K/S/H/T1/T2, save the file, and Superior Drummer plays it back through your kit: with timing jitter, velocity ranges, swing, flams and accents already baked in.

Quickstart

First, follow note/begin.md once to enable the macOS IAC virtual MIDI port and load Superior Drummer 3 in Logic. Then:

npm install -g @cluesurf/beat

Save this as calm.beat:

instrument: drumkit
tempo: 88
humanize: subtle

measure: 4*4
C|X---:----:----:----|
H|x-x-:x-x-:x-x-:x-x-|
S|----:x---:----:x---|
K|x---:--x-:--x-:----|

Run it:

beat ./calm.beat

It loops forever, reloads on save, and plays through Logic. Hit Ctrl-C to stop.

What's in here

beat/
├── code/             # the engine (parser, scheduler, MIDI export, humanize)
├── test/             # songs (each in text.beat / code.ts / data.ts forms)
├── text/             # the .beat VS Code syntax-highlighter extension
├── note/             # docs (spec, drum defaults, roadmap, syntax, etc.)
├── package.json
├── pnpm-workspace.yaml
├── tsconfig.json
└── vitest.config.ts

Examples

Test songs live at test/<name>/ and may exist in three equivalent representations:

| File | What it is | | ----------- | -------------------------------------------------------------------------------------------------------- | | text.beat | Text drum tab: see note/tab/spec.md and note/tab/drum.md | | code.ts | Imperative TypeScript DSL (NOTE constants) | | data.ts | Pure data (raw MIDI note numbers) |

pnpm play <name> picks the first format it finds (text.beat first by default). Override with --format beat | code | data | text.

# test/basic/text.beat
instrument: drumkit
tempo: 100

measure: 4*4
H|x-x-:x-x-:x-x-:x-x-|
S|----:x---:----:x---|
K|x---:----:x---:----|

Running

Prerequisite: macOS IAC bus configured + Logic Pro listening. Full setup at note/begin.md.

pnpm list:ports                              # verify "TS Drum Engine" port
pnpm try                                     # quick sanity hit
pnpm play                                    # default song
pnpm play tool/grudge                        # play a specific song
pnpm play tool/grudge --part bridge-2        # specific part
pnpm play tool/grudge --pattern bar-007      # solo one bar
pnpm play tool/grudge --from 17 --to 32      # play a region
pnpm play tool/grudge --humanize loose       # drag + jitter
pnpm export tool/grudge                      # write a .mid file

Syntax highlighter

The VS Code extension lives in text/. Top-level scripts:

pnpm text:make    # build the .vsix
pnpm text:load    # build + install into VS Code
pnpm text:login   # vsce login cluesurf (one-time)
pnpm text:host    # publish to the marketplace

See note/syntax.md for the full layout, scope table, and dev loop.

Tests

pnpm exec vitest run             # 31 tests covering the tab parser

Docs

• note/tab/spec.md: generic tab format spec
• note/tab/drum.md: drumkit defaults
• note/superior-drummer-control.md : what SD3 lets us program
• note/tool-drum-sound.md: Tool-style SD3 setup
• note/syntax.md: .beat syntax highlighter
• note/roadmap.md: what's next

License

MIT

ClueSurf

Made by ClueSurf, meditating on the universe ¤. Follow the work on YouTube, X, Instagram, Substack, Facebook, and LinkedIn, and browse more of our open-source work here on GitHub.