DRAFT · SPECULATIVE

PWHAMSS: Personal Workshop for Human-Device Animation and MIDI Sync Systems

Version 0.0.2-draft · Status: speculative draft · Updated 2026-11-10 · As of Bollawax 0.2.4 and Bollard SDK 0.1.0

Speculative draft. No Pop Boll hardware has shipped, and nothing on this page has been built or validated on hardware. Names, fields and limits will change without notice, and nothing here is an offer, a commitment or a promise of compatibility. We would love to hear about partnership, OEM and dev-kit ideas: use the contact form on this site.

Note: The band's brain is a removable cart, the Bolltridge. It lives in the ball, and the same cart can also go into other docks, such as the Glass Snipler. A PWHAMSS device takes the cart instead of carrying a computer of its own.

PWHAMSS is the family of Pop Boll devices that a person works on alongside the band, and the name of the web simulator at popboll.com/pwhamss where those devices are built before they exist. The first PWHAMSS device is the Glass Snipler. The overview page introduces the rest of the ecosystem.

1. What the family is#

The Pop Boll plays by itself. Sixteen virtual musicians jam, seven judges score every take, and the ball writes and plays songs from licensed corpora with nobody touching it. A PWHAMSS device is the other half of that idea: a place where a person stands at the keys with the same band, pulling material out of the same corpora, cutting it, playing it and handing it back.

The expansion of the name says what the family is for:

A PWHAMSS device runs Bollawax, the Boll's song factory, so the band and the judges are the same code on the same corpora. What the family adds is a person in the loop and the surfaces a person needs.

2. Shared principles#

Every PWHAMSS device is expected to keep these, and the Glass Snipler is the first to be built to them.

• An always-visible Workshop. A touch surface that never goes away, holding the popboard (the lanes of material you are working on), one bar ruler, a loop window, the transport and the band's listening log. Modes change what the keys do; the Workshop stays.
• Context-switching keys. The keys are transparent and sit over a display, so every key shows what it does right now: its legend, tint, state and stamp. A K-mode key is a letter, a P-mode key is a pad or a scale degree, an S-mode key is a card from your library, and the same key changes between them with no printed legend to contradict it.
• One frame for every renderer. The device is a pure state machine that turns events into frames. The web simulator and the slab's display draw the same frame. Nothing a renderer shows may be invented locally, and a frame is a pure function of the event history.
• HAMS sync of the person's library. The person's sniplets, keymaps and settings belong to the person, not the device, and follow them through HAMS, the Bollawax sync system that already carries a person's songs, ratings and guilds between Bolls and the website. Local first: every device keeps a full copy and works offline for weeks.
• Corpora and licensing unchanged. PWHAMSS devices read the same licensed corpora from bollawax.org as the Boll, under the same terms. Derived stems and stem MIDI are corpus assets, made once when a corpus is built and downloaded like any other. No PWHAMSS device creates corpora, and nothing here changes what a corpus licence allows.

3. The web simulator at popboll.com/pwhamss#

During development the simulator is visible to superusers only. Everyone else, signed in or not, sees the site's ordinary not-found page for /pwhamss and for its API, never a permission error. When the design settles the gate will open in stages.

What it shows. A pixel-faithful drawing of the Glass Snipler in layout A, scaled to the browser window at a fixed aspect ratio: the full-width Workshop on top, the knob row with the pad and the mode diamonds, the 48 keys and the six side keys. An optional toggle shows the frame's matrix and status large. The library is seeded on first use from the built-in corpus, so the simulator starts with real stems and real derived riffs, loops and beats, each carrying its song's stamp.

How a real keyboard maps onto the device. The four physical QWERTY rows of your keyboard are the four rows of the device: the digit row is row 0, the Q row is row 1, the A row is row 2, the Z row is row 3. In K mode that makes typing on your keyboard typing on the device. In P, S and A modes the same physical keys press the pads, degrees, cards and stems that currently occupy those positions. Other inputs:

While the transport is playing the browser sends ticks at 10 Hz (estimate) so the playhead advances; the simulator never reads a clock of its own.

It runs the same state machine the device will. The simulator's canvas is a renderer and nothing more: it sends events and draws the frames that come back. A reload resumes the session. When hardware exists, the slab's display will draw the same frames from the same code.

On a Pop Boll. A Boll serves the same simulator page on its own network once it has fetched the Snipler layer (the Glass Snipler page explains the layer). Without the layer the page says so and draws an empty slab. Fetching and running the layer is under the Snipler Use Grant.

Planned, and not available: the real engine hosted on popboll.com for signed-in developers, and an open stub simulator in the Bollard SDK that replays schema-valid frames.

4. Sniplets, in brief#

A sniplet is a piece of MIDI with a length in bars, a native tempo and a lock, a key, a Groove, a Guild (Family), an Instrument, an AGI flag ("looping is A Good Idea"), a privacy flag and a finished flag. The kinds are sniplet (song-length), riff, loop, beat and macro. Ids are content fingerprints, so the same notes filed twice are one sniplet. SNIP POP lifts material out; SNIP PUT drops it on the popboard. The Glass Snipler page has the full field list and the fitting rules.

5. The frame and event contract#

This is the developer-facing summary. The Bollard SDK carries the shapes as two draft JSON Schemas, snipler-events and snipler-frame, with a validator in Python and JavaScript. They are drafts: they have not yet been checked against frames the engine produces, and where they and this page disagree, neither is final.

