Skip to content

README.en.md

Latest commit

 

History

History
208 lines (151 loc) · 6.48 KB

README.en.md

File metadata and controls

208 lines (151 loc) · 6.48 KB
Raw

Strudel Console

English | 한국어

A terminal-native music composition tool + MCP server powered by the Strudel live-coding engine. Live-code music in your terminal, or compose through AI agents like Claude Code.

Strudel Console TUI

Installation & Running

npm install
npm run build

TUI Mode (default)

npm start
# or
npm run tui

MCP Server Mode

npm run mcp

Register in Claude Code's settings.json:

{
  "mcpServers": {
    "strudel-console": {
      "command": "node",
      "args": ["--experimental-specifier-resolution=node", "/path/to/strudel-console/dist/mcp/server.js"]
    }
  }
}

MCP Server Spec

Transport: stdio | Protocol: MCP | Version: 0.1.0

Tools

Playback

Tool Description Parameters
evaluate Evaluate Strudel pattern code and start playback immediately code (string, required)
start Start/resume current pattern playback —
stop Stop playback —
toggle Toggle play/stop —
set_bpm Set BPM (default 120) bpm (number, positive)
get_state Query current state (playing, code, errors, etc.) —

Samples

Tool Description Parameters
load_samples Load samples/banks source (string) — github:user/repo, local path, or URL

Patterns

Tool Description Parameters
save_pattern Save pattern to ~/.strudel-console/patterns/ name (string), code (string), bpm (number, optional)
load_pattern Load a saved pattern name (string)
list_patterns List all saved patterns —

Multi-Track

Tool Description Parameters
add_track Add a new track. All active tracks play simultaneously via stack() name (string, optional), code (string, optional)
evaluate_track Update a track's pattern code and recompile code (string), track_index (int, 1-based, optional — defaults to active track)
remove_track Remove a track track_index (int, 1-based)
mute_track Toggle track mute track_index (int, 1-based)
solo_track Toggle track solo. When any track is soloed, only soloed tracks play track_index (int, 1-based)
set_track_gain Set track volume track_index (int, 1-based), gain (number, 0.0–1.0)
list_tracks List all tracks with status (name, mute, solo, gain, code) —

Mixer

Tool Description Parameters
set_master_gain Set master output volume (applies to all tracks) gain (number, 0.0–1.0)
list_effect_presets List available effect presets —

Available effect presets:

Preset Effect Chain
clean (none)
lofi .lpf(800).gain(0.8)
ambient .room(0.6).delay(0.4).gain(0.7)
dark .lpf(400).room(0.3).gain(0.9)
bright .hpf(300).lpf(8000).gain(0.9)
tape .lpf(3000).room(0.2).delay(0.15).gain(0.85)

Render

Tool Description Parameters
render_to_file Render pattern to WAV file (OfflineAudioContext) code (string, optional), cycles (int, 1–64, default 8), bpm (number, optional), filename (string, optional)

Output path: ~/.strudel-console/renders/

AI Composition

Tool Description Parameters
analyze_pattern Analyze musical properties of a pattern (key, scale, range, density) code (string), cycles (int, 1–16, default 4)
load_genre_preset Load a genre preset — auto-configures tracks + BPM and starts playback genre (string)
list_genre_presets List genre presets with descriptions —

Available genre presets:

Genre BPM Tracks Description
lofi 75 4 Chill lo-fi beats with jazzy chords
techno 130 4 Driving four-on-the-floor with acid bassline
ambient 60 3 Slow evolving pads with reverb
house 124 5 Classic house groove with organ stabs
dnb 174 3 Fast breakbeat with rolling bass
jazz 110 3 Swing feel with ii-V-I progression

Resources

URI Description
strudel-console://guide Strudel pattern writing guide (mini notation, effects, multi-track workflows)
strudel-console://music-theory Music theory reference (scales, chord progressions, rhythm patterns, intervals)

Workflow Examples

1. Single Pattern Playback

evaluate({ code: 'note("c4 e4 g4 b4").sound("sine")' })
set_bpm({ bpm: 90 })
stop()

2. Multi-Track Composition

add_track({ name: "drums", code: 's("bd sd hh sd")' })
add_track({ name: "bass", code: 'note("c2 e2 g2 e2").sound("sawtooth").lpf(400)' })
evaluate_track({ code: 's("bd sd [~ bd] sd")', track_index: 1 })
mute_track({ track_index: 2 })          // Mute bass
set_track_gain({ track_index: 1, gain: 0.8 })

3. Genre Preset → Customize

load_genre_preset({ genre: "lofi" })     // 4 tracks + 75 BPM setup
list_tracks()                            // Check current tracks
evaluate_track({ code: 's("bd ~ [bd sd] ~")', track_index: 1 })  // Modify drums
set_master_gain({ gain: 0.7 })

4. Analyze → Render

analyze_pattern({ code: 'note("c4 e4 g4 b4").sound("sine")', cycles: 4 })
render_to_file({ code: 'note("c4 e4 g4 b4").sound("sine")', cycles: 16, bpm: 90, filename: "melody" })

Error Handling

All tools return error messages with isError: true on failure.

Scenario Error Example
Invalid Strudel syntax Error: unexpected token ...
Non-existent track index Error: track 5 does not exist
Unknown genre Unknown genre. Available: lofi, techno, ambient, house, dnb, jazz
No pattern to render Error: no pattern to render. Provide code or set up tracks.
Pattern not found Error: pattern not found: ...

Tech Stack

  • Engine: @strudel/* v1.1.0 + node-web-audio-api (IRCAM Rust bindings)
  • MCP: @modelcontextprotocol/sdk (stdio transport)
  • TUI: Ink 5.x + React 18
  • Language: TypeScript (ESM)

License

This project is licensed under the GNU Affero General Public License v3.0 or later.

This is a derivative work based on Strudel (AGPL-3.0-or-later).