claude-music 1.0.0 → 1.1.0

package/README.md

@@ -15,9 +15,20 @@ npm install -g claude-music   # or: pnpm add -g claude-music
 claude-music install
 ```
 
-`claude-music install` downloads the prebuilt audio daemon and the model, registers
-the MCP server with Claude Code, and installs the `/music` command. **Restart Claude
-Code** afterwards so it loads the MCP server, then:
+`claude-music install` downloads the prebuilt audio daemon and a model, registers
+the MCP server with Claude Code, and installs the `/music` command. In a terminal it
+prompts for which model to use; pass `--model small|base` to choose without a prompt:
+
+```
+claude-music install --model small   # ~0.5 GB, realtime on any Apple Silicon (default)
+claude-music install --model base    # ~2.8 GB, higher quality, realtime on M2 Pro+
+```
+
+**Small** is the default — smallest download and realtime on any Apple Silicon, so it's
+the safe pick for older Macs. **Base** sounds better and runs in realtime on M2 Pro and
+above (and usually on M1 too). The ~1.4 GB of shared resources download once and are
+reused by both, so switching models only re-downloads the model itself. **Restart Claude
+Code** after installing so it loads the MCP server, then:
 
 ```
 /music          # start — Claude picks an opening vibe
@@ -32,7 +43,7 @@ changes, and music stops when you end the session.
 
 - **Apple-Silicon Mac** (M-series) — required by MLX/Metal.
 - **Node ≥ 18** and the **`claude`** CLI (Claude Code).
-- ~1.3 GB of disk for the model, downloaded on first install.
+- ~1.7 GB of disk for the model + resources, downloaded on first install.
 
 No Xcode, CMake, or Python needed — the daemon ships as a prebuilt binary. (If a
 prebuilt binary can't be fetched, `install` falls back to building from source,

package/dist/__tests__/download.test.js

@@ -1,25 +1,32 @@
 import { describe, it, expect } from "vitest";
-import { MODEL_FILES } from "../download.js";
-import { MODEL_FILE, RESOURCES_DIR, MAGENTA_HOME } from "../paths.js";
-describe("MODEL_FILES", () => {
-    it("includes the compiled small model and its state", () => {
-        expect(MODEL_FILES).toContain("models/mrt2_small/mrt2_small.mlxfn");
-        expect(MODEL_FILES).toContain("models/mrt2_small/mrt2_small_state.safetensors");
+import { RESOURCE_FILES, modelFiles } from "../download.js";
+import { modelMlxfn, MAGENTA_HOME, RESOURCES_DIR } from "../paths.js";
+describe("model + resource file lists", () => {
+    it("model files cover the compiled model and its state", () => {
+        expect(modelFiles("small")).toEqual([
+            "models/mrt2_small/mrt2_small.mlxfn",
+            "models/mrt2_small/mrt2_small_state.safetensors",
+        ]);
+        expect(modelFiles("base")).toEqual([
+            "models/mrt2_base/mrt2_base.mlxfn",
+            "models/mrt2_base/mrt2_base_state.safetensors",
+        ]);
     });
     it("includes all musiccoca and spectrostream resources", () => {
-        const musiccoca = MODEL_FILES.filter((f) => f.startsWith("resources/musiccoca/"));
-        const spectrostream = MODEL_FILES.filter((f) => f.startsWith("resources/spectrostream/"));
+        const musiccoca = RESOURCE_FILES.filter((f) => f.startsWith("resources/musiccoca/"));
+        const spectrostream = RESOURCE_FILES.filter((f) => f.startsWith("resources/spectrostream/"));
         expect(musiccoca).toHaveLength(6);
         expect(spectrostream).toHaveLength(4);
     });
-    it("has no duplicate entries", () => {
-        expect(new Set(MODEL_FILES).size).toBe(MODEL_FILES.length);
+    it("has no duplicate resource entries", () => {
+        expect(new Set(RESOURCE_FILES).size).toBe(RESOURCE_FILES.length);
     });
 });
 describe("paths", () => {
-    it("derives the model + resources paths from the magenta home", () => {
-        expect(MODEL_FILE.startsWith(MAGENTA_HOME)).toBe(true);
+    it("derives model paths under the magenta home from the model key", () => {
+        expect(modelMlxfn("small").startsWith(MAGENTA_HOME)).toBe(true);
+        expect(modelMlxfn("small").endsWith("models/mrt2_small/mrt2_small.mlxfn")).toBe(true);
+        expect(modelMlxfn("base").endsWith("models/mrt2_base/mrt2_base.mlxfn")).toBe(true);
         expect(RESOURCES_DIR.startsWith(MAGENTA_HOME)).toBe(true);
-        expect(MODEL_FILE.endsWith("models/mrt2_small/mrt2_small.mlxfn")).toBe(true);
     });
 });

package/dist/cli.js

@@ -5,7 +5,9 @@ const USAGE = `claude-music — live AI background music for Claude Code
 
 Usage:
   claude-music install        Download the daemon + model, register the MCP
-                              server, and install the /music command.
+                              server, and install the /music command. Prompts
+                              for a model on a terminal; pass --model small|base
+                              to choose non-interactively (default: small).
   claude-music uninstall      Remove the MCP registration and /music command.
                               (add --purge to also delete the cached binary + model)
   claude-music doctor         Check that everything is installed correctly.
@@ -22,7 +24,7 @@ async function main() {
             await runServer();
             return; // server keeps the process alive on the stdio transport
         case "install":
-            await install();
+            await install(rest);
             break;
         case "uninstall":
             await uninstall(rest.includes("--purge"));

package/dist/download.js

@@ -5,15 +5,12 @@ import * as path from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { fileURLToPath } from "node:url";
-import { MAGENTA_HOME } from "./paths.js";
+import { MAGENTA_HOME, MODELS } from "./paths.js";
 const HF_REPO = "google/magenta-realtime-2";
 const HF_BASE = `https://huggingface.co/${HF_REPO}/resolve/main`;
-// The complete set of files the mrt2d daemon needs at runtime: the compiled
-// small model + its state, and the shared musiccoca / spectrostream resources.
-// All are public on HuggingFace and download without auth.
-export const MODEL_FILES = [
-    "models/mrt2_small/mrt2_small.mlxfn",
-    "models/mrt2_small/mrt2_small_state.safetensors",
+// Shared musiccoca / spectrostream resources, needed by every model. All are
+// public on HuggingFace and download without auth.
+export const RESOURCE_FILES = [
     "resources/musiccoca/audio_preprocessor.tflite",
     "resources/musiccoca/mapper.tflite",
     "resources/musiccoca/music_encoder.tflite",
@@ -25,6 +22,14 @@ export const MODEL_FILES = [
     "resources/spectrostream/quantizer.safetensors",
     "resources/spectrostream/spectrostream_encoder.mlxfn",
 ];
+/** The two files specific to a given model: its compiled .mlxfn + state. */
+export function modelFiles(key) {
+    const { name } = MODELS[key];
+    return [
+        `models/${name}/${name}.mlxfn`,
+        `models/${name}/${name}_state.safetensors`,
+    ];
+}
 function humanBytes(n) {
     if (n >= 1 << 30)
         return `${(n / (1 << 30)).toFixed(2)} GiB`;
@@ -77,18 +82,19 @@ async function downloadFile(url, dest, label) {
     console.log(`    ${label}: done (${humanBytes(received)})`);
 }
 /**
- * Download all model + resource files into MAGENTA_HOME, skipping any file that
- * already exists locally with the same size as the remote. Returns how many
- * files were actually fetched.
+ * Download the chosen model + the shared resources into MAGENTA_HOME, skipping
+ * any file that already exists locally with the same size as the remote.
+ * Returns how many files were actually fetched.
  */
-export async function downloadModel() {
+export async function downloadModel(key) {
+    const files = [...modelFiles(key), ...RESOURCE_FILES];
     let fetched = 0;
-    console.log(`==> Downloading model + resources to ${MAGENTA_HOME}`);
-    for (let i = 0; i < MODEL_FILES.length; i++) {
-        const rel = MODEL_FILES[i];
+    console.log(`==> Downloading ${MODELS[key].name} + resources to ${MAGENTA_HOME}`);
+    for (let i = 0; i < files.length; i++) {
+        const rel = files[i];
         const dest = path.join(MAGENTA_HOME, rel);
         const url = `${HF_BASE}/${rel}`;
-        const tag = `[${i + 1}/${MODEL_FILES.length}] ${rel}`;
+        const tag = `[${i + 1}/${files.length}] ${rel}`;
         if (fs.existsSync(dest)) {
             const local = fs.statSync(dest).size;
             const remote = await remoteSize(url);

package/dist/install.js

@@ -2,9 +2,10 @@ import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import * as readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { downloadBinary, downloadModel } from "./download.js";
-import { BIN_DIR, CLAUDE_MUSIC_HOME, COMMANDS_DIR, DAEMON_BIN, MAGENTA_HOME, MODEL_FILE, MUSIC_COMMAND, RESOURCES_DIR, } from "./paths.js";
+import { BIN_DIR, CLAUDE_MUSIC_HOME, COMMANDS_DIR, DAEMON_BIN, DEFAULT_MODEL, MAGENTA_HOME, modelMlxfn, MODELS, MUSIC_COMMAND, readConfig, RESOURCES_DIR, RESOURCES_MB, writeConfig, } from "./paths.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, "..");
 const CLI_JS = path.join(__dirname, "cli.js");
@@ -182,18 +183,73 @@ function installCommand() {
     fs.copyFileSync(TEMPLATE_MUSIC, MUSIC_COMMAND);
 }
 // ---------------------------------------------------------------------------
+// model selection
+// ---------------------------------------------------------------------------
+/** Parse a model choice from CLI args (`--model base|small`, `--base`, `--small`). */
+function modelFromArgs(args) {
+    const i = args.indexOf("--model");
+    const val = i >= 0 ? args[i + 1] : undefined;
+    if (val === "base" || args.includes("--base"))
+        return "base";
+    if (val === "small" || args.includes("--small"))
+        return "small";
+    if (val !== undefined) {
+        throw new Error(`unknown --model '${val}' (expected 'small' or 'base')`);
+    }
+    return undefined;
+}
+function ask(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => rl.question(question, (a) => {
+        rl.close();
+        resolve(a.trim());
+    }));
+}
+/** Interactive model picker (only used on a TTY). */
+async function promptModel() {
+    const totalSmall = ((MODELS.small.approxMB + RESOURCES_MB) / 1024).toFixed(1);
+    const totalBase = ((MODELS.base.approxMB + RESOURCES_MB) / 1024).toFixed(1);
+    console.log("\nWhich model would you like?");
+    console.log(`  1) ${MODELS.small.label}  — ${MODELS.small.note}`);
+    console.log(`  2) ${MODELS.base.label}   — ${MODELS.base.note}`);
+    console.log(`     (total first-time download incl. shared resources: ` +
+        `~${totalSmall} GB small / ~${totalBase} GB base)`);
+    const answer = await ask("Choose [1]: ");
+    return answer === "2" || answer.toLowerCase() === "base" ? "base" : "small";
+}
+/**
+ * Resolve which model to install: an explicit flag wins; otherwise prompt on an
+ * interactive terminal; otherwise fall back to the default (keeps the
+ * one-command, non-interactive flow working in scripts/CI).
+ */
+async function resolveModel(args) {
+    const flagged = modelFromArgs(args);
+    if (flagged)
+        return flagged;
+    if (process.stdin.isTTY && process.stdout.isTTY)
+        return promptModel();
+    return DEFAULT_MODEL;
+}
+// ---------------------------------------------------------------------------
 // entry points
 // ---------------------------------------------------------------------------
-export async function install() {
+export async function install(args = []) {
     preflight();
+    const model = await resolveModel(args);
+    console.log(`==> Model: ${MODELS[model].name}`);
     await ensureBinary();
-    await downloadModel();
+    await downloadModel(model);
+    writeConfig({ model });
     await registerMcp();
     installCommand();
     console.log("");
-    console.log("claude-music installed.");
+    console.log(`claude-music installed (${MODELS[model].name}).`);
     console.log("  Restart Claude Code, then type /music to start. It steers itself as you");
     console.log("  work and stops when you end the session.");
+    console.log("  Switch models anytime: claude-music install --model small|base");
 }
 export async function uninstall(purge) {
     console.log("==> Removing mrt2-mcp registration...");
@@ -212,7 +268,9 @@ export async function doctor() {
     const platformOk = process.platform === "darwin" && process.arch === "arm64";
     const claudeOk = have("claude");
     const binOk = fs.existsSync(DAEMON_BIN);
-    const modelOk = fs.existsSync(MODEL_FILE);
+    const model = readConfig().model;
+    const modelPath = modelMlxfn(model);
+    const modelOk = fs.existsSync(modelPath);
     const resourcesOk = fs.existsSync(RESOURCES_DIR);
     let mcpOk = false;
     const r = spawnSync("claude", ["mcp", "list"], { encoding: "utf8" });
@@ -223,7 +281,7 @@ export async function doctor() {
     console.log(`  [${ok(platformOk)}] platform: ${process.platform}/${process.arch}`);
     console.log(`  [${ok(claudeOk)}] claude CLI on PATH`);
     console.log(`  [${ok(binOk)}] daemon binary: ${DAEMON_BIN}`);
-    console.log(`  [${ok(modelOk)}] model: ${MODEL_FILE}`);
+    console.log(`  [${ok(modelOk)}] model (${MODELS[model].name}): ${modelPath}`);
     console.log(`  [${ok(resourcesOk)}] resources: ${RESOURCES_DIR}`);
     console.log(`  [${ok(mcpOk)}] mrt2-mcp registered`);
     console.log(`  [${ok(cmdOk)}] /music command: ${MUSIC_COMMAND}`);

package/dist/paths.js

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 // Central path constants for claude-music. Everything the installer writes and
@@ -13,10 +14,46 @@ export const BIN_DIR = path.join(CLAUDE_MUSIC_HOME, "bin");
  * fallback, which leaves the binary inside the magenta-realtime build tree).
  */
 export const DAEMON_BIN = process.env.MRT2D_BIN || path.join(BIN_DIR, "mrt2d");
-/** Where the model + shared resources are downloaded. The daemon hardcodes this. */
+/** Where the model + shared resources are downloaded. The daemon defaults here. */
 export const MAGENTA_HOME = path.join(HOME, "Documents", "Magenta", "magenta-rt-v2");
-export const MODEL_FILE = path.join(MAGENTA_HOME, "models", "mrt2_small", "mrt2_small.mlxfn");
 export const RESOURCES_DIR = path.join(MAGENTA_HOME, "resources");
+/** Shared resources (musiccoca + spectrostream) add ~1.4 GB regardless of model. */
+export const RESOURCES_MB = 1376;
+export const MODELS = {
+    small: {
+        name: "mrt2_small",
+        label: "Small",
+        approxMB: 464,
+        note: "~0.5 GB · realtime on any Apple Silicon (default)",
+    },
+    base: {
+        name: "mrt2_base",
+        label: "Base",
+        approxMB: 2788,
+        note: "~2.8 GB · higher quality · realtime on M2 Pro and above",
+    },
+};
+export const DEFAULT_MODEL = "small";
+/** Absolute path to a model's compiled .mlxfn for the given key. */
+export function modelMlxfn(key) {
+    const { name } = MODELS[key];
+    return path.join(MAGENTA_HOME, "models", name, `${name}.mlxfn`);
+}
+export const CONFIG_FILE = path.join(CLAUDE_MUSIC_HOME, "config.json");
+/** Read the persisted config, defaulting to the small model. */
+export function readConfig() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+        return { model: raw.model === "base" ? "base" : "small" };
+    }
+    catch {
+        return { model: DEFAULT_MODEL };
+    }
+}
+export function writeConfig(cfg) {
+    fs.mkdirSync(CLAUDE_MUSIC_HOME, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n");
+}
 /** Runtime artefacts created by the daemon. */
 export const SOCKET_PATH = path.join(HOME, ".mrt2d.sock");
 export const PID_PATH = path.join(HOME, ".mrt2d.pid");

package/dist/server.js

@@ -5,7 +5,7 @@ import * as fs from "node:fs";
 import * as net from "node:net";
 import { z } from "zod";
 import { buildVibeMessage } from "./vibe.js";
-import { DAEMON_BIN, LOG_PATH, PID_PATH, SOCKET_PATH } from "./paths.js";
+import { DAEMON_BIN, LOG_PATH, modelMlxfn, PID_PATH, readConfig, RESOURCES_DIR, SOCKET_PATH, } from "./paths.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Can we actually connect to the daemon's socket right now? */
 export function socketAlive() {
@@ -29,17 +29,34 @@ export async function ensureDaemon() {
     if (!fs.existsSync(DAEMON_BIN)) {
         throw new Error(`mrt2d not installed at ${DAEMON_BIN} — run: claude-music install`);
     }
+    // Launch the model the user selected at install time (defaults to small).
+    const modelPath = modelMlxfn(readConfig().model);
+    // Fail fast with an actionable message if the model/resources are missing,
+    // rather than spawning a daemon that exits immediately and waiting it out.
+    if (!fs.existsSync(modelPath) || !fs.existsSync(RESOURCES_DIR)) {
+        throw new Error(`model not found at ${modelPath} — run: claude-music install`);
+    }
     const out = fs.openSync(LOG_PATH, "a");
-    const child = spawn(DAEMON_BIN, [], {
+    const child = spawn(DAEMON_BIN, ["--model", modelPath, "--resources", RESOURCES_DIR], {
         detached: true,
         stdio: ["ignore", out, out],
     });
+    // Detect an early crash (e.g. a corrupt/partial model) so we don't sit through
+    // the full timeout. The daemon stays alive past unref() on success.
+    let exitCode = null;
+    child.on("exit", (code) => {
+        exitCode = code ?? 1;
+    });
     child.unref();
     // Model load is fast for mrt2_small (~2s) but allow generous headroom.
     for (let i = 0; i < 60; i++) {
         await sleep(1000);
         if (await socketAlive())
             return;
+        if (exitCode !== null) {
+            throw new Error(`mrt2d exited during startup (code ${exitCode}) — check ${LOG_PATH}. ` +
+                `If the model is incomplete, re-run: claude-music install`);
+        }
     }
     throw new Error(`daemon did not come up within 60s — check ${LOG_PATH}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-music",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Live AI background music for Claude Code, scored in real time by Claude itself (Magenta RealTime 2 on Apple Silicon).",
   "type": "module",
   "bin": {