How to play it.

01

First sound

1. 1
   Open it. In the browser, or the app for macOS, Windows or Linux. In the browser, click the page once so it may make sound.
2. 2
   Play the letters. The row from A to ' is a keyboard, C4 to F5, with W E T Y U O P as the black keys. A MIDI keyboard works too.
3. 3
   Change the sound. The number keys 1 to 8 pick one of eight sounds. Turn the knobs: drag them up or down, or scroll over them.
4. 4
   Too much? Esc silences everything at once. Enter plays again.

02

The panel

Point at any part of the panel, or tap it, to see what it is and which computer key plays it. On a phone the panel shows its vertical skin, the same keys arranged for a narrow screen.

Above the panel sit Undo and Redo. Under it, a bar with Settings, Keys (the map of what plays what), Remap, Library, and the Help key. In the desktop app the bar also has the Agent button. A small light in a key's corner shows its state: the mode, the track, the sequencer, the metronome, the mic, recording and playing.

03

The four knobs

Blue, green, white and orange. They are endless: they turn without stops, and do something different on each page. Whatever the screen draws in a knob's colour is what that knob moves. Here, on the synth's envelope page:

• Shift + turn gives a knob its second job, or makes it finer where it has none.
• With the mouse: drag up or down, or scroll. The up and down arrows turn the knob you touched last.
• On a MIDI controller, bind a knob in Remap.

04

The four modes

The four mode keys pick what the panel is for. Press the lit mode key again for that mode's setup page, and again to leave it. Tape and mixer mode keep the last instrument: in tape mode the keys play whatever synth or drum sound you chose last.

05

Synth

Keys 1 to 8 hold eight sounds. Each sound is four parts, one under each T key, and the four knobs shape the part on screen.

Eight engines

Shift + T1 opens the engine list; blue scrolls, T1 confirms. Only the engine changes: the envelope, effect and LFO stay. On every tuned engine, orange is tone, a low-pass from dark to open.

• Shift + 1 to 8 opens the presets for that slot: blue picks the engine, green a preset; press the number again to load it.
• Hold 1 to 8 for two seconds to save the sound as it is. Shift + synth brings back the saved version.
• Lift copies the sound, drop pastes it over the current slot.
• < and > shift the octave; with shift they bend the pitch while held.
• Press synth again for play mode: poly, mono, legato or unison (blue), glide (green), drift (white) and level (orange). Every sound is remembered between launches, edits included.

06

Sampling

Any sound you can make, or any sound file you have, can become an instrument.

1. Press micIn synth or drum mode. The screen shows the input's level and its light blinks.
2. Hold a keyMake the sound while you hold it; let go to finish. The mic light burns red while it records.
3. Play itTrimmed and levelled, it plays across the keyboard, in tune with the key you held.

• In synth mode a take is up to twelve seconds, and the current slot becomes a sampler. In drum mode it goes onto the drum key you held, up to eight seconds.
• Sing an F4 on the F4 key, and the keyboard plays it in tune. A tenth of a second from before the key is kept for the attack.
• Mic again, or Esc, cancels.
• Drop a sound file on the panel (wav, aiff, flac, ogg or mp3): it goes into the current synth slot, or onto the drum key struck last. While you drag, the panel says where it will land.
• The input is chosen in Settings, Sampling input. In the plugin, it is the host's side-chain: see The plugin.

Three ways to play a sample

Shift + blue on the sampler's page picks the mode. Each of the eight sounds keeps its own sample, mode and knobs.

07

Drums

Keys 1 to 8 pick one of eight kits. Every one of the 24 keys has its own sound, all made from scratch: kicks, snares, claps, hats, cymbals, toms, percussion, bass hits and noises. The key you struck last is the one you edit.

• Shift + blue on the kit page picks the struck key's sound, sample included.
• Lift and drop copy one key's sound to another: hold the source key and press lift, hold the target and press drop.
• Shift + < or >, while held, play the drums two semitones lower or higher.
• Presets, saving, effects and LFOs work as in synth mode.

08

Tape

Four tracks, six minutes. T1 to T4 pick the track you record onto. Recording replaces what is on the track, as on a real tape, with a short fade at each end so nothing clicks. Shift + record layers one take onto it instead, and shift + orange sets recording to layers for good. To erase a track, press shift + tape, pick the tracks with T1 to T4, then press tape; undo brings them back.

Transport

• Record + play records on the selected track. Record while the tape plays punches in. Record while stopped arms the track; play then starts recording.
• Stop stops. Stop + < jumps to the start, stop + > to the end of the last take.
• Hold < or > to rewind or fast-forward, and hear the tape rush past. Shift + play plays backwards.
• Drag sideways on the screen to hold the tape by hand: it plays at the speed you move it, and lands on the nearest beat when you let go.

Takes and editing

Each recording is a take, drawn as a line on its track. The take under the tape head is the one you edit. Lift cuts it and keeps it (with a loop on, exactly the loop), drop puts it back at the head, again and again, and split cuts it in two.

Tape tricks: keys 1 to 8

• 1ininset the loop start at the head
• 2outoutset the loop end at the head
• 3loopon or off; shift loops the take under the head
• 4breakwhile held, the tape brakes to a halt
• 5reversethe tape changes direction
• 6chopwhile held, repeat a sixteenth note, in time
• 7m1memo 1hold it, press mixer and turn knobs to store a second mix; hold it later to hear it
• 8m2memo 2the same; hold both for halfway between

The tape machine

Press tape again for the machine's own page. It colours what the tape plays, never what it holds, so turning it all down gives the clean recording back.

09

Mixer

Keys 1 to 4 mute tracks 1 to 4 and keys 5 to 8 solo them. The sends start at zero, so a new master effect is heard once you turn a send up.

10

Tempo

The tempo key opens the tempo page. Tap it in time to set the tempo by tapping.

11

Sequencers

The sequencer key turns the sequencer on or off; synth and drums each keep their own. Shift + sequencer picks the type. While a sequencer is on, a key plays the sequence, transposed from C; turn orange until hold lights to keep it going on its own. Most of them take their notes with shift + keys.

12

Export

Settings, Audio files, Export audio opens a sheet with two choices: the mix (the four tracks as the mixer has them, in one file) and each track (one file per tape track, all as long as the tape). A finished piece is kept whole as a project: see Undo and projects. It says how long each is, writes 32-bit float WAV or 24-bit FLAC under a name of your own, and shows how far it got. Import a sound does what dropping a file on the panel does: in tape mode it goes onto the selected track at the head.

13

Undo and projects

Undo and Redo sit just above the panel; rest the mouse on one and it says what it would do, as in "Undo: green knob, decay 245 ms to 528 ms". Cmd + Z and Cmd + Shift + Z on a Mac; Ctrl + Z and Ctrl + Y on Windows and Linux.

Knob turns, sounds and kits, sequencer edits, the mixer, the tempo and every tape edit can be undone, one step at a time, up to 500 steps. Playing is never undone: notes, play and stop, the tape head and the volume stay as they are.

Save and Open sit at the other end of the same bar. A project is one .tapey file that holds a whole piece: the sounds and kits with their samples, the sequences, the mix and tempo, and the four tape tracks. Cmd + S saves it and Cmd + O opens one (Ctrl on Windows and Linux); an orange dot beside its name means there are changes not saved yet. In the browser a project saves to your downloads, and you can drop a .tapey file on the panel to open it. Projects from the browser open in the app, and the other way round.

To start over, Settings has Reset to factory settings: everything goes back to a first launch, after it asks, and it offers to save the project first.

14

The project file

A .tapey file is a plain zip: rename it to .zip and any computer opens it. Nothing inside is locked away.

├─ project.json   sounds, kits, samples,
│                 sequences, mix, tempo
└─ tape/
   ├─ tape.json    takes, loop, head
   └─ track1.flac  one per track in use

• The app writes 24-bit FLAC; the browser writes 32-bit float WAV. Both open both, so a song moves between the browser and the app either way.
• What belongs to your computer stays out: the sound devices, the window, the skin, the key map and the MIDI map.
• A project from a newer tapey-1 says which version made it, instead of opening half of it.

15

The computer keyboard

Every key on the panel has a computer key, and each cap on the panel shows its letter, small and faint at the bottom. The keys go by where they sit, so they work with any keyboard language.

Scroll the keyboard sideways to see all of it.

• notes
• modes
• T1 to T4
• keys 1 to 8
• tempo, sequencer, mic
• transport
• lift, drop, split

• Esc silences everything and lets go of every key; Enter plays again. On a list, the arrows move, Enter picks and Esc closes.
• Cmd + , (Ctrl + , on Windows and Linux) opens the settings.
• Keys, under the panel, shows this map in the app. Settings, Panel, Key letters hides the letters on the caps.

16

MIDI and remap

Pick a MIDI keyboard in Settings, MIDI input. Notes, velocity, pitch bend, the sustain pedal and the mod wheel just work.

Remap, under the panel, opens a banner with two tabs. Nothing plays while it is open.

• Computer keys: click a key or a note on the panel, then press the computer key for it. The banner says what changed.
• MIDI: click a knob, the volume, a key or a note, then move a knob or press a pad on your MIDI device. The first control heard is bound, on any channel. A knob or fader turns the panel's knob by as much as it moves, so a value never jumps.
• Right-click a control to clear it. Done or Esc leaves.

17

Settings

Settings, under the panel, or Cmd + , (Ctrl + , on Windows and Linux).

Sound output

Where the sound goes: the system's, or a device you pick.

Sampling input

The microphone or line input that mic records from.

MIDI input

The MIDI keyboard or controller to play from.

Panel

Keyboard starts on C or F, dark mode (auto, light or dark), the skin, key letters, hints on hover, and the skin editor.

Tape

Hear the tape while winding, tape speed moves everything, snap the tape to the beat.

Sound files

Save the sound, kit or skin you are playing as a small file, and load one back.

Audio files

Export audio (the mix or each track, as WAV or FLAC) and import a sound.

Latency

How quickly the sound answers. If you hear clicks, pick a safer one. The bar under the panel shows the latency and any dropouts.

Feedback

Copy log, show the log file, and report a problem on GitHub with the version filled in.

Agents

In the desktop app: the connection for AI agents, on or off, and its port. See Your AI agent.

18

Skins and the library

Everything in the library comes from players: share yours.

19

Share yours

The library is the community/ folder of the repository. Add a sound, a kit, a sample or a skin with a pull request; once it is merged, it shows up in the Library of every copy of tapey-1.

1. Save itSettings, Sound files, Save sound or Save kit. A skin: Edit skin, Export skin file. A sample: a .wav or .flac.
2. Give it a foldercommunity/<kind>/<name>/, with the file and a short meta.json.
3. Check itnode tools/community-index.mjs says what is wrong in plain words and updates the list.
4. Open a pull requestThe tests run the same check. Once merged, everyone has it.

{
  "name": "Velvet Keys",
  "author": "your name or handle",
  "description": "One or two sentences on how it sounds.",
  "kind": "synth",
  "tags": ["keys", "soft"],
  "licence": "CC0"
}

• The kinds are synth, drum, sample and skin. The folder's name is lower case, with dashes between words.
• The licence is CC0 or CC-BY-4.0. Share only what you made yourself.
• A sample is always CC0, melodic, a few seconds long, yours or provably public domain, and says its root note and its source.
• There is no picture to make: the library draws each entry from what it holds.

The full guide.

20

The plugin

The same instrument and the same panel inside your music program. It takes MIDI from the host, plays into the host's mixer in stereo, follows the host's tempo, and saves everything with your project, the tape included.

1. 1
   Download the plugins for macOS, Windows or Linux and unzip them.
2. 2
   Copy each one into its folder above, making the folder if it is not there. On macOS and Linux each plugin is a folder: copy the whole thing.
3. 3
   Let the host look for new plugins: most do it when they start. In Logic and GarageBand it is an instrument from the maker "tapey-1".

On macOS the plugins are not signed with a paid Apple certificate, so macOS may refuse them at first. In Terminal, run xattr -dr com.apple.quarantine followed by the plugin's path, once for each. The full plugin guide.

On Linux the plugin has no window of its own yet: the host shows its sliders. Export and import live in the app; in a host, bounce there.

21

Your AI agent

If you want, the desktop app can play with an AI agent such as Claude Code, Codex or Cursor. While the app is open, it serves the agent on your own computer only, over MCP, the way agents use tools. The agent can press keys, turn knobs, play notes, read the screen and record to tape while you play.

• You see what it touches: the keys and knobs it uses press and turn on the panel, ringed in violet.
• The Agent button under the panel, or Cmd + . (Ctrl + .), stops it at once: everything it started goes quiet until you click again.
• Settings, Agents turns the connection off, or moves it to another port. The browser version has none.

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

Other agents: setup for each one. Agents can read llms.txt.

22

Help us test

tapey-1 is in alpha: it makes music, and it is not finished. Every report helps, even a short one.

1. 1
   Play it the way you like to play, on the computer you have.
2. 2
   When something goes wrong, write down what you pressed just before, and what you heard or saw. A short phone video of the sound helps a lot.
3. 3
   Tell us in a new issue: your system (macOS, Windows, Linux or the browser), the version you downloaded, your sound device (speakers, headphones, USB or Bluetooth), and the latency and dropouts shown in the bar under the panel.

Ideas, sounds and skins are welcome too. tapey-1 is better for every person who plays it and says what they found.