Content
# BeatScope
English | [简体中文](README.zh-CN.md)
[](https://github.com/chosuicide/beatscope/actions/workflows/ci.yml)
[](https://github.com/chosuicide/beatscope/releases/tag/v0.12.2)
[](LICENSE)
**Turn a song into a beat-synchronised film — or give its timing to a coding agent.**
BeatScope listens for beats, real transients, energy changes, tempo changes and repeated sections. Beathi Studio turns those measurements into a movie preview and a reusable timing package. Everything runs locally; your audio is not uploaded.
[](https://github.com/chosuicide/beatscope/releases/download/v0.12.0/beatscope-v0.12.0-product-tour.mp4)
**[▶ Watch the 57-second product tour](https://github.com/chosuicide/beatscope/releases/download/v0.12.0/beatscope-v0.12.0-product-tour.mp4)**
## What you do
1. Upload a WAV, FLAC, MP3, OGG or M4A file.
2. Check the film preview, song structure and rhythm map.
3. Render a video, export MIDI/CSV, or give the `.beatscope` package to a coding agent.
## Download and run
### Windows
Download **[Beathi Studio v0.12.2](https://github.com/chosuicide/beatscope/releases/download/v0.12.2/Beathi-Studio-v0.12.2-windows-x64.zip)**, extract it, then double-click **Beathi Studio.exe**. The portable package already includes the analyser, browser and FFmpeg.
### Python 3.10+
Download the wheel from the [v0.12.2 release](https://github.com/chosuicide/beatscope/releases/tag/v0.12.2), then run:
```powershell
pip install beatscope-0.12.2-py3-none-any.whl
beatscope serve --open
```
## Two useful outputs
### A film you can watch
The built-in template gives you an immediate music-video preview and can render an MP4. The preview, playhead and rhythm maps all follow the same audio clock, so seeking does not restart the analysis.
### Timing a coding agent can use
Export the `.beatscope` package, then give it to an agent together with your footage, images or references. The package contains measured timing—not a fixed visual style—so the agent can build something new without guessing where the music hits.
```text
your song
↓
BeatScope measures the timing
↓
.beatscope package + your media + your idea
↓
coding agent creates the visual
```
## What BeatScope measures
- beats, bars and tempo changes;
- original onset timestamps—the sound is never moved onto a prettier grid;
- LOW / MID / HIGH energy;
- neutral repeated sections such as A / B / A′;
- optional response ordering for dense songs, so consumers do not react to everything.
BeatScope does **not** pretend to know that a sound is a kick, snare or 808. It reports evidence and lets the renderer decide what to do with it.
<details>
<summary><strong>What is inside the Agent package?</strong></summary>
The package includes `rhythm-map.json`, MIDI and CSV views, a deterministic JavaScript runtime, a self-checking probe, member hashes, and short Agent instructions. It does not include the source audio, a visual template or a pre-written creative task.
`response_relevance` only ranks existing onsets. It is not a probability, confidence score or claim about musical truth; no onset is created, deleted or moved.
</details>
## For developers
```powershell
git clone https://github.com/chosuicide/beatscope.git
cd beatscope
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev,mcp]"
beatscope serve --open
```
BeatScope also provides:
- a local stdio MCP server for analysis and bounded timing queries;
- seven browser WebMCP tools inside Beathi Studio;
- deterministic runtime helpers for browser workers and offline renderers;
- reference consumers for Canvas, Three.js and Remotion;
- `beatscope validate-handoff <package.zip>` and `beatscope validate-consumer <package.zip>`,
which check an exported package against the consumer contract before you build on it.
Read more: [movie renderer](docs/local-movie.md) · [MCP](docs/mcp.md) · [WebMCP](docs/webmcp-studio.md) · [high-precision mode](docs/high-precision.md) · [Agent Skill](skills/beatscope-visualizer/SKILL.md)
## Honest limits
- The current Studio ships one built-in film template.
- Structure labels describe repetition, not Verse/Chorus or emotion.
- Real-world beat, tempo and structure evaluation still needs broader public benchmarks.
- MP3 support requires local libsndfile support or FFmpeg.
## License
[MIT](LICENSE)
MCP Store