Music Blocks: a visual programming language for music

A visual language where the program is the score

Music Blocks is described as a visual programming language and a collection of manipulative tools for exploring musical and mathematical concepts in an integrative and entertaining way. The two epigraphs at the top of the README set the frame, a Monk line about musicians being subconsciously mathematicians and a Leibniz line about music being a hidden arithmetic exercise of the soul.

The application is interactive and the interaction is described precisely: basic mouse events like click, right click, click and drag, and keyboard events like hotkey press. The application is audio-visual, producing graphics, artwork and music at once.

That combination is the pedagogical idea. The blocks are a programming language with a visible structure, and running them produces sound, which gives the learner an immediate result that a generic programming exercise does not. The examples directory shows the range of what gets built this way, from simple things like a twelve bar blues and Frere Jacques to genuinely involved pieces like Bach tonal inversion contrapunctus and a Galton box with retrograde, plus a crossword puzzle and a Doraemon theme.

The project comes from Sugar Labs, the organisation behind the Sugar learning environment, and the reason for combining music and programming is written up separately in a document called WhyMusicBlocks.md in the repository root.

Four ways to run it

The README is thorough about the ways to get it running, and that reflects a project with several audiences.

The hosted web app at musicblocks.sugarlabs.org is the main one, and the browsers listed as working best are Google Chrome or Chromium, Microsoft Edge since it is Chromium-based, Mozilla Firefox and Opera. The experimental build from the most recent master branch is at sugarlabs.github.io/musicblocks, so you can try unreleased changes without installing anything.

There is also an Android app on the Google Play Store, under the package id my.musicblock.sugarlab.

The desktop path runs through Electron, and the package file shows the entry point is electron-main.js with an electron script and an electron-builder dist script.

And there is a Docker image, described in the local setup section with a build step and a run step that publishes port 3000.

docker build -t musicblocks .

docker run -p 3000:3000 musicblocks

The container is then reached at http://localhost:3000, and stopping it with Ctrl + C frees the port.

The licence is the GNU Affero General Public License v3.0, described in the README as a free copyleft licence, with the Licence.txt and COPYING files at the repository root.

Running it locally with npm

Music Blocks is written using native browser technologies, and the bulk of the functionality is in vanilla JavaScript. That has a direct consequence for local use: most of the functionality can be accessed by launching the index.html file in the browser using a file URL pointing at an absolute path.

Doing that leaves some functionality unavailable, so the README recommends launching a local web server from the Music Blocks directory instead.

You download or clone the repository, cd into the directory, install the dependencies with npm install, and start the server with npm run dev.

npm install

npm run dev

You should then see a message saying the HTTP server is serving on 127.0.0.1 port 3000, and you open localhost:3000 or 127.0.0.1:3000 in your browser. The note about using ctrl + c or cmd + c to quit the server is there to avoid a socket error on the next start.

For Turtle Blocks, the same server serves the graphics view at localhost:3000?turtle=true.

The package file gives the details. The dev script runs nodemon with a development environment flag, the prod script runs the same entry point with a production flag, and the serve scripts use http-server bound to 127.0.0.1 on port 3000, one with gzip and brotli compression and one with caching disabled for development. Node 20 or newer is required by the engines field.

The troubleshooting section is honest about the rough edges

The README has a troubleshooting section that is unusually candid, and it is worth reading before you conclude your setup is broken.

When running Music Blocks locally with npm run dev, the interface may load successfully even though some interactions appear unresponsive. New contributors may observe console errors such as $ is not defined, lang is not defined, or p5 is not defined. These errors can occur due to script loading order and initialization differences in local environments.

The guidance is that if the interface loads and assets render correctly, the setup is generally considered successful for development purposes, and that future improvements may address these issues as part of ongoing refactoring efforts.

That is a fair description of the state of a large browser application that loads scripts without a bundler. The p5 reference points at the graphics library that Turtle Blocks relies on, and the fact that a missing global breaks interaction rather than the whole page is consistent with how a script tag ordering problem behaves.

Two smaller pieces of the same honesty: there is a Troubleshooting section in the repository root called Debugging.md, a debugger tool guide, an AI debugger widget guide and a reflection widget guide, and there are accessibility documents in the tree, a WCAG audit report, a canvas accessibility proposal and a touch support audit.

Turtle Blocks is the same codebase with a different lens

Turtle Blocks is described as a view into Music Blocks that focuses on graphics rather than music, and it shares the same codebase. There is no separate project to install.

The access route is a query parameter. Append ?turtle=true to the URL and you get the graphics view, and a redirect link at turtle.sugarlabs.org points at musicblocks.sugarlabs.org?turtle=true for convenience.

This is a clever piece of engineering in its own right. One application, one build, one set of blocks, and a parameter that changes the domain from sound to drawing. For a learning tool, it means the block vocabulary a teacher has already introduced transfers between the two activities, and it means the project only has to maintain one implementation.

The Turtle documentation lives in TurtleDocs/ with its own README, and the examples directory contains entries with a .tb extension alongside the .html ones, which suggests the graphics examples are stored in a format specific to that view.

For the voice output, the README points to a separate document on the Kokoro voice under Docs/, so the speech synthesis is a documented, separable component of the system.

Project state, tooling and the shape of the repository

The release history is dated by theme rather than by version number alone. The listed tags are v3.8.0 for the 2026 GSoC DMP updates from 2026-09-16, v3.7.1 labelled Pre-GSoC-2026 from 2026-02-15, and v3.7.0 marked End of Year 2025 from 2025-12-31.

That naming convention tells you something about how the project is run. GSoC is the Google Summer of Code programme, and tagging releases around the summer and the year end means the repository is on a cycle driven by student contributions, which also means the release cadence is tied to the programme rather than to a steady engineering schedule.

The repository is not archived and the last push was on 2026-10-18. The tooling in the package file is broad: Jest for unit tests with coverage and mutation testing through Stryker, Cypress for end to end tests, ESLint, Prettier, commitlint with the conventional config, husky for hooks, Babel, and electron-builder for packaging.

The tree is large and tells the story of a long lived project. There is an activity/ directory, a dist/ directory, bower_components/, a css/ directory, fonts/, an examples/ directory with dozens of pieces, cypress/ with its own config, a scripts/ directory with a test generator, and a Docs/ directory. There are also documents you would not expect in a kids coding environment: PERFORMANCE.md, DOCS_MODULE_ARCHITECTURE.md, REVIEW_GUIDELINES.md, GOVERNANCE.md, MAINTAINERS.md, a .devcontainer/ directory and a .coderabbit.yaml.

There is Japanese documentation too, in README-ja.md, and a convert_po_to_json.py script, so the translation workflow is part of the build.

Editorial conclusion

Adopt Music Blocks if you are teaching programming through music or want a browser-native environment where the only dependency is a modern browser, since it needs no build step to try and the visual model makes the feedback loop immediate. Do not adopt it as a general purpose visual IDE or as a library to embed, because it is a complete application with an AGPL licence and a large surface of its own. Verify first that your browser is Chrome, Chromium based Edge, Firefox or Opera, since those are the ones that work best, that you have Node 20 for the local server and the npm scripts, and that you accept the AGPL v3 terms if you plan to distribute a modified version.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. sugarlabs/musicblocks on GitHub