picoTracker Librarian

A librarian and arrangement editor for picoTracker SD cards that runs entirely in your browser — pico and Advance cards alike. Browse and audit your projects, instruments, samples and themes; hear a song without leaving the page; edit the arrangement, phrases, slice points and instrument parameters; find and repair broken sample references; build ordered setlists; export MIDI — whole song or per-channel stems, with MIDI instruments on their configured channels. One HTML file, no install, no server, and no data ever leaves your machine.

Requires Chrome or Edge (it uses the File System Access API to read your card; Firefox and Safari don't support it).

⚠ Beta — back up your projects first

This is beta software that writes to your SD card. Reading and browsing are safe and well exercised; the editing features (arrangement, phrases, slice points, instrument parameters, themes) have been through many rounds of real-card use and review, but they are younger than the browsing side.

Every write backs the original up to PTLibrarian_Backups/ on the card, verifies the result byte-for-byte and rolls back on failure, and deletions go to a trash folder rather than vanishing. That is not a substitute for your own backup. Copy your card, or at least the projects you care about, before editing anything. Use at your own risk.

Getting started

1. Open index.html in Chrome or Edge (or the hosted page).
2. Click OPEN SD CARD and pick your picoTracker card (or any folder with the picoTracker layout: projects/, samples/, instruments/, themes/, …).

No card handy? Hit Try with demo data on the landing screen — a synthetic card, generated audio included, loads entirely in memory so you can explore every tab, the pattern editor, playback and the repair flow without touching hardware.

picoTracker projects are self-contained — each project folder carries its own samples/ pool — so missing-sample detection works instantly, with no cataloguing step. The library is cached in IndexedDB, so reopening the same card is instant and rescans are incremental — a warm rescan reads no sample data at all.

Cards that have been near a Mac collect AppleDouble junk (._kick.wav, .DS_Store, .Spotlight-V100). These are skipped everywhere — scans, listings, exports — so they never appear as phantom samples.

What it does

Browse

• Projects — list and grid views, filtered and sorted by name, date, missing samples, instrument count, BPM or size. Each row plays, opens the pattern editor, or compares directly; expanding it shows the instrument bank, the sample pool with missing/unused markers, project settings, and similar projects by shared samples. An autosave badge flags projects where the device would load newer unsaved state.

• Instruments — every .pti in instruments/ plus every project's instrument bank, decoded in full (all parameters, slice points), with type filters (SAMPLE / SAMPLESOURCE / MIDI / SID / OPAL), sample status, usage tracking and a ▶ on every row whose sample is on the card. Parameters are grouped into Sample / Tuning / Mix / Filter / Crush / Amp / LFO / Table cards with level bars, note names for root note and L/R for pan.

• Samples — the samples/ library tree plus every project pool, with duration, sample rate and bit depth per WAV, used/unused badges, and up/down arrow-key audition.

• Themes — visual previews of every .ptt with swatches, and the device's active theme flagged. Preview applies a palette to the app itself; Set on device writes it into the card's .config.xml so the tracker boots with it; Save device colours as .ptt captures the current device palette as a new theme. There's also a theme creator: build one from scratch or copy an existing one, with a live device-screen preview drawn from the firmware's real colour roles.

• Grooves — every non-default groove across all projects, step-visualised.

• Renders — renders/ and recordings/ with waveform preview and playback.

• Stats — collection KPIs, instrument types, FX command usage, tempo/scale/firmware distributions, backbone samples, recently modified, and the device's .config.xml.

Play

• In-browser playback — press Play on any project and hear it. A Web Audio engine walks the song the way the firmware player does: per-channel advance with group looping (a channel that hits an empty cell loops its contiguous run of chains, exactly like the device — verified against the firmware source), chains ending at their first empty step, grooves, per-channel GRV switches, HOP flow, chain and project transpose, slices, loop modes including pingpong (built as a mirrored composite buffer, bouncing exactly where the firmware bounces), and VOL/PAN/KIL. Playback loops endlessly, as the device does — the transport's loop toggle is on by default; turn it off for a single pass. Songs arranged as islands (sections separated by blank rows, each looped live) are understood: the main Play button plays the longest island, and each row's gutter ▶ plays and loops from that row, between the blanks around it. Slice and loop points are converted through each WAV's own sample rate, so playback is in time whatever your machine's audio rate is, and the mix runs through a limiter so dense passages don't clip. An honest sketch of the song, not an emulation: synth voices (SID/OPAL) and most FX are out of scope by design, and Advance SAMPLESOURCE amp envelopes aren't applied.
• Play anything, from anywhere — the whole song, from any row (the gutter ▶ starts there and plays on, which is also how you reach parts below a gap), one chain, or one phrase.
• Transport — a bar along the bottom shows what's playing, a scrub bar you can drag to jump around, a loop toggle, elapsed/total, and a stop that works from anywhere; the playing project's row stays lit. Space plays whatever you're looking at: the open phrase, else the open chain, else the song. While anything plays, the song grid outlines the cell each channel is currently inside, lights its row, highlights the chains in play, and marks the current step of the open chain.

Arrange and edit

• Pattern editor — the song grid at full size, with an ordered chain list down the left bucketed by number group (usage counts, colours, per-chain preview, hover-to-highlight), and chain and phrase panels beside the grid rather than under it. Click any cell to choose the chain that sits there from a filterable list of the chains this song already uses, the ones defined but unplaced, and free slots; type a value that isn't listed and it's offered too, so all of 00–FE is reachable. Arrow keys walk the grid — the active cell carries a high-contrast marker with its row and channel labels lit, and the gutter ▶ plays the song from that row to the end — and shift+arrows or shift+click select a block, which then copies, pastes or clears as a unit (⌘/Ctrl+C/V, Del, ⌘/Ctrl+A for everything, Esc to deselect). Whole rows also copy and paste from the gutter, and ⌘/Ctrl+Z undoes arrangement changes. Spare rows sit past the end of the song so an arrangement can be extended, with + more rows for as far as the geometry allows. Chain colours come from the chain number: the high nibble picks a hue family so the 00s, 10s and 20s each read as a group, while lightness strides within a group to keep neighbours apart. Pick your own per chain, or reset.
• Chain editor — open any chain and edit its 16 steps in place: which phrase plays at each step, chosen from the project's phrases with a note count each, and a per-step transpose. Beat-marked every four. Clone copies a chain to an empty slot and repoints the grid cells that used it.
• Reach anything — ⤳ Go to… opens any chain or phrase, whether or not it appears in the song, so ideas can be sketched without editing the arrangement first.
• Phrase editor — a tracker-style grid you edit in place. Arrows and Tab move the cursor, Enter or typing opens a pick-list, Del clears a cell. Notes, instruments and FX are chosen by name — 04 Night Bass rather than 04, KIL/HOP/PSL rather than raw hex — with fuzzy matching, so c4 finds C-4. Shift+arrows select a block over steps and columns, which copies, pastes, clears and transposes as a unit. The header says where the phrase is used and warns when editing it will change several chains at once, with Clone to vary it in one place only. ✎ Instr (or ⌥↓, or ⌥-clicking an instrument cell) jumps straight to that instrument's edit screen, so an instrument can be tweaked from the pattern that plays it. An optional QWERTY piano mode types notes straight down the column (z s x d c v g b h n j m for C–B, q 2 w 3 e r 5 t 6 y 7 u an octave up, a for note-off, [/] for octave), carrying the instrument down and advancing by a configurable step. Insert or delete a step (shifting the rest of the phrase), per-step copy/paste, whole-phrase copy/paste/clear, one-click transpose (±1/±12), 50-level undo, and a ▶ that auditions just that phrase.
• Scale lock — the phrase editor knows what key a project is in, from its own setting, from a scale you choose for it, or from the notes themselves. Out-of-key notes are flagged either way; with the lock on the note pick-list only offers notes in the key, typed and piano entry snap, and +1/−1 move by scale degree rather than by semitone (octaves stay octaves). A one-click fix moves every stray note to the nearest one in the key, offered only when the scale is something you or the project stated rather than something detected.
• Generators — a preview-then-apply modal that writes real phrase data: Euclidean rhythms with rotation, arpeggios over twelve chord shapes in four patterns, variations of what is already there with a similarity dial and a reroll, and a humanise pass writing VOL with an accent on the beat and a seeded spread. Everything is seeded, so the same settings always give the same phrase and a result you liked can be reached again. The preview shows before and after for every step, nothing is written until you press Apply, one undo takes it all back, and a block selection narrows the scope.
• Slice editor — any sample instrument's WAV on a big waveform. Zoom with the scroll wheel or −/+/Fit, with a full-file strip underneath showing where you are that drags to scroll. Drag markers, double-click to add, audition slices by clicking regions or with the 1–9,0 keys, auto-chop breakbeats with transient detection, equal-divide clean loops, and snap everything to zero-crossings. Advance SAMPLESOURCE instruments carry 32 slice pads, pico SAMPLE instruments 16.
• Instrument parameters — edit any existing parameter of a project-bank instrument in place, with sliders alongside the values for 0–255 knobs.
• Tables and grooves — a tab in the project workspace for both: three columns of command and value over 16 steps per table, and groove step lengths in ticks.
• New projects — create an empty project on the card and start writing.

All edits are held in memory until you explicitly save, and every save goes through the write path described under the safety model. Files using the legacy 2-byte command encoding are read-only.

Inspect and export

• Project overview — four headline cards (BPM, playback length, scale, samples) over grouped Song / Instruments / File panels, a clickable full-width song map, FX-usage and groove summaries, collapsible instrument and sample sections, and auditionable sample rows with one-click access to the slice editor.
• Compare — diff two projects: shared and unique instruments and samples, metadata side by side.
• Song map — the arrangement drawn wide, with named section bands you drag out over the rows and notes pinned to a row ("Intro", "drop", "repeat x2"). Exports as PNG or SVG for a setlist or a rehearsal sheet, and saves to PTLibrarian_map.json on the card so a marked-up map travels with the project.
• Render to WAV — bounce a project to a stereo 16-bit WAV, or to stems, one WAV per channel that plays, delivered as a single zip. Rendered offline through the same scheduling as the preview, so it sounds like what you heard, with live progress on the buttons while it works.
• MIDI export — download any project as a Standard MIDI File (type 1, 24 PPQ, a tempo track plus one track per channel that plays anything, chain and project transpose applied, per-channel GRV groove switches and HOP flow honoured), or as MIDI stems: one .mid per playing channel, zipped, each with its own tempo track. Notes played by a MIDI instrument export on that instrument's configured channel at the firmware's velocity, with its note length producing a real note-off — so a project driving hardware exports ready to drive the same hardware from a DAW.

Device (USB)

• Live screen mirror — connect the picoTracker over USB (WebSerial) and watch the device screen in the browser, rendered pixel-for-pixel with the device's own bitmap font — or in one of six alternative faces (Terminal, Typewriter, Clean, Serif, Heavy, Hand) built at runtime from fonts your system already has, with the device's special glyphs always kept native. Full-refresh requests, a pop-out window for capture, full-screen mode and PNG snapshots. Reachable straight from the landing page, no SD card needed. Requires the https:// page, since WebSerial only exists in secure contexts.
• Audio-reactive effects — drive the effects from a live audio input. Pick the interface the picoTracker (or your mixer) is plugged into and the picture moves with what you are hearing; there is no sync problem because it is the real signal, a frame or two behind. Bass, mids, highs, level and a transient pulse are each available as a source, and every effect can carry up to three routings, each mapping a source to any numeric parameter of that effect with its own signed depth (−100% to +100%), so bloom intensity can ride the level while bloom radius rides the bass, and an effect can duck on a beat as well as swell on one. Your sliders stay where you put them and the modulation rides on top. Nothing is routed to the speakers, and no audio device is opened without a click.
• Output effects — the whole effects panel lives in a slide-out drawer on the right of the Device tab, so the mirror keeps the screen. Thirty-two GPU effects, for streaming, recording and projection: screen curve, wave warp, scanline jitter, block glitch, RGB offset, RGB planes, VHS ghosting, channel swap, colour grade, phosphor tint, phosphor glow, CRT scanlines, LCD panel, pixel grid, dot matrix, interlace, noise, vignette, posterise/dither, trails/rescan (a real feedback buffer with zoom, rotate and hue-spin, so the past compounds into tunnels and spirals), pixelate, hue cycle, kaleidoscope, refresh bar, invert/solarise — and the circuit-bent signal path ported from SIGNAL//ROT (same author): composite-cable decode (chroma bleed, NTSC edge rainbows, dot crawl, ringing), tape rot (streaky noise, dropouts, generation loss), sync damage (H wobble, V-roll with blanking bar, hum bar), the bent enhancer (oscillating edge ghosts, luma-hue, strobing inversion) and the luma-keyed rainbow map — plus background feedback: the letterbox region becomes a self-oscillating enhancer feedback loop (zoom, rotate, hue-spin, soft-clipped near-unity gain) seeded by the display's own glow and a video-synth oscillator, with the picture floating inset on top, wandered by a genlocked drift and re-seeded by a post-effects screen echo. Twelve of the colour and texture treatments carry an Apply to control — Picture, Backdrop or Both — so the loop can wear its own scanlines, rainbow maps or grain while the display stays clean — and CRT (Lottes), a port of Timothy Lottes' public-domain CRT shader (gaussian beam per scanline in linear light, grille/TV/VGA shadow masks). Twenty-three presets, a 🎲 Random button that rolls a curated look, per-parameter control, and settings that persist. Looks export and import as small JSON files for sharing. The original effect list and its tuned parameter ranges come from DMG Darkroom; they are reimplemented here as a single WebGL shader pass so they hold 60fps on live video rather than being applied to a still image.
• Built for capture — pick an output size (960×720, 1440×1080, 1280×720, 1920×1080 or Custom free width × height for banners and ultrawide walls; non-matching aspects pillarbox rather than stretch, with a Fill control if you would rather overscan and a Bars colour you can key out), then pop the mirror into its own chrome-free window (Document Picture-in-Picture where available — no title bar, no address bar) and capture that in OBS or any screen recorder — the popped-out window drives its own frames, so it keeps running when you switch away from the Librarian tab. A stand-in screen is drawn before anything is connected, so a look can be set up without the hardware to hand. Screen Text stamps over the mirror — stand-in or live device — replacing the song-title area or writing along the bottom row, in your colour on the theme's own background, so the screen can be retitled for capture. (Syphon users: the browser cannot publish Syphon; capture the pop-out in OBS and republish with a Syphon-server plugin.) All of it is display-side; nothing is ever sent to the device. Effects need WebGL. Without it the mirror still works, still honours the output size, fill, bars and pop-out, and tells you why the effects are off.
• Remote input — written, and deliberately disabled. The client half of a proposed FE 03 key-state opcode exists in the code, but the button is hidden and nothing is ever sent: on a real Advance the proposed opcode makes the screen flicker, which means the closed firmware already assigns inbound opcodes beyond the published protocol. Sending it blind risks provoking undefined behaviour on the device. This needs agreement on the firmware side before it's switched on — see ROADMAP.md.
• Card access while connected is a firmware matter (issues #1430 / #1432), not something a client can work around.

Maintain

• Problems tab — missing sample references, unused pool samples with reclaimable sizes, unused instruments, content-identical samples (byte-level dupe scan), duplicate .pti names, stale autosaves, unreadable files, backbone sounds, and the repair log. Most problems can be fixed from the tab itself.

• Fix all exact matches — one-click batch repair: every missing reference with an exact-name copy elsewhere on the card is restored by file copy, verified and audit-logged.

• Repair mode — two fixes for a broken reference: copy a matching WAV from the library or another project's pool into this project's pool (no project-file edit), or re-point the reference to an existing pool sample by rewriting only that attribute inside the project file.

• Cleanup and trash — unused pool samples move to PTLibrarian_Trash/ on the card rather than being deleted, and every row of the Browse tab's sample browser has a 🗑 that does the same for any library or pool file (with a louder warning when a project still uses it). The Trash tab lists what's in there and lets you restore a file to where it came from (refusing if something of that name has reappeared) or delete it permanently, individually or all at once.

• Extract as .pti — pull any instrument out of a project bank into instruments/ as a .pti (or download it if the card is read-only).

• Backup — copy the card to a folder or download it as a ZIP, with per-directory selection (.config.xml and .current always included).

• Chain colours travel with the card — write them to PTLibrarian_colours.json at the card root, and they're picked up on any machine.

• Setlists — click projects to add them to an ordered setlist, drag or ▲▼ to reorder, then export a lean, card-ready projects/ layout as a folder or ZIP. Folders can be numbered (01_, 02_ …) so the device lists them in playing order. Setlists save with their order.

The safety model

The card is opened read-only. Nothing is written unless you explicitly confirm a repair, an edit or an export. Every write follows the same path:

• Write permission is requested only at the moment you confirm.
• The file's modification time and size are checked against the scan first; if it changed since (say, you saved on the device), the write refuses and asks for a rescan rather than clobbering it.
• The original is copied to PTLibrarian_Backups/<timestamp>/ on the card before anything is overwritten.
• Before writing, a preview lists exactly which grid cells, chains, phrases, tables and grooves will change.
• After writing, the file is re-read, re-parsed and compared byte-for-byte against what you intended — phrase buffers, song grid, chains and transposes, tables, grooves, slice points, parameters, whichever applied.
• If verification fails, the write is rolled back automatically from the backup.
• Every operation is recorded in the browser and appended to PTLibrarian_Backups/audit-log.txt on the card, so the history travels with the card.

Deletions are never destructive: cleanup moves files to PTLibrarian_Trash/.

Everything runs locally. No server, no telemetry, no network access beyond loading the page. The hosted page installs as an offline-capable PWA.

Format compatibility

File-format knowledge is derived from the open-source picoTracker firmware (BSD-3-Clause): the XML project format and its run-length/hex <DATA> chunk encoding, .pti instruments, .ptt themes, .config.xml, the frozen FourCC command values, and SampleInstrument's slice and loop semantics.

The Advance firmware is closed source. Its format support here is interoperability work derived from real card files, not reverse engineering of the binary: geometry is inferred from buffer lengths rather than assumed, so the Advance's larger layout (256 song rows, 255 phrases, 128 tables, SAMPLESOURCE instruments with 32 slice pads, nested groove buffers, hex Font values) is read without hard-coding a firmware version. Parsers are deliberately tolerant — unknown instrument types, parameters and elements are preserved and displayed rather than rejected — so newer output should degrade gracefully.

Validated against real Advance card files spanning firmware 2.0-RC3, 2.1-BETA1, 2.2-BETA1, 2.3-Beta1 and 3.0, alongside the pico format from the open firmware. Some early betas used a short-lived 2-byte command encoding; that's detected from the buffer length rather than the version string, and those files open read-only with unknown commands shown as hex.

Development

The entire app is a single index.html — deliberately, so it can be hosted anywhere and audited in one read. Internal modules: PT (format knowledge: parsers, encoders, rewriters, playback timeline, MIDI, scales and the phrase generators), Cache (IndexedDB), Scanner, Zip (store-method ZIP writer), AudioPlayer, Demo (synthetic card), USB (Remote UI protocol, painting to an offscreen canvas), FX (effect definitions, presets, audio modulation and the WebGL renderer), AudioReact (audio input and band/transient analysis), Mirror (the visible output canvas, render loop and pop-out), SongPlayer (Web Audio) and one UI module.

Tests are zero-dependency Node scripts that extract modules straight out of index.html, so they always run against the shipped code:

node tests/parser.test.mjs   # 197 unit tests: formats, MIDI timing, slice/loop units, islands, pingpong, round-trips, generators, scales, audio analysis
node tests/fuzz.test.mjs     # seeded fuzz — parsers must never throw
node tests/audio.test.mjs    # renders the mix and a WAV export offline: no clipping, correct slice offsets, valid stems
node tests/e2e.mjs           # 328 browser checks (needs: npm i -D playwright)

The parser tests run round-trip checks against real Advance project files when they're present locally; those files are not in this repository.

The USB mirror renders each model with its own face: the classic picoTracker with the 8x8 Wide face and special-glyph page by nILS (public domain), and the Advance with the firmware's Ubuntu Mono-derived bitmap font (Ubuntu Font Licence 1.0 — see Ubuntu-Font-Licence-1.0.txt), on its native 720×720 square screen. The model is detected from the device's USB IDs at connect. The classic firmware's other two fonts are not redistributable and are intentionally not embedded. The official Flutter client was the reference for the Advance geometry.

The mirror's output effects are a reimplementation of the filter set from DMG Darkroom (MIT, same author): the effect list, parameter ranges and many of the tuned constants are carried over, but the filters themselves are rewritten from 2D-canvas passes over a still image into one WebGL shader pass that runs at video rate.

The single-file architecture and the backup-first safety model were first proven in M8 Librarian, this project's sibling for the Dirtywave M8.

Status and known limitations

Beta, as of v1.0.0 — see the warning at the top before you edit anything. CHANGELOG.md records what changed and why, including the bugs found and how they were caught; ROADMAP.md lists what's known to be missing.

What the player deliberately does not do, so nobody has to discover it the hard way: it is an honest sketch of the song, not an emulation of the device. Synth voices (SID/OPAL) are silent, most FX commands beyond VOL/PAN/KIL/GRV/HOP are ignored, and Advance SAMPLESOURCE amp envelopes are not applied, so notes on the Advance sustain where the device would let them decay. Remote input over USB stays disabled until the protocol question is settled with the firmware side (the mirror is view-only). Card access while the device is plugged in waits on firmware support.

Not affiliated with xiphonics. Use at your own risk — the read-only default, backup-first writes and automatic rollback exist precisely so that risk stays near zero.