@beatbax/cli

Command-line interface for BeatBax chiptune live-coding language.

Overview

BeatBax CLI provides command-line tools for working with BeatBax chiptune files:

• Play .bax songs
• Verify syntax
• Export to JSON, MIDI, WAV, and UGE (hUGETracker) formats
• Convert WAV files to raw NES DMC samples
• Extract instruments from hUGETracker .uge files into a .ins kit
• Inspect UGE files

Runtime note: Node playback internals are provided by @beatbax/engine/node, and the CLI consumes that API.

Installation

npm install -g @beatbax/cli

Or use without installing:

npx @beatbax/cli play song.bax

Usage

Play a Song

beatbax play song.bax

Options:

• --headless - Play without UI (server environments)
• --loop - Loop playback

Verify Syntax

beatbax verify song.bax

Checks for syntax errors without playing.

Export Formats

JSON (ISM - Intermediate Song Model):

beatbax export json song.bax output.json

MIDI (4-track Standard MIDI File):

beatbax export midi song.bax output.mid

WAV (PCM audio):

beatbax export wav song.bax output.wav
beatbax export wav song.bax output.wav --duration 30

UGE (hUGETracker v6):

beatbax export uge song.bax output.uge

Export options:

• --verbose - Show detailed progress
• --debug - Show diagnostic information
• --strict-gb - Reject non-GB-compatible features (UGE)
• --duration - Limit export length in seconds (MIDI, WAV)

Programmatic payload builders

CLI commands call exporter plugins with outputPath. For scripts and tools, use engine payload builders directly (no filesystem write):

import { buildJSON, buildMIDI, buildUGE, buildWAVFromSong } from '@beatbax/engine/export';

const json = buildJSON(song);
const midi = buildMIDI(song);
const uge = buildUGE(song);
const wav = await buildWAVFromSong(song, { sampleRate: 44100 });

See Export architecture.

Inspect UGE Files

beatbax inspect file.uge

Shows metadata, instruments, patterns, and effects from UGE files.

Extract instruments from UGE files

beatbax extract instrument song.uge
beatbax extract instrument song.uge kit.ins
beatbax extract instrument path/to/uges --out gameboy.ins --demo gameboy-instruments-demo.bax

Pulls duty / wave / noise instruments (plus subpat programs) from hUGETracker .uge files into a BeatBax .ins kit. This is not full-song import — patterns and orders stay on the proposed beatbax convert uge command.

Useful options:

• Trailing kit.ins argument, or --out <path> — where to write the kit (default for a single file: {basename}.ins next to the source)
• --from uge — force UGE parsing when the file is not named .uge
• --stdout — print the kit; do not write a file
• --summary — counts and renames only (cannot combine with --demo)
• --demo [path] — write a tour .bax that import "local:…"s the kit and plays every name once (requires writing a kit file)
• --type pulse,wave,noise — extract a subset of channel classes
• --strict — fail if any input is missing, unknown, or fails to parse

A song then uses the kit:

chip gameboy
import "local:kit.ins"
bpm 128
channel 1 => inst Lead pat hook

Usage: beatbax extract instrument [options] <inputs...> [output.ins]

For a single .uge, omit the output path to write {basename}.ins beside the source.

Import MIDI → .bax

beatbax import midi song.mid song.bax --chip gameboy
beatbax convert midi2bax song.mid song.bax --chip nes --config mapping.json
beatbax import midi song.mid --chip gameboy --dry-run
beatbax import midi song.mid --inspect            # per-track report, writes nothing
beatbax import midi song.mid song.bax --chip gameboy --config arrange.json --annotate

Converts a Standard MIDI File into editable BeatBax source (chip kits, pat/seq reuse, drum tokens). --chip is required (gameboy | nes) except with --inspect (add --json for a JSON report). The config can place parts by bar range on binding channel lanes, pick chord reduction, tempo, window and nudge; --annotate explains what each mapping kept and dropped. See docs/features/midi-importer.md for options and config schema.

Convert WAV to NES DMC

beatbax convert wav2dmc kick.wav --dmc-rate 15 --emit-inst
beatbax convert wav2dmc kick.wav --dmc-rate 10 --trim-silence -50 --tail-ms 12 --play

This creates a raw .dmc byte stream for NES DMC playback. Input WAV files must be 16-bit PCM; other WAV encodings, including common 24-bit PCM files, are not supported. The file does not store playback settings, so the chosen --dmc-rate must match the dmc_rate= value used by the instrument:

inst kick type=dmc dmc_rate=15 dmc_loop=false dmc_sample="local:kick.dmc"

Useful options:

• --dmc-rate <0-15> / -q <0-15> - DMC playback rate used for encoding and preview (15 is the highest quality/default).
• --dmc-loop - Emit and preview the sample as a looping DMC instrument.
• --emit-inst - Print a ready-to-paste inst ... type=dmc line.
• --play - Preview the converted sample using the selected rate and loop setting.
• --trim-silence <db> / --no-trim-silence - Trim quiet tails before encoding to reduce DMC hiss.
• --tail-ms <ms> and --fade-out-ms <ms> - Keep and smooth the end of a trimmed sample.
• --max-duration-ms <ms> - Hard cap the source length before encoding.
• --ntsc / --pal - Select the DMC hardware rate table (--ntsc is the default).

Example Workflow

# Create a song
cat > mysong.bax << EOF
chip gameboy
bpm 128

inst lead type=pulse1 duty=50 env=gb:12,down,1
inst bass type=pulse2 duty=25 env=gb:10,down,1

pat melody = C4 E4 G4 C5
pat bassline = C3 . G2 .

channel 1 => inst lead pat melody
channel 2 => inst bass pat bassline
EOF

# Verify syntax
beatbax verify mysong.bax

# Play it
beatbax play mysong.bax

# Export to multiple formats
beatbax export json mysong.bax mysong.json
beatbax export midi mysong.bax mysong.mid
beatbax export uge mysong.bax mysong.uge

# Inspect the exported UGE
beatbax inspect mysong.uge

Help

Get help for any command:

beatbax --help
beatbax play --help
beatbax export --help
beatbax extract instrument --help
beatbax import midi --help
beatbax convert midi2bax --help
beatbax convert wav2dmc --help

Programmatic Usage

You can also use the CLI programmatically:

import { play, verify, exportFile } from '@beatbax/cli';

await play('song.bax');
const isValid = await verify('song.bax');
await exportFile('uge', 'song.bax', 'output.uge');

Requirements

• Node.js 16+ (18+ recommended)
• For audio playback: speaker support (automatic on most platforms)

Resources

• GitHub Repository
• Full Documentation
• Tutorial
• Engine Library

License

MIT © BeatBax Contributors