Skip to content

quickstart.md

Latest commit

 

History

History
194 lines (131 loc) · 3.38 KB

quickstart.md

File metadata and controls

194 lines (131 loc) · 3.38 KB

Quickstart

Groove CLI is a terminal groovebox: you create tracks, assign samples, type patterns, and hit play.

Install & run

Build and run:

cargo build --release
./target/release/groove-cli

Or during development:

cargo run --

Modes

  • Default: TUI (tracker-style UI with a command line). This is what you get with no flags.
  • Classic REPL: groove-cli --repl (line-based prompt with rustyline).

Open a song on startup

groove-cli --open songs/song.yaml
# or
groove-cli -o songs/song.yaml

In REPL mode, if you start with --open … (or if song.yaml exists in the current directory) the app will watch the file and reload audio when it changes.

Make your first beat (TUI or REPL)

All commands below work in both modes unless noted.

1) Add tracks

+ kick snare hat

Track names are single words (no spaces). You can use - name to remove them later.

2) Pick samples (with Tab completion)

Use ~ for fuzzy sample selection:

kick ~ 909/kick
snare ~ snare
hat ~ hat
  • Tab completion: in the TUI, press Tab after ~ to see matches; in the REPL, Tab completion is provided by rustyline.
  • In the TUI: when there are multiple matches, pressing Tab cycles through them and inserts the current selection into the command line.
  • Multi-word fuzzy search: kick ~ linn snare class<Tab> matches space-separated tokens (any order).
  • Paths with spaces: track ~ … accepts spaces; if you want to keep chaining more actions after the sample, use ~[ ... ] or quotes.

Example chaining (pattern + sample + gain in one line):

kick x... ~[harsh 909 kick] -3db

3) Enter patterns

kick x...x...x...x...
snare ....x.......x...
hat x.x.x.x.x.x.x.x.

You can also enter melodic note tokens (sharps + flats supported):

+ synth
synth ~ synth/C4
synth c d# eb bb
notes synth

4) Play / stop

go
.          # stop (a single dot)

Aliases: play / stop.

5) Tempo + swing

140        # typing a number sets BPM
swing 15   # 0..100 (%)

Optional: set the UI “bar length” (used for the TUI playhead display):

steps 16

Mix & performance

Gain

Track-first (recommended):

hat -6db
snare +2db

Mute / solo

hat mute
hat unmute
kick solo   # toggles

Delay (per track)

snare delay on
snare delay 1/8 0.40 0.25   # time, feedback (0..1), mix (0..1)
snare delay off

Variations (live pattern switching)

Define a variation:

kick.fill x.x.x.x.x.x.x.x.

Switch:

kick > fill
kick > main

Generate patterns with code (Rhai)

kick gen euclid(5,16)
hat gen random(0.35, 42)
snare gen fill(16)

Built-ins include: euclid(k,n), random(density, seed), fill(length), repeat(pattern, n), invert(pattern), rotate(pattern, n), humanize(pattern, amount).

AI pattern generation (OpenAI)

Set env vars (or put them in a .env file):

export OPENAI_API_KEY="..."
# optional
export OPENAI_MODEL="gpt-5.2"

Apply a suggestion directly to a track:

kick ai "four on the floor"

Or generate suggestions without applying:

ai kick "funky breakbeat"

Save / load

save my-song.yaml
open my-song.yaml

Next