convez.ai
MCP Server
AJBogo9

supercollider-mcp

AJBogo9/supercollider-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server connecting Claude to SuperCollider with real-time playback and NRT audio rendering

Instalação

$npx convez-ai AJBogo9/supercollider-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

supercollider-mcp

An MCP server that connects Claude Code to SuperCollider, enabling AI-driven music composition with both real-time playback and non-realtime (NRT) audio rendering at 50-150x realtime speed.

Why SuperCollider?

SuperCollider is a platform for audio synthesis and algorithmic composition. Its synthesis server (scsynth) runs independently of any frontend and accepts OSC messages, making it straightforward to drive programmatically.

Two features make it well-suited for AI-assisted composition:

  • Real-time synthesis: send code, hear results immediately, iterate
  • Non-realtime (NRT) rendering: process an audio score from a file at 50-150x realtime speed -- a 5-minute piece renders in 2-4 seconds, no waiting

Requirements

  • Linux (tested on Ubuntu 24.04)
  • supercollider-server package (scsynth 3.13+)
  • PipeWire with JACK compatibility (pw-jack)
  • Python 3.11+

Install SuperCollider server only (no GUI needed):

sudo apt install supercollider-server

Create the pw-scsynth wrapper (routes scsynth through PipeWire/JACK):

cat > ~/.local/bin/pw-scsynth << 'EOF'
#!/bin/bash
exec pw-jack scsynth "$@"
EOF
chmod +x ~/.local/bin/pw-scsynth

Installation

git clone https://github.com/AJBogo9/supercollider-mcp
cd supercollider-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

MCP configuration

Add to your project's .mcp.json:

{
  "mcpServers": {
    "supercollider": {
      "command": "/path/to/supercollider-mcp/.venv/bin/python",
      "args": ["-m", "sc_mcp.server"],
      "cwd": "/path/to/supercollider-mcp"
    }
  }
}

Tools

ToolDescription
sc_bootBoot scsynth (auto-called by sc_play)
sc_pingCheck server status
sc_quitShut down scsynth
sc_play(code)Run Python/supriya code on the live server
sc_stopStop all sounds, signal song threads to exit
sc_logRead scsynth output and exec errors
sc_render(code, duration, output_path)NRT render to WAV (returns a one-line analysis summary)
sc_analyze(path)Analyze a render: loudness, dynamics, spectrum, stereo, key
save_song / load_song / list_songsSong library
save_pattern / load_pattern / list_patternsPattern snippets

SynthDef library

Six built-in SynthDefs available in every sc_play call:

  • ambient_pad -- warm slow-attack pad, good for chords
  • bass_drone -- dark low-pass sawtooth sub-bass
  • pluck_tone -- Karplus-Strong plucked string
  • noise_wind -- band-pass filtered noise (wind, breath)
  • choir_wash -- formant-filtered pink noise (choir approximation)
  • sample_one_shot -- one-shot buffer player for audio files

NRT example

sc_render("""
import random
# Simple ambient chord progression
chords = [[293, 369, 440], [247, 311, 392], [261, 329, 415]]
for i, freqs in enumerate(chords):
    for freq in freqs:
        with score.at(i * 6.0):
            s = score.add_synth(ambient_pad, freq=freq, amp=0.25,
                                attack=2.0, sustain=3.0, release=2.0)
        with score.at(i * 6.0 + 6.0):
            score.free_node(s)
with score.at(duration):
    score.do_nothing()
""", duration=20.0, output_path="/tmp/ambient.wav")

Renders 20 seconds of audio in under 0.1 seconds.

Real-time example

sc_play("""
import threading, random, time

BEAT = 60.0 / 90.0

def bass_loop():
    while not stop.is_set():
        with server.at():
            server.add_synth(bass_drone, freq=55, amp=0.4, attack=1.0, sustain=2.0, release=1.0)
        stop.wait(4 * BEAT)

def melody_loop():
    scale = [440, 494, 554, 587, 659]
    while not stop.is_set():
        with server.at():
            server.add_synth(pluck_tone, freq=random.choice(scale), amp=0.3, decay=2.0)
        stop.wait(random.uniform(0.5, 2.0))

for fn in [bass_loop, melody_loop]:
    threading.Thread(target=fn, daemon=True).start()
""")
# Stop with: sc_stop()

Audio analysis

The model can't hear the audio, so sc_analyze turns a render into measurable proxies it can reason about, closing the quality side of the loop (render -> analyze -> adjust). It reads the rendered file directly (no real-time playback or recording) and reports:

  • Loudness: integrated LUFS, loudness range, true peak (dBTP), clipping
  • Dynamics: dynamic range (peak - RMS)
  • Spectral balance: 6-band energy, spectral centroid, mud/harshness flags
  • Stereo: phase correlation, width, and a mono-bass check
  • Key: detected key/scale, to compare against what was intended
sc_render("...", duration=180.0, output_path="/tmp/track.wav")
# -> Rendered 180.0s ... Analysis: -11.9 LUFS, peak -3.0 dBTP, DR 11.3 dB, ...

sc_analyze("/tmp/track.wav")
# -> full report with per-band levels, stereo metrics, detected key, and notes

sc_render folds a one-line summary into its output automatically; call sc_analyze for the full report.

Ver o original no GitHub

Bom para

Relacionados