@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, and UGE (hUGETracker) formats
• Inspect UGE files

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

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

Inspect UGE Files

beatbax inspect file.uge

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

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

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