beepbox: browser melodies packed into a URL

The song is the URL

The first thing the README explains is the storage model, and it is the most unusual idea in the project. All song data is packaged into the URL at the top of your browser. When you make changes to the song, the URL is updated to reflect your changes, and when you are satisfied with your song, you just copy and paste the URL to save and share it.

That is the whole persistence layer. There is no account, no server side storage, no database and no file format to negotiate, because the song is serialised into the fragment of the address and travels with the link. Two consequences follow directly.

The first is that sharing is trivial and collaboration is absent. A link is the artefact, so sending a tune to somebody is a paste, and there is no way to edit a song that somebody else is editing, because there is only one copy of it, in a URL.

The second is that the URL grows. A song with several instruments, a few patterns and a long arrangement is a long string, and URLs have limits, and some chat clients and mail systems truncate long links. The project has evidently accepted that trade, since the design has not changed and the tool is described as a passion project that will always be free to use.

That framing matters for evaluation. BeepBox is a sketchpad, and a sketchpad that produces a shareable artefact in one click is a coherent thing to be. It is not an arrangement tool, a tracker, or a sample manager, and nothing in the documentation suggests it is trying to be.

The site is beepbox.co, the code is MIT licensed, the author is John Nesky, and the repository is not archived with the last push on 2026-08-07. The published versions are v4.2 from 2023-08-01, v4.2.1 from 2025-11-24 and v4.2.2 from 2025-12-08, so the releases are versioned separately from the site, and the site is ahead of the last tag.

Three builds, three folders, three purposes

The code is divided into several folders, and the division is by use case rather than by layer, which is the right cut for a project like this.

The synth/ folder has just the code you need to be able to play BeepBox songs out loud, and the README notes you could use this code in your own projects, like a web game. After compiling the synth code you open website/synth_example.html to see a demo using it, and to rebuild just the synth code you run npm run build-synth.

The editor/ folder has additional code to display the online song editor interface, the thing most people picture when they hear the name. After compiling the editor code you open website/index.html to see the editor interface, and the rebuild command is npm run build-editor.

The player/ folder has a miniature song player interface for embedding on other sites, rebuilt with npm run build-player.

The website/ folder contains the index.html files used to view the interfaces, and the build process outputs JavaScript files into that folder.

So there are three separately buildable bundles, and each npm script compiles one of them. That is the shape to understand before you contribute, because a change to the song format or to the audio engine has to reach the synth, the player and the editor, and the build script wires them together in a fixed order. The full build is clean, then build-synth, then build-player, then build-editor, which means the editor is always compiled last and sees the finished synth and player.

The synthesiser is the reusable part, and it is on npm

The README has a section on its own for this, and it is short. You can use BeepBox's synthesizer to play music in your own web app, and it points at the npm package for more details.

That npm package is separate from this repository's own manifest. The package.json here is marked private with the name beepbox, and the build scripts are wired to compile and then publish through a script rather than through npm publish, so the published artefact is produced by the project's own pipeline.

For an adopter, this is the interesting seam. The song format, the instrument definitions and the audio scheduling are all in the synth code, and they are what the npm package exposes. That means a web game, a chat application or a puzzle can play BeepBox songs, and can serialise a song into a URL in the same way the site does, which is what makes the link sharing model composable with your own application rather than a toy you can only use at beepbox.co.

The dependency list gives a sense of the implementation. The build uses rollup 2 with the node resolve and sourcemaps plugins, terser for minification and esbuild, with TypeScript 4.9.5 compiling the sources, and concurrently and five-server for the live editor workflows. There is exactly one peer dependency, imperative-html at ^0.1.2, which means the synthesiser is expected to be dropped into a host that already provides it.

The published synth is therefore not a standalone library in the usual sense. It is the audio half of BeepBox, packaged so that it can play songs that BeepBox's own editor produced.

Building it from source

The compiling section lists the prerequisites and then the four commands, and the prerequisites are worth restating because the build is not a modern bundler setup.

The code is written in TypeScript, which requires Node and npm, and to contribute changes you also need git. Then:

git clone https://github.com/johnnesky/beepbox.git
cd beepbox
npm install
npm run build

Beyond the main build there are the per target builds, which are the ones you will use day to day, npm run build-synth, npm run build-editor and npm run build-player, and each of them calls a shell script in the scripts/ directory, bash ./scripts/compile_synth.sh and its siblings. There is also npm run clean, which calls scripts/clean.sh, and npm run live-editor and npm run live-editor-fast-typeless, which start a development server for the editor with and without the typing animation, using the concurrently and five-server development dependencies.

