# tapey-1

> A free, open-source synthesizer, drum machine and four-track tape recorder, a personal project by Isaque Seneda. It runs in the browser, on macOS, Windows and Linux, and as an Audio Unit, VST3 and CLAP plugin. It is small (a few MB, written in Rust) and in alpha. The desktop app can also let an AI agent play it together with a person, over MCP (Settings, Agents).

- Repository: https://github.com/isaqueseneda/tapey-1
- Guide for agents working in the repository: https://github.com/isaqueseneda/tapey-1/blob/main/AGENTS.md
- Downloads (latest release): https://github.com/isaqueseneda/tapey-1/releases/latest
- Play in the browser: https://play.tapey.org
- How to play it, every key and knob: docs.html on this site
- Licence: GNU GPL, version 3 or later

## What it is

One panel: a screen, four coloured knobs (blue, green, white, orange), mode keys, tape keys and a two-octave keyboard.

- Synth: eight engines (pulse, fm, digital, string, chip, phase, cluster, sampler), an envelope, seven effects (delay, reverb, compressor, radio, chorus, lofi, filter) and three LFOs (tremolo, value, random).
- Drums: eight kits of 24 synthesized sounds; any key can hold a recorded or imported sample.
- Sequencers: chain, pattern, arpeggio, bounce and curve, running at the tempo (40 to 240 BPM).
- Tape: four tracks, six minutes. Overdub, lift (cut), drop (paste), split, loop, reverse, speed, and tape colour (saturation, wow and flutter, age, hiss).
- Mixer: level, pan and EQ per track, a master effect, two mix memories.
- Projects: save the whole piece (sounds, samples, sequences, mix, tape) as one .tapey file. Settings, Audio files: bounce the mix or export the tracks as WAV or FLAC.

People play it with the computer keyboard, a MIDI keyboard or the mouse. The full key and knob reference is docs/panel.md in the repository.

## Connect over MCP

While the desktop app is open it serves MCP (Streamable HTTP, protocol 2025-06-18 or 2025-03-26) on the local machine only, at:

    http://127.0.0.1:7341/mcp

The port can be changed in the app's Settings, Agents, or with the environment variable TAPEY_PORT. The app's welcome screen shows the address with the real port.

Claude Code:

    claude mcp add --transport http tapey-1 http://127.0.0.1:7341/mcp

Or the Claude Code plugin, which adds the server and a skill for making music with tapey-1:

    /plugin marketplace add isaqueseneda/tapey-1
    /plugin install tapey-1@tapey-1

Other MCP clients:

    {
      "mcpServers": {
        "tapey-1": { "type": "http", "url": "http://127.0.0.1:7341/mcp" }
      }
    }

Clients that only start programs: run the app's program with the argument mcp (on a Mac /Applications/tapey-1.app/Contents/MacOS/tapey-1 mcp; on Windows tapey-1.exe mcp). It carries stdio to the running app.

The same app answers a plain HTTP API on that port, for scripts: GET /api lists the tools, GET /api/state reads the state, POST /api/<tool> with the tool's arguments as JSON calls one. The web version in the browser has no server; use the desktop app.

Setup for each client: https://github.com/isaqueseneda/tapey-1/blob/main/docs/agents.md
Reference: https://github.com/isaqueseneda/tapey-1/blob/main/docs/api.md

## The tools

The tool list your client receives from the server is the source of truth for names and arguments. Every tool answers with a short sentence and the state that changed.

- get_state: mode, sound and its settings in readable units, tempo, tape (playing, recording, armed track, position, which tracks hold sound), mix, what the screen shows, in words, and whether the person paused you. Call it first.
- listen: levels of the mix, the live synth and drums, and each tape track over a few seconds (peak and RMS in dB, silent, clipping, low/middle/high balance), and what is running. Use it to check that music plays, is not too loud, and that a recorded track holds sound.
- screenshot: the screen as a PNG.
- tap_key, press_key, release_key: any panel key by name (synth, drum, tape, mixer, t1-t4, 1-8, seq, tempo, mic, rec, play, stop, left, right, lift, drop, split, help, shift), with optional shift.
- turn_knob (blue, green, white, orange, by clicks), set_volume, set_octave.
- set_tempo (bpm, sync, metronome): set it first, then write every part in beats, 4 to a bar. The bpm is the tempo at normal tape speed; the tape's speed moves the tempo heard (get_state's tempo.bpm).
- play_notes: a phrase of notes ({note, start, length, velocity}, in beats) played live at the tempo; notes are names like C4 or MIDI numbers, and drum sounds like kick for the drums; start_at next_bar lands it on the bar. It warns when the tape runs with no track armed. stop_notes stops it.
- program_pattern: a 16-step (one bar) drum or synth pattern from a grid such as {"kick": "x...x...x...x..."}, looping at the tempo; stop_pattern.
- record_loop: one part (notes or a pattern) recorded onto a track for exactly some bars, from a given bar; says whether the track holds sound.
- set_mode, select_track, transport (play, stop, record, arm, disarm, rewind, to_end, seek to seconds or a bar; with beats, run that long and stop).
- set_loop, tape_reverse, tape_break, tape_chop: the tape's loop and tricks by name.
- list_presets, load_preset, select_sound: factory sounds and kits, and the eight slots of each.
- list_params, set_param: every setting of the sound, the mixer and the tape by name (attack, cutoff, fx.mix, track 2, tape.speed, saturation, engine, effect, lfo, master effect), with values as the screen shows them ("mix 35" takes 35) or with units ("200 ms", "-6 dB", "0.5x"); a value out of range is refused with the range.
- checkpoint, restore_checkpoint: keep the sounds, mix and tape machine, experiment, go back.
- undo, redo: take back the last change (yours or the person's: a knob, a sound, a sequencer edit, the mixer, the tempo, a take or an edit on the tape), or put it back; get_state's history says what each would do. Notes and the transport are never undone.
- save_project, export_mix: keep everything now; write wav files. export_mix takes what: "mix" bounces the mix (one stereo wav), "tracks" exports tracks (one wav per tape track); without it, both.
- list_library, load_library_item: sounds and kits installed in the app's library folder.
- load_sample: a sound file on this computer (wav, aiff, flac, ogg, mp3) as a sample, as a drop on the panel does: into the current synth slot (root: the note it was recorded on) or onto a drum key. The sampler has three modes (set_param mode): keys (tune, play, start, end), slice (slices: 2 to 24 even, or hits; play, start, end) and grain (position, size, density, spray).

The MCP resource tapey://guide is a short guide to making music with tapey-1, with recipes.

Good habits: set a tempo and think in bars. Read the state and listen after you act, to check what happened. Keep changes musical and small while the person is playing. Ask before you record over a track that already holds sound.

The person sees what you do on the panel (keys pressed, knobs turned, ringed in violet) and can stop you at once with the Agent button under the panel. While stopped, every tool that changes anything answers "The player paused the agent": stop and ask them.

## Community library

Synth sounds, drum kits, samples and skins live in the community/ folder of the repository, under synth/, drum/, sample/ and skin/. A pull request that adds a folder there, with the saved file and a meta.json, puts it in the app's Library once merged; community/README.md says how, and node tools/community-index.mjs checks it.