Events go from a renderer to the Snipler. Each is a JSON object with a type and a t_ms, integer milliseconds on the renderer's monotonic clock. Renderers may batch events; the reply is the frame after the last one.

{"events": [
  {"type": "mode", "mode": "S", "t_ms": 120400},
  {"type": "key_down", "key": 14, "pressure": 0.62, "t_ms": 120655},
  {"type": "key_up", "key": 14, "t_ms": 120790},
  {"type": "side_down", "side": 4, "t_ms": 121002},
  {"type": "side_up", "side": 4, "t_ms": 121090},
  {"type": "tick", "t_ms": 121100}
]}

Unknown event types are ignored and never fatal. Keyboard shortcuts are the renderer's business: it turns them into these events.

Frames go from the Snipler to a renderer. A frame is the whole display state, abridged here to one key card, one side card, one knob and one lane:

{
  "v": 1, "t_ms": 121100, "mode": "S", "layer": "0", "layer_held": false,
  "status": "S · page 1/3 · 1 selected · 4 bars on board",
  "keys": [{"glyph": "", "sub": "", "label": "Velvet Hook", "tint": "#9BE26B",
            "field": 0.0, "band": 0.0, "state": "selected",
            "stamp": ["bolt", "cup", "moon", "fish"], "marks": ["agi"]}],
  "side": [{"glyph": "ENT", "sub": "", "label": "open guts", "tint": "#9BE26B",
            "field": 0.0, "band": 0.0, "state": "pressed", "stamp": null, "marks": []}],
  "knobs": [{"id": "L", "label": "page", "value": 0.0, "display": "1/3"}],
  "workshop": {
    "view": "board", "bpm": 120.0, "key": "F#m", "easy": true,
    "transport": {"playing": false, "recording": false, "playhead_beat": 0.0,
                  "loop": [0, 4], "bars": 4, "cue": false},
    "lanes": [{"id": "sn_3f9a1c77be02", "name": "Velvet Hook", "kind": "riff", "bars": 2,
               "native_bpm": 143.0, "locked": true, "gain": 0.8, "mute": false, "solo": false,
               "cue": false, "stamp": ["bolt", "cup", "moon", "fish"], "tint": "#F3E97A",
               "fit": "loop", "repeats": 2, "enter_bar": 0, "preview": [[0, 0.5, 66, 96]]}],
    "guts": null, "text": null, "picker": null,
    "band": {"listening": ["Vespera"], "log": []}
  },
  "matrix": {"w": 26, "h": 16, "rgb": "000000000000…"},
  "selection": ["sn_3f9a1c77be02"], "held": [], "toast": null
}

The rules a renderer can rely on:

• keys always has 48 cards and side always has 6, in device order; knobs has 4, in the order S, M, L, H.
• A card is drawn from its own fields alone: glyph, sub, label, tint, field and band (0 to 1 meters), state (idle, selected, held, pressed, dim, empty, armed or active), an optional 4-glyph stamp and a list of marks (agi, lock, draft, ear, now).
• matrix.rgb is 416 pixels × 6 hex characters, row-major from the top-left.
• workshop.view is one of board, guts, keymap, text or picker; the matching sub-object is present and the others are null.
• Every frame the Snipler produces in its tests passes the engine's own frame check.
• The envelope version v is 1. Additions within a major version are new optional fields; removing or changing the meaning of a field is a new major version.

6. Routines and Bolltridges#

PWHAMSS devices sit inside the existing ecosystem rather than beside it.

• The computer in a PWHAMSS device is a Bolltridge cart. The device is a dock: the cart stands in it, connects through the Bollport, and runs Bollawax. The same cart that lives in a Pop Boll runs the Glass Snipler when it is docked in one. The Glass Snipler page says what is decided about that and what is built.
• Routines run where the song factory runs, on the cart. Routines are Python hooks into the song factory, described in bollardeck Part B, and they run only on a person's own device. A PWHAMSS device changes nothing about that: a routine sees the same song factory, and the person's sniplets reach the band only by the band stealing them from the cue stream, which is a riff-book trade, not a routine hook.
• Docks and accessories. The dock messages of bollardeck Part A (now playing, stems, beat, lights) are a draft with no service behind them yet. When that service exists, a PWHAMSS device is meant to look to an accessory like a Boll that happens to have a person at it.
• Third-party work on the Snipler (data, external renderers and controllers, sandboxed apps) is planned and waits for the same service.

7. Roadmap#

Dates are not given. Nothing here has a shipping date, and there is no hardware yet.

8. Status and open items#

• Built so far: nothing on hardware. The simulator and the state machine are in development.
• Estimates: every timing on this page, including the 10 Hz tick rate and the key gesture thresholds on the Glass Snipler page.
• The frame and event schemas in the Bollard SDK are drafts (§5).
• Other PWHAMSS devices beyond the Glass Snipler are not specified. The principles in §2 are what a second device would have to keep.
• HAMS sync of sniplets and the Guild (Family) link to HAMS guilds are intended and not designed.

Changes#

• 0.0.2-draft (2026-11-10). §6 rewritten for the Bolltridge cart; the retired cartridge contract is gone; the draft schemas in the Bollard SDK are named; the Pop Boll's own simulator page and the planned developer simulators are described.

9. Licence#

This page's text is CC BY 4.0: it may be quoted and shared with credit. The Glass Snipler and its engine are all rights reserved for now. The open code a developer needs (the schemas, the validator and the client libraries) is in the Bollard SDK under Apache-2.0. None of this covers the project's names and logos.