andrewlb notes

Takoyaki

Takoyaki

Code

Tools

Claude CodeRustTauriNext.jsTypeScriptSQLitebinrw

What worked

The parser isolation strategy paid off immediately: building the clean-room ot-parser crate with byte-exact round-trip tests before touching any write path meant the foundation was validated before risk increased. The three-layer safety model (snapshot + dry-run + atomic writes with F_FULLFSYNC) gives musicians confidence that creative work is never at risk. Choosing the same Tauri/Rust/React stack as Wallflower meant shared learnings across both audio-adjacent desktop apps.

What broke

Phase 6 discovered the database was in-memory — backup history vanished on restart. Phase 7 found the parser was built but never wired into read commands — project detail showed 128 empty stubs. Both were caught in audit, but they reveal how AI-generated code can pass all tests while missing fundamental integration. Sixteen human verification items remain pending because they require a real Octatrack in USB mode — no amount of fixture tests replaces hardware-in-the-loop validation.

Roles

I defined the target community (Octatrack users underserved since OctaEdit was abandoned ~10 years ago), the three-layer safety model, and the decision to build a clean-room parser (MIT license, no GPL contamination). Claude Code wrote the binary parsers, atomic write engine, Tauri IPC commands, React UI, and backup infrastructure.

Takoyaki (Octatrack Project Manager)

Overview

Takoyaki is a native macOS desktop application for safe backup, versioning, and file management of Elektron Octatrack music production hardware. It fills a gap the Octatrack community has had since OctaEdit was abandoned ~10 years ago — a reliable, open-source tool for managing projects and samples with zero risk of data loss or corruption.

Core purpose: An Octatrack user can manage their projects and samples with complete confidence that their creative work is never at risk — every destructive operation is snapshot-protected, previewed, and atomically applied.

Target users: Elektron Octatrack MkII users on macOS who want reliable project backup, versioning, and sample management.

What It Does

  • Automatic OT volume detection and clean-room binary parsing of all OT file types with byte-exact round-trip fidelity
  • Three-layer safety model: snapshot before write (SHA-256 verified), dry-run preview, and atomic staged writes with F_FULLFSYNC
  • Project browser with bank grid, sample slot tables, and health checks (missing samples, wrong formats, bad sample rates)
  • Full project backup to Mac with checksum verification and one-click restore to any prior snapshot
  • Project duplication, rename, zip export, and cross-project bank copy with automatic slot remapping
  • Sample assignment to Flex/Static slots with format validation and atomic multi-file transactions
  • Optional Wallflower library integration for searching samples by key, BPM, and tags — graceful degradation when absent

How It Fits Together

Tauri 2.x wraps a Rust backend (binary parsing via binrw/nom, atomic file I/O, SQLite for state) with a Next.js 15 / React 19 frontend. The ot-parser crate is a standalone library with zero I/O dependencies. tauri-specta auto-generates TypeScript types from Rust command signatures, eliminating manual type synchronization across the IPC boundary.

Architecture Decisions

  • Clean-room parser instead of forking ot-tools-io — MIT license; ot-tools-io is GPL v3 and self-described as unstable
  • Three-layer safety model — OT project corruption is unacceptable; belt-and-suspenders justified for irreplaceable creative data
  • F_FULLFSYNC on macOS — Standard fsync doesn't guarantee disk flush; F_FULLFSYNC does. Critical for CF card hot-unplug safety
  • Staging on same filesystem — Cross-filesystem renames are not atomic on macOS FAT32
  • USB disk mode only — No MIDI/SysEx. Simpler, safer, covers all file management use cases
  • Wallflower as optional integration — Read-only SQLite connection to Wallflower's database. Target all OT users, not just Wallflower users
  • Newtype index wrappers — ProjectSlotId, BankSlotId, BankNumber prevent index confusion at compile time in binary format code

What Changed After Dogfooding

The in-memory database bug (Phase 6) and the unwired parser (Phase 7) were both cases where the app appeared to work in development but broke on real use. The database issue only surfaced on restart; the parser issue only showed when someone scrolled through all 128 slots. Both point to the same lesson: AI-generated integration layers need explicit verification of data flow end-to-end, not just component-level tests. The byte-exact round-trip tests on the parser, by contrast, caught every binary format issue before it could reach the write path — isolation and focused testing work.

Weaknesses & Open Questions

  • macOS only — Tauri supports cross-platform but Windows/Linux are untested
  • OT MkII only — No MkI format support; binary differences are unknown
  • No arrangement editing — Read-only for arrangement files
  • Unknown binary sections — Preserved as raw bytes but not interpreted; format coverage is necessarily incomplete
  • No real hardware testing yet — Volume detection, FAT32 atomicity, and visual verification all require a real OT in USB mode

Ecosystem Role

Takoyaki is the bridge between Wallflower (sample library) and the Octatrack hardware — musicians capture and analyze jams in Wallflower, then deploy samples to the OT via Takoyaki. It shares the Tauri/Rust/React stack with Wallflower and validates that stack choice for audio-adjacent desktop apps. It is the portfolio's first clean-room binary format project and first community-serving open-source tool (addressing a documented need on Elektronauts forums).