Muilyzz

Advanced

CLI & agents

Muilyzz scores are built on a versioned CommandKit contract. The same commands run inside Muilyzz Studio (coach / agent) and from the Terminal as muilyzz— so Claude and other agents can produce charts without clicking through the UI.

Inside Muilyzz Studio

  • Coach / Muily Chat — theory, practice, and score help while you edit.
  • Welcome · Theory · document coach panels share one agent hub.
  • macOS: Help → Agents & CLI… explains both surfaces and installs the Terminal command.

Three surfaces, one contract

  • CommandKit — source of truth (Studio, CLI, MCP).
  • CLI — muilyzz / scripts/muilyzz-agent.
  • Doc — this page + agent pipeline (order, tempo snap).
  • MCP — stdio server at Muilyzz/mcp so Claude/Cursor load tools without re-fetching the site every turn.

Timing pipeline (agents)

  1. create score = media-linked shell only (not aligned).
  2. Download Apple preview AAC for the catalog id.
  3. analyze aac → bpm, beatTimes, spectrogram.
  4. Tempo snap: measured floats (e.g. 136.64) often become 136.5 if |Δ| ≤ ~0.35 (DAW / composer grid) — apply via set bpm.
  5. set bpm + set preview-offset (tick 0 ≈ first downbeat ms).
  6. observe aac --render overlay.png — inspect grid on spectrogram like a human.
  7. Optional match aac for full-song pin (Shazam; may fail).

MCP

# Repo: Muilyzz/mcp
cd mcp && npm install && npm start

# Claude Desktop / Cursor — mcpServers.muilyzz:
#   command: node
#   args: ["/ABS/Muilyzz/mcp/src/server.mjs"]

# Consumer smoke (analyze → snap → create .mzz):
npm run smoke

Resource muilyzz://docs/agent-pipeline carries the short policy text.

Tools

Generated from the MCP server registry — verb = category, pipeline order = permission level (read → evidence → propose → mutate).

read

  • muilyzz_inspect_scoreInspect scoreread-only

    Read a .mzz envelope and its canonical document revision before mutation.

    document

evidence

  • muilyzz_analyze_aacAnalyze AAC

    Deterministic DSP evidence from a local preview AAC/M4A: bpm, beatTimes, spectrogram, harmonyEvidence. Does not mutate .mzz. Next: muilyzz_observe_aac / muilyzz_set.

    audiooutputpreferredBpm
  • muilyzz_observe_aacObserve AAC vs grid

    Compare current score grid vs analysis; optional spectrogram overlay PNG for visual check (agent should inspect).

    documentanalysisaudiooutputrenderanalysisOutputpreferredBpmincludeSpectrogramexpectedRevision
  • muilyzz_observe_harmonyObserve harmony

    Measure key-independent, beat-synchronous chroma, absolute bass-pitch candidates, and chord-template candidates on a confirmed .mzz preview grid. Returns evidence only and never mutates the score. Next: muilyzz_interpret_harmony.

    documentaudiooutputmaximumBeatsexpectedRevision
  • muilyzz_render_guideRender guide audio

    Offline SF2 piano render of a .mzz (audition or score) to a WAV file — same compile+bounce as Studio export. Never mutates the document. This is the agent's listen gate: render the audition copy and hand the file to the user before any authored-score commit.

    documentoutputsoundfontexpectedRevision
  • muilyzz_match_aacMatch AAC (Shazam)

    Locate preview t=0 with a lossless Shazam report. Returns exactCatalog, timingEquivalentSibling, catalogMismatch, noMatch, offsetConflict, or metadataUnavailable. Passing document (+expectedRevision) additionally pins the result into the score — that mode is a mutation.

    audiocatalogIddocumentoutputinPlaceexpectedRevision

propose

  • muilyzz_interpret_harmonyInterpret harmony

    Explicitly reinterpret reusable beat evidence under one downbeat-phase hypothesis, then build bar-median dynamics, L3-B tonal evidence, L3-C structural evidence, and ranked L4 key × chord × bass hypotheses. Diatonic theory is a weak prior. Does not mutate .mzz. Next: muilyzz_write_harmony_audition.

    documentaudioevidenceoutputdownbeatPhaseShiftBeatsmaximumBeatsexpectedRevision

mutate

  • muilyzz_create_scoreCreate score shell

    Create an unaligned or partially aligned media-linked .mzz shell. It is current only when both preview position and score offset are supplied.

    titleartistcatalogIddurationMsoutputalbumartworkUrlbpmbeatsPerBarpreviewScoreOffsetMspreviewPositionMsoverwrite
  • muilyzz_write_harmony_auditionWrite harmony audition

    Apply one explicitly ranked L4 hypothesis to a separate audition .mzz. Writes canonical key-relative chord/formula/slash-bass descriptors, measured performance dynamics, and resolved absolute sound. Requires the source revision, never writes in place, and marks generated chord/bass events with AI provenance.

    documentinterpretationoutputhypothesisRankoverwriteexpectedRevision
  • muilyzz_setSet calibration field

    Set one score calibration field: bpm | meter | previewPosition | previewOffset | fullOffset. Pass exactly the parameters that field needs — bpm: value; meter: numerator+denominator; offsets/position: milliseconds. Values must come from measured evidence, not defaults.

    documentfieldvaluenumeratordenominatormillisecondsoutputinPlaceexpectedRevision

meta

  • muilyzz_helpCLI helpread-only

    List muilyzz CLI commands (same contract as Studio CommandKit). Read https://muilyzz.com/developers for agent pipeline.

Terminal CLI

After installing Studio on Mac, use Help → Install CLI for Terminal to link ~/bin/muilyzz and add $HOME/bin to your shell PATH (user-local; App Store friendly).

From a monorepo checkout (developers):

# Build & run
./scripts/muilyzz-agent help

# Create a score shell
./scripts/muilyzz-agent create score \
  --title "Song" --artist "Artist" --catalog-id 123 \
  --duration-ms 180000 --output song.mzz

# Analyze a local preview AAC
./scripts/muilyzz-agent analyze aac \
  --audio preview.m4a --output analysis.json

Full command list: muilyzz help. Shazam match commands should go through ./scripts/muilyzz-agent so the binary is signed with the Studio App ID.

External agents (Claude, etc.)

Point the agent at this page and at muilyzz help. Prefer non-destructive writes (--output instead of --in-place) unless the user explicitly wants in-place edits. Studio remains the place to hear beat playback, perform, and export for sharing.

  1. Ensure muilyzz is on PATH.
  2. Create or mutate .mzz via CommandKit.
  3. Open the file in Muilyzz Studio to listen / perform / Export.
  4. Optional: publish via Studio → web /share/ingest.

Apps

Download / TestFlight for Muilyzz (play) and Muilyzz Studio (create). Everyday listening stays on the feed — this page is for producers and automators.