mcp-flstudio 0.1.0__py3-none-any.whl

fl_studio_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""FL Studio MCP Server - Control FL Studio via Model Context Protocol."""
+
+__version__ = "0.1.0"

fl_studio_mcp/audio/__init__.py

@@ -0,0 +1 @@
+"""Audio utilities (S4 slicing)."""

fl_studio_mcp/audio/analysis.py

@@ -0,0 +1,169 @@
+"""fl_audio analyze: tempo / key / chords in pure numpy (no ML models, no extra envs).
+
+Server-side, dependency-light (numpy + the system ffmpeg for decoding):
+
+  tempo   two independent estimators over one onset envelope (log spectral flux):
+          ``autocorr`` (envelope autocorrelation) and ``tempogram`` (Fourier
+          tempogram, fundamental + 2nd harmonic). Both carry a log-normal prior at
+          120 BPM; when they disagree beyond half/double, the caller reports a gap.
+  key     Krumhansl-Kessler profiles correlated with the clip's mean chroma
+          (24 keys); ``strength`` = the Pearson r of the winner (< 0.5 = weak).
+  chords  per-beat chroma vs major/minor triad templates (cosine); quiet windows
+          are 'N'. Labels are Harte-style ('C:maj', 'A:min') for ``chord_name``.
+
+These are estimates for a producer to check by ear, not ground truth: gaps are
+reported by the caller, never hidden.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import numpy as np
+
+SR = 22050
+N_FFT = 2048
+HOP = 512
+FPS = SR / HOP
+BPM_MIN, BPM_MAX = 60.0, 200.0
+NOTES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+# Krumhansl-Kessler key profiles (C major / C minor)
+KK_MAJ = np.array([6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88])
+KK_MIN = np.array([6.33, 2.68, 3.52, 5.38, 2.60, 3.53, 2.54, 4.75, 3.98, 2.69, 3.34, 3.17])
+
+
+def load(path: Path, seconds: float = 120.0) -> np.ndarray:
+    """Mono float audio at SR, at most ``seconds`` long (any format/bit depth, via ffmpeg)."""
+    raw = subprocess.run(["ffmpeg", "-loglevel", "error", "-i", str(path), "-t", str(seconds),
+                          "-ac", "1", "-ar", str(SR), "-f", "f32le", "-"],
+                         capture_output=True, check=True, timeout=300).stdout
+    return np.frombuffer(raw, dtype=np.float32).astype(np.float64)
+
+
+def spectrogram(x: np.ndarray) -> np.ndarray:
+    """|STFT|, shape (frames, N_FFT//2 + 1)."""
+    if x.size < N_FFT:
+        x = np.pad(x, (0, N_FFT - x.size))
+    n = 1 + (x.size - N_FFT) // HOP
+    idx = np.arange(N_FFT)[None, :] + HOP * np.arange(n)[:, None]
+    return np.abs(np.fft.rfft(x[idx] * np.hanning(N_FFT), axis=1))
+
+
+def onset_envelope(mag: np.ndarray) -> np.ndarray:
+    """Half-wave-rectified log spectral flux, local mean removed, peak = 1."""
+    logm = np.log1p(100.0 * mag)
+    flux = np.maximum(0.0, np.diff(logm, axis=0)).sum(axis=1)
+    w = max(1, int(0.5 * FPS))
+    flux = np.maximum(0.0, flux - np.convolve(flux, np.ones(w) / w, mode="same"))
+    peak = flux.max() if flux.size else 0.0
+    return flux / peak if peak > 0 else flux
+
+
+def _prior(bpm: np.ndarray) -> np.ndarray:
+    return np.exp(-0.5 * (np.log2(bpm / 120.0) / 1.0) ** 2)
+
+
+def tempo_autocorr(env: np.ndarray) -> float | None:
+    if env.size < 4 * FPS:
+        return None
+    e = env - env.mean()
+    ac = np.fft.irfft(np.abs(np.fft.rfft(e, n=2 * e.size)) ** 2)[: e.size]
+    lags = np.arange(int(FPS * 60 / BPM_MAX), int(FPS * 60 / BPM_MIN) + 1)
+    lags = lags[lags < ac.size - 1]
+    if lags.size == 0 or ac[0] <= 0:
+        return None
+    score = ac[lags] / ac[0] * _prior(60 * FPS / lags)
+    i = int(np.argmax(score))
+    lag = float(lags[i])
+    if 0 < i < lags.size - 1:              # parabolic refinement of the peak
+        a, b, c = ac[lags[i] - 1], ac[lags[i]], ac[lags[i] + 1]
+        den = a - 2 * b + c
+        if den != 0:
+            lag += 0.5 * (a - c) / den
+    return 60 * FPS / lag
+
+
+def tempo_tempogram(env: np.ndarray) -> float | None:
+    if env.size < 4 * FPS:
+        return None
+    t = np.arange(env.size) / FPS
+    e = env - env.mean()
+    bpms = np.arange(BPM_MIN, BPM_MAX + 0.25, 0.25)
+
+    def mag(f: np.ndarray) -> np.ndarray:
+        return np.abs(np.exp(-2j * np.pi * f[:, None] * t[None, :]) @ e)
+
+    f = bpms / 60.0
+    score = (mag(f) + 0.5 * mag(2 * f)) * _prior(bpms)
+    return float(bpms[int(np.argmax(score))])
+
+
+def tempo(x: np.ndarray) -> dict:
+    env = onset_envelope(spectrogram(x))
+    a, b = tempo_autocorr(env), tempo_tempogram(env)
+    agree = bool(a and b and min(abs(a - b), abs(a - 2 * b), abs(2 * a - b)) / max(a, b) < 0.04)
+    bpm = a or b
+    if agree:     # the tempogram is finer; the autocorrelation picks the octave better
+        bpm = min((b / 2, b, b * 2), key=lambda v: abs(v - a))
+    r1 = lambda v: round(float(v), 1) if v else None  # noqa: E731
+    return {"bpm": r1(bpm), "bpm_alt": [r1(bpm / 2), r1(bpm * 2)] if bpm else [],
+            "autocorr": r1(a), "tempogram": r1(b), "agree": agree}
+
+
+def chroma(mag: np.ndarray) -> np.ndarray:
+    """Per-frame pitch-class energy (frames, 12), 55 Hz - 4.2 kHz."""
+    freqs = np.fft.rfftfreq(N_FFT, 1 / SR)
+    band = (freqs >= 55) & (freqs <= 4200)
+    pc = np.round(69 + 12 * np.log2(freqs[band] / 440.0)).astype(int) % 12
+    proj = np.zeros((band.sum(), 12))
+    proj[np.arange(pc.size), pc] = 1.0
+    m = mag[:, band]
+    peak = m.max() if m.size else 0.0
+    if peak > 0:
+        m = m / peak                     # level-independent compression
+    return np.log1p(100.0 * m ** 2) @ proj
+
+
+def key(x: np.ndarray) -> dict:
+    c = chroma(spectrogram(x)).sum(axis=0)
+    if c.sum() <= 0:
+        return {"key": None, "scale": None, "strength": 0.0}
+    best = (-2.0, 0, "major")
+    for root in range(12):
+        for scale, prof in (("major", KK_MAJ), ("minor", KK_MIN)):
+            r = float(np.corrcoef(c, np.roll(prof, root))[0, 1])
+            if r > best[0]:
+                best = (r, root, scale)
+    return {"key": NOTES[best[1]], "scale": best[2], "strength": round(best[0], 3)}
+
+
+def chords(x: np.ndarray, bpm: float | None = None) -> list[dict]:
+    """Chord per beat (or per 0.5 s without a tempo): [{chord, start, end, score}]."""
+    ch = chroma(spectrogram(x))
+    if ch.size == 0:
+        return []
+    win = max(1, int(round(FPS * (60.0 / bpm if bpm else 0.5))))
+    tmpl = []
+    for root in range(12):
+        for q, iv in (("maj", (0, 4, 7)), ("min", (0, 3, 7))):
+            v = np.zeros(12)
+            v[[(root + i) % 12 for i in iv]] = 1.0
+            tmpl.append((f"{NOTES[root]}:{q}", v / np.linalg.norm(v)))
+    energy = [ch[i:i + win].sum() for i in range(0, ch.shape[0], win)]
+    floor = 0.05 * float(np.median([e for e in energy if e > 0] or [0.0]))
+    out = []
+    for k, i in enumerate(range(0, ch.shape[0], win)):
+        v = ch[i:i + win].mean(axis=0)
+        start, end = i / FPS, min(i + win, ch.shape[0]) / FPS
+        if energy[k] <= floor or not v.any():
+            out.append({"chord": "N", "start": start, "end": end, "score": None})
+            continue
+        v = v - v.min()                  # drop the broadband floor before matching
+        n = np.linalg.norm(v)
+        if n == 0:
+            out.append({"chord": "N", "start": start, "end": end, "score": None})
+            continue
+        lab, s = max(((lab, float(t @ v / n)) for lab, t in tmpl), key=lambda p: p[1])
+        out.append({"chord": lab, "start": start, "end": end, "score": round(s, 3)})
+    return out

fl_studio_mcp/audio/slicer.py

@@ -0,0 +1,283 @@
+"""S4.1: audio slicing — onset boundaries → slice files + manifest.
+
+Server-side, no MIDI. Pipeline:
+
+  1. read the audio (wav via stdlib; anything else decoded to mono float
+     with the system ffmpeg)
+  2. onset detection (half-wave-rectified flux peak-picking — the same
+     class as librosa's superflux,
+     implemented in pure numpy so the MCP server stays dependency-light)
+  3. boundaries: ``onset`` grid = detected onsets (min-gap merged);
+     ``16``/``32`` grid = uniform 16th/32nd-note steps at the given BPM
+  4. each slice is extracted, **declicked** (3 ms raised-cosine edge
+     fades) and written as a 16-bit mono wav under
+     ``fl-studio-mcp/.generated/slices/<song>/`` (git-ignored, rule 9/10)
+  5. manifest JSON: per-slice start/len (seconds + samples), energy →
+     velocity (40..127, relative to the loudest slice), a coarse
+     key guess (chroma mode over the whole clip), and the grid cell.
+
+The manifest is the contract for S4.3 (``fl_load_slices``) and S4.2
+(Edison region scripts): one entry per slice, in order.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+import wave
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+AUDIO_EXTS = {".wav", ".mp3", ".m4a", ".flac", ".ogg", ".aiff", ".aif"}
+
+#: slices shorter than this (seconds) are merged into their neighbour
+MIN_SLICE_S = 0.06
+HOP_S = 0.005          # 5 ms analysis hop (~882 frames/s at 44.1k)
+MIN_GAP_S = 0.08       # hits closer than this keep the stronger
+
+
+# ---------------------------------------------------------------------------
+# Reading
+# ---------------------------------------------------------------------------
+def read_mono(path: Path, sr: int = 44100) -> np.ndarray:
+    """Return the file as mono float64 in [-1, 1] at ``sr``."""
+    path = Path(path)
+    if not path.is_file():
+        raise FileNotFoundError(path)
+    if path.suffix.lower() == ".wav":
+        with wave.open(str(path), "rb") as w:
+            n_ch, sw, fr = w.getnchannels(), w.getsampwidth(), w.getframerate()
+            raw = w.readframes(w.getnframes())
+        if sw == 2:
+            data = np.frombuffer(raw, dtype="<i2").astype(np.float64) / 32768.0
+        elif sw == 1:
+            data = (np.frombuffer(raw, dtype=np.uint8).astype(np.float64)
+                    - 128.0) / 128.0
+        else:
+            raise ValueError(f"unsupported wav bit depth {sw * 8}")
+        if n_ch > 1:
+            data = data.reshape(-1, n_ch).mean(axis=1)
+        if fr != sr:
+            data = _resample(data, fr, sr)
+        return data
+    # non-wav: decode with ffmpeg to raw f32le mono
+    with tempfile.TemporaryDirectory() as td:
+        tmp = Path(td) / "decoded.raw"
+        subprocess.run(
+            ["ffmpeg", "-y", "-i", str(path), "-ac", "1", "-ar", str(sr),
+             "-f", "f32le", "-c:a", "pcm_f32le", str(tmp)],
+            check=True, capture_output=True)
+        data = np.fromfile(str(tmp), dtype=np.float32).astype(np.float64)
+    return data
+
+
+def _resample(x: np.ndarray, sr0: int, sr1: int) -> np.ndarray:
+    if sr0 == sr1:
+        return x
+    n = int(len(x) * sr1 / sr0)
+    if n == 0:
+        return x
+    xp = np.linspace(0.0, 1.0, num=len(x), endpoint=False)
+    xq = np.linspace(0.0, 1.0, num=n, endpoint=False)
+    return np.interp(xq, xp, x)
+
+
+# ---------------------------------------------------------------------------
+# Onsets (HWR flux peak-picking)
+# ---------------------------------------------------------------------------
+def onset_times(audio: np.ndarray, sr: int,
+                min_gap_s: float = MIN_GAP_S,
+                threshold_pct: float = 50.0) -> list[float]:
+    """Onset times (seconds) via half-wave-rectified flux peak-picking.
+
+    The threshold is the higher of the flux mean and the ``threshold_pct``
+    percentile of the (0..1 normalised) flux. A pure mean+k·std threshold
+    is dominated by the loudest transients (kicks) and starves the quiet
+    ones (hats); the percentile floor adapts to the instrument mix. Raise
+    ``threshold_pct`` for dense, noisy material.
+    """
+    hop = max(1, int(sr * HOP_S))
+    pad = (-len(audio)) % hop
+    if pad:
+        audio = np.concatenate([audio, np.zeros(pad)])
+    n_frames = len(audio) // hop
+    if n_frames < 1:
+        return []
+    frames = np.asarray([audio[i * hop:(i + 1) * hop]
+                         for i in range(n_frames)], dtype=np.float64)
+    # half-wave rectification
+    hwr = np.maximum(0.0, frames)
+    diff = np.diff(hwr, axis=0, prepend=hwr[:1])
+    flux = diff.sum(axis=1) / max(1, hwr.shape[1])
+    if len(flux) < 3 or flux.max() < 1e-6:
+        return []
+    flux = flux / flux.max()
+    mean = float(flux.mean())
+    thresh = max(mean, float(np.percentile(flux, threshold_pct)))
+    cand: list[tuple[float, float]] = []
+    for i in range(1, len(flux) - 1):
+        if flux[i] > thresh and flux[i] >= flux[i - 1] and flux[i] > flux[i + 1]:
+            cand.append((i * HOP_S, float(flux[i])))
+    # min-gap: keep the stronger of overlapping candidates
+    cand.sort(key=lambda c: c[0])
+    out: list[float] = []
+    last_t = -1e9
+    for t, e in cand:
+        if t - last_t >= min_gap_s:
+            out.append(round(t, 3))
+            last_t = t
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Boundaries
+# ---------------------------------------------------------------------------
+def boundaries(duration_s: float, grid: str = "onset", bpm: float = 0.0,
+               onsets: list[float] | None = None,
+               min_slice_s: float = MIN_SLICE_S) -> tuple[list[float], dict]:
+    """Slice boundary times (start with 0.0, end with duration).
+
+    grid: ``onset`` (detected, min-gap merged), ``16`` (16th notes at bpm),
+    ``32`` (32nd notes at bpm).
+    """
+    if grid == "onset":
+        raw = [0.0] + sorted(t for t in (onsets or []) if 0 < t < duration_s)
+        if not raw or raw[-1] < duration_s:
+            raw.append(round(duration_s, 3))
+        merged = [raw[0]]
+        for t in raw[1:]:
+            if t - merged[-1] >= min_slice_s:
+                merged.append(t)
+            # else: drop the closer onset (merged into the previous slice)
+        if merged[-1] < duration_s:
+            merged[-1] = round(duration_s, 3)
+        meta = {"grid": "onset", "n_onsets": len(onsets or [])}
+        return merged, meta
+    if grid in ("16", "32"):
+        if not bpm:
+            raise ValueError(f"grid={grid!r} needs bpm")
+        bpm = float(bpm)
+        div = 4 if grid == "16" else 8
+        step = 60.0 / bpm / div
+        out = [0.0]
+        t = step
+        while t < duration_s - 1e-6:
+            out.append(round(t, 3))
+            t += step
+        out.append(round(duration_s, 3))
+        meta = {"grid": grid, "bpm": bpm, "step_s": round(step, 5)}
+        return out, meta
+    raise ValueError(f"unknown grid {grid!r} (onset|16|32)")
+
+
+# ---------------------------------------------------------------------------
+# Per-slice features
+# ---------------------------------------------------------------------------
+def slice_features(s: np.ndarray, sr: int, rmax: float) -> dict:
+    rms = float(np.sqrt(np.mean(np.square(s)))) if len(s) else 0.0
+    vel = 40 + int(round(87 * min(1.0, rms / rmax))) if rmax > 0 else 80
+    return {"rms": round(rms, 5), "velocity": int(min(127, max(40, vel)))}
+
+
+def estimate_key(audio: np.ndarray, sr: int) -> str | None:
+    """Coarse key guess: 12-bin chroma mode over the whole clip."""
+    if len(audio) < sr:
+        return None
+    x = np.ascontiguousarray(audio[: min(len(audio), sr * 30)])
+    n = len(x)
+    fft = np.fft.rfft(x * np.hanning(n))
+    mag = np.abs(fft)
+    freqs = np.fft.rfftfreq(n, 1.0 / sr)
+    bins = np.zeros(12)
+    for f, m in zip(freqs, mag):
+        if f < 60 or f > 5000:
+            continue
+        midi = round(69.0 + 12.0 * np.log2(f / 440.0))
+        if midi < 0:
+            continue
+        bins[midi % 12] += m
+    if bins.max() <= 0:
+        return None
+    names = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"]
+    return names[int(bins.argmax())]
+
+
+def _declick(a: np.ndarray, sr: int, ms: float = 3.0) -> np.ndarray:
+    n = int(sr * ms / 1000)
+    a = a.copy()
+    if n * 2 < len(a) and n > 0:
+        fade = 0.5 * (1 - np.cos(np.linspace(0, np.pi, n)))
+        a[:n] *= fade
+        a[-n:] *= fade[::-1]
+    return a
+
+
+def write_wav16(path: Path, a: np.ndarray, sr: int) -> None:
+    pcm = np.clip(a, -1.0, 1.0)
+    pcm = (pcm * 32767.0).astype("<i2")
+    with wave.open(str(path), "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(sr)
+        w.writeframes(pcm.tobytes())
+
+
+# ---------------------------------------------------------------------------
+# Driver
+# ---------------------------------------------------------------------------
+def slice_audio(path: Path, out_root: Path, song: str,
+                grid: str = "onset", bpm: float = 0.0,
+                sr: int = 44100) -> dict[str, Any]:
+    """Run the whole pipeline; returns the manifest dict and writes
+    slice wavs + manifest.json under ``out_root/song/``."""
+    audio = read_mono(path, sr)
+    duration = len(audio) / sr
+    onsets = onset_times(audio, sr)
+    bounds, meta = boundaries(duration, grid=grid, bpm=bpm, onsets=onsets)
+
+    out_dir = out_root / song
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    slices = []
+    rmax = 0.0
+    segs = []
+    for i in range(len(bounds) - 1):
+        s0, s1 = int(bounds[i] * sr), int(min(len(audio), bounds[i + 1] * sr))
+        seg = audio[s0:s1]
+        r = float(np.sqrt(np.mean(np.square(seg)))) if len(seg) else 0.0
+        rmax = max(rmax, r)
+        segs.append((seg, s0, s1))
+    for i, (seg, s0, s1) in enumerate(segs):
+        clean = _declick(seg, sr)
+        fname = f"slice_{i:03d}.wav"
+        write_wav16(out_dir / fname, clean, sr)
+        feat = slice_features(seg, sr, rmax)
+        slices.append({
+            "index": i,
+            "file": fname,
+            "start_s": round(s0 / sr, 3),
+            "len_s": round(max(0, s1 - s0) / sr, 3),
+            "start_sample": s0,
+            "len_samples": max(0, s1 - s0),
+            "velocity": feat["velocity"],
+            "rms": feat["rms"],
+        })
+    manifest: dict[str, Any] = {
+        "song": song,
+        "source": str(path),
+        "sr": sr,
+        "duration_s": round(duration, 3),
+        "grid": meta.get("grid", grid),
+        "bpm": meta.get("bpm", bpm or 0),
+        "key_guess": estimate_key(audio, sr),
+        "n_slices": len(slices),
+        "slices": slices,
+        "note": ("Generated by fl_slice_audio; private learning material — "
+                 "not for shared datasets (rule 10)."),
+    }
+    (out_dir / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
+    manifest["manifest_path"] = str(out_dir / "manifest.json")
+    return manifest