BeatScope Director

GIF
WebMCP Director focusing and comparing measured visual ranges inside the BeatScope player.

Inspiration

BeatScope started from a simple problem: music visualizations often look impressive, but the timing logic behind them is usually locked inside one demo. I wanted to turn musical timing into reusable, deterministic data that could drive different visual systems — and also be understood by coding agents.

The WebMCP Challenge made it possible to take that idea one step further: instead of making an agent inspect the DOM or guess how the player works, BeatScope can expose its musical state directly as structured browser tools.

What it does

BeatScope Director adds an in-browser WebMCP collaboration layer to BeatScope.

An AI agent can inspect the loaded track, query timing and energy at any moment, read bounded musical events, find visually interesting ranges, compare sections, focus the timeline, control playback, and create loops — all inside the same player the user is watching.

It currently exposes eight WebMCP tools through document.modelContext.registerTool(), including:

get_project_context
get_state_at_time
get_events
find_visual_moments
compare_ranges
focus_range
control_playback
set_loop_range

The agent does not receive the source audio. It works from BeatScope's already-computed analysis, while the user's normal local upload and playback workflow remains unchanged.

How I built it

I kept BeatScope's existing architecture and analysis pipeline intact and added WebMCP as a separate browser integration layer.

Both the existing stdio MCP server and the new WebMCP Director read the same Rhythm IR and deterministic runtime, so they describe the same track with the same semantics; only the transport and lifecycle are different.

The WebMCP layer is split into schemas, queries, actions, responses, and registration lifecycle code. Read-only tools are explicitly separated from tools that modify the page. Agent actions are visible in the UI and can be reversed by the user.

I also built a reproducible WebMCP demo with rights-safe synthesized audio, browser smoke tests, snapshots, benchmarks, and CI coverage.

Challenges

The hardest part was keeping the agent useful without letting it invent musical meaning.

BeatScope deliberately reports measurable facts such as beats, transients, frequency-band energy, and neutral structural repetition. It does not pretend that an onset is a kick or snare, or that a repeated section must be a verse or chorus.

Another challenge was browser control. Playback actions have to respect autoplay restrictions, variable-tempo timing, cancellation, page lifecycle, and user ownership of the final state.

I also wanted WebMCP to fail gracefully: if document.modelContext is unavailable, BeatScope still behaves like the normal player instead of breaking.

What I learned

WebMCP works best when it is not just a wrapper around buttons.

The most useful tools expose the application's actual domain model. In BeatScope, that means giving the agent direct access to deterministic rhythm, structure, energy, and playback state instead of forcing it to reconstruct those concepts from the interface.

I also learned that human-agent collaboration feels much safer when agent actions are visible, bounded, and reversible. The user still owns the player; WebMCP simply gives the agent a structured way to participate.