Because the build scripts are bash, the build is Unix shaped. On Windows that means a shell that can run them, and the README does not address it.

There is also npm run deploy-website, which calls scripts/deploy.sh, and npm run publish, which calls scripts/publish_on_npm.sh. The repository layout is simple and matches the folder structure described above, with dist/, editor/, player/, scripts/, synth/ and website/ at the top level, and the website folder holding the index.html files that the build writes into.

mp3 export downloads lamejs in the browser

The dependencies section has one paragraph that deserves attention, because it describes a runtime download rather than a build time one.

Most of the dependencies are listed in package.json, but the README notes that BeepBox also has an indirect, optional dependency on lamejs via jsdelivr for exporting.mp3 files. If the user attempts to export an.mp3 file, BeepBox will direct the browser to download that dependency on demand.

So the MP3 export path pulls a third party library into the user's browser at the moment they click export, from a public CDN, rather than bundling it. That keeps the initial payload smaller, which matters for a tool that people open on slow connections, and it means the export feature depends on a network fetch to a CDN that the project does not control.

For a user this is invisible unless the fetch fails, in which case the export is the thing that breaks while everything else keeps working. For somebody who wants to embed BeepBox in a product, the arrangement is worth thinking about, because a build that fetches code at runtime is a different kind of artifact from one that does not, and some deployment environments will not let a page do that.

The rest of the tool, the editor, the player and the synthesiser, has no such runtime dependency, since the other dependencies are installed from package.json at build time.

npm publish is blocked on purpose

There is a small detail in the scripts that tells you how the project handles releases, and it is easy to miss.

The prepublishOnly script does not run a release. It prints Use 'npm run publish' instead! and exits 1, so any attempt to publish the package with npm publish fails immediately. The actual publishing goes through npm run publish, which calls scripts/publish_on_npm.sh.

The reason is visible in the layout of the other scripts. The build produces several bundles, the synthesiser is published separately from the application code, and the site is deployed by its own script. A single npm publish of the repository package would publish the wrong thing, since the package here is marked private with the name beepbox, and the artefact consumers actually install is the synthesiser.

So the release process is a set of shell scripts that build, deploy the website and publish to npm, and the manifest exists to stop an accidental publish of the wrong contents. If you fork this and want to publish your own build, you have to replace that guard rather than work around it.

The licence is MIT, and the README points to the licence file in the repository, so the terms that apply to the code and to the synthesiser package are the ones in that file.

Where BeepBox is the wrong tool

The limits follow from the design and are worth stating plainly.

The first is the storage model. A song that lives in a URL is a song that cannot be longer than a URL, cannot be versioned, cannot be edited by two people at once, and disappears if the link is lost. For a sketchpad that is a feature. For anything you intend to keep, or to share with someone who will work on it, it is a limitation that no amount of configuration removes.

The second is the browser. There is no server component in this repository, no account system and no persistence, so the application is a static site. That is a strength for hosting and a limit for anything that needs a backend, a library of saved songs or moderation of what gets shared.

The third is the scope of the music. The description says instrumental melodies, the feature list is a canvas based editor with an instrument palette, and the synthesiser implements that one sound engine. If you want a general purpose audio library for a web application, with sample handling, effects, mixing or a wider instrument set, this is the wrong dependency, and writing a small synth against the Web Audio API yourself is a different and more controllable design.

The fourth is the maintenance shape. The version numbers in the tags and the state of the site can diverge, as the v4.2 tag from 2023 and the v4.2.2 tag from 2025 show, and the release process is a set of shell scripts rather than a published workflow, so forking it means owning the pipeline rather than reusing it.

Editorial conclusion

Adopt BeepBox if you want a music toy that needs no account and no backend, if you are happy for the song to live in a URL that can get long, or if you want its synthesizer for your own web project. Do not adopt it as a general audio library, since the engine is built around one song format and one instrument set, and do not expect the repository to be a good foundation for anything but a browser game. Verify first that the npm beepbox package's API matches what you need, that your build environment can run the bash build scripts, and that you have read the licence file before redistributing a build that includes the synthesiser.

Frequently asked questions

Official sources

1. johnnesky/beepbox on GitHub
2. License: MIT
3. Project website
4. README
5. Releases