Key ideas#

Pocket is careful about a handful of things that most music software leaves unsaid: which recording you mean, which clock a position belongs to, and who said what about the result. Once these ideas click, every other guide reads more easily. This page explains them in plain terms and ends with a glossary.

Pocket in one paragraph#

Pocket is a library of small, single-purpose operations for musical work. Among other things they can capture a passage of a recording, place a cue on a timeline, render alternatives, edit MIDI, read a saved Ableton Live set and record what a listener heard. Each operation is called a provider, and you can call every provider three ways. Providers that make something, such as a capture, a render or a report, write it as a new file. Read-only providers, such as queries, capabilities_list and Peek, write nothing. Many providers, including all of the practice tools, return a receipt describing exactly what they did and did not do. Some older tools, Peek among them, return their own documented report instead.

One implementation, three ways in#

All three call the same Python function, so a result never depends on which door you came in through. CLI command names use hyphens, and MCP tool names use underscores. The CLI and MCP take the same JSON argument object. capabilities_list (or pocket capabilities-list) reports what your installation can do right now.

MCP, the Model Context Protocol, is an open standard that lets AI assistants call local tools. pocket-mcp runs on your own machine and talks to your agent over standard input and output. Nothing is hosted, and no audio is uploaded. See Use Pocket with an agent.

Stores, artifacts and handles#

Pocket writes what it makes into a folder you choose, called a store (store_root). Inside it:

• An artifact is one saved thing: a musical context, a render, a comparison or a listening report. It lives under artifacts/<sha256>/, named by the hash of its own bytes, and it never changes after it is written.
• A handle is a small JSON pointer to one artifact. It holds the artifact's location in the store, its SHA-256 hash and its schema. You pass handles from one call to the next.

{
  "schema": "pocket.artifact-handle/v1",
  "artifact_uri": "artifacts/4f78c0e9…/record.json",
  "sha256": "4f78c0e9…",
  "artifact_schema": "pocket.musical-context/v1"
}

• A receipt is what many calls return, whether or not they wrote anything. It holds a status, handles to anything new, coverage (what was and was not attempted), warnings and stated uncertainty. For example, "human_listening": "not_performed" means exactly that.

Every read checks the bytes against their hash. Moving a whole store to another folder or machine keeps every reference valid.

Nothing is overwritten#

Pocket never edits your recordings, projects or earlier results in place.

• An edit creates a new artifact that remembers its parent (its lineage). The original stays exactly as it was.
• Commands that write folders require a new destination and refuse an existing one, so an earlier experiment is never clobbered.
• Operations that write into a store take a request ID. Repeat a call with the same ID and the same inputs, and you get the same verified receipt back (a replay), with nothing done twice. Reuse the ID with different inputs, and the call fails with idempotency_conflict. An interrupted request is left in place for you to inspect with request_status. It is never retried silently.

A recording is its bytes#

Pocket identifies audio by the SHA-256 hash of the file's exact bytes, not by its title or filename. Renaming a file doesn't change its identity. Two masters that share a title are two different recordings. A catalog entry, such as a Spotify track URI, describes a release, not a particular audio file on your disk.

Time has more than one clock#

Musicians juggle several kinds of time at once, and Pocket names each of them separately.

• Source frames are sample positions in the original recording file. At 48 kHz, one second is 48,000 frames. Pocket counts from the start of the whole file, even when you captured only a short passage of it.
• A timeline measures arrangement position in quarter notes (qn) on a declared tempo map. At 120 BPM, one quarter note lasts half a second.
• An occurrence is one placement of a source passage on a timeline. A passage that plays twice has two occurrences, each with its own ID. That's why Pocket asks which occurrence you mean when you place a cue inside a repeated passage.
• An anchor (a cue) is a named point you author, such as "where the horn comes in". Each anchor has a kind, and the kinds stay distinct: an onset (where a sound starts), a pulse (the steady beat you would tap), bar one (the downbeat that starts a bar) and a phrase start (where a musical sentence begins). A loud accent might be a backbeat, and a phrase can start on a pickup. Pocket never assumes that any two of these coincide.

Positions are exact. Pocket writes fractions as {"n": 5, "d": 2}, meaning 5/2 or two and a half quarter notes, and never rounds them to decimals behind your back. Frame intervals are end-exclusive: [1000, 2000) covers frames 1000 through 1999.

The first experiment puts all of this in one place: a cue at source frame 4000 lands at 5/2 quarter notes during a passage's second pass.

Four kinds of evidence#

Every claim carries an attribution: the actor, their actor_kind (human or agent), the statement and any uncertainty. These are stated claims, not verified identities. Pocket always labels an agent's report as an agent report, and it never presents one as human listening.

A successful render, a clean signal check or a confident score is never a musical verdict. Pocket doesn't pick winners or average opinions, and when two reports disagree, you see both.

Profiles, limits and refusals#

A profile is a named, versioned rulebook for one kind of processing, such as browser-pcm16-original-rate/v1. It states exactly what an operation does and, just as importantly, what it will not do.

When an input falls outside a profile, Pocket refuses and explains why. It will not approximate. There is no silent resampling, normalization, fading, time-stretching or rounding to make something "work". Every provider also has explicit size limits, so a request can't grow without bound.

Schema names such as pocket.practice-render/v1 identify a record's family and version. When a format changes, it gets a new version, and old records keep their original meaning.

A qualified profile has been tested against a specific real environment, such as one browser or one Live version. That is a narrower promise than implemented, and the guides say which one applies.

Working with Ableton Live#

Pocket's core never needs a DAW (digital audio workstation). A set of optional adapters works with Ableton Live 12:

• Thread reads saved .als set files.
• Stitch builds comparison copies of a transition.
• Baste observes the open session through a Max for Live device.
• Pipette carries a kept trial into a new project.

Native means inside Live itself, as opposed to working with its files. Native steps are supervised: a person opens, saves and renders in Live, and Pocket checks the resulting files and records what was observed, with attribution. A saved set describes intent, and a rendered file establishes what audio came out. Neither one tells you how the audio sounds.

Choosing records#

• A record bag is a sealed crate of records with optional notes about each one, such as energy or vocal density, attributed to whoever wrote them.
• A brief states the setting, duration and intent for a set.
• A route is one proposed order through a bag for a brief. Weave proposes several.
• A session is the shared, revision-checked state that Whisker uses to propose what could come next.

The tool family#

A pocket is sewn with thread and stitches, and Pip, the field mouse who lives in this one, peeks out and feels the way with whiskers. The names follow from that.

The standalone practice, review and MIDI tools are named for what they do. See all guides.

Glossary#