How icherniukh/ep133-krate works
1. What this repo is
- ep133-krate is a Python 3.11+ sample manager for the EP-133 KO-II.
- It is centered on a reverse-engineered MIDI SysEx protocol; PROTOCOL.md and the captures/ artifacts are the architectural source of truth.
2. Top-level shape
- src/core/ is the protocol/device domain layer.
- src/cli/ is the command-line interface.
- src/tui/ is the Textual-based terminal UI.
- src/mobile/ is a planned/early mobile app surface.
- tests/ contains most of the protocol and behavior verification, including emulator-backed end-to-end tests.
3. Main runtime path
- User action enters through either the CLI entrypoint (krate.py / src/cli/cli_main.py) or the TUI (src/tui/app.py).
- Both frontends call into the same core client/operations layer.
- The core layer talks to the hardware over MIDI, and responses are parsed back into domain models for rendering or file transfer.
4. Core domain boundary
- src/core/client.py is the low-level transport-facing client.
- src/core/operations.py and src/core/ops.py hold the stateful workflows, such as upload transactions that span multiple protocol messages.
- src/core/models.py, types.py, and naming.py define protocol data structures and wire encodings.
- audio.py, backup.py, and waveform_store.py handle sample-specific concerns outside the raw transport layer.
5. Protocol encoding layer
- types.py contains the wire primitives, especially Packed7, which exists because SysEx is 7-bit-clean.
- Binary payloads such as PCM audio and JSON metadata are encoded/decoded here before they cross the MIDI boundary.
- This keeps the transport layer unaware of the encoding details and makes serialization symmetric and testable.
6. CLI architecture
- src/cli/parser.py routes subcommands into command modules like cmd_audio.py, cmd_slots.py, cmd_system.py, and cmd_transfer.py.
- Commands are rendered through an injected View abstraction in display.py and formatters.py, with concrete terminal, silent, and JSON output modes.
- This is a deliberate boundary: command logic can be tested without stdout patching or subprocesses.
7. TUI architecture
- The TUI is a Textual app built from src/tui/app.py, ui.py, state.py, actions.py, and supporting widgets/dialogs.
- Device access is isolated in src/tui/worker.py: blocking EP133Client calls run in a background thread so the async UI stays responsive.
- waveform_widget.py and the waveform cache logic support braille waveform rendering and avoid unnecessary device round-trips when a fingerprint is already known.
8. Audio and transfer pipeline
- Upload/download flows move between local files and slot metadata, with src/core/audio.py and src/core/operations.py coordinating conversion and protocol sequencing.
- The README notes sox as a required external tool for audio conversion/optimization, so audio handling is not purely in-process Python.
- The transfer path also includes recovery/verification behavior, reflecting the device’s quirks captured in protocol evidence.
9. Device/protocol realities that shape the design
- The repo encodes known device behavior, such as re-initializing after downloads, avoiding stale metadata paths, and using runtime inventory over incomplete device metadata.
- These constraints influence the client/operations design more than the UI design, because correctness depends on message ordering and session state.
- PROTOCOL.md plus the capture files are therefore architectural dependencies, not just documentation.
10. Support tooling and external surfaces
- scripts/ contains utilities for capture upload, MIDI proxying, mobile bridging, and capture cleanup.
- tests/emulator.py and the tests/e2e/ suite provide a simulated device boundary for integration testing.
- GitHub Actions, linting, and release workflows show the repo is designed for reproducible validation and packaging.
11. Mobile roadmap
- src/mobile/ exists as a separate UI surface with screens for slot lists and upload queue management.
- It is architecturally distinct from the CLI/TUI, but still expected to reuse the same core protocol layer.
- The README positions native mobile as a roadmap item rather than the primary shipped interface.
12. How to diagram it
- A good diagram would show three client surfaces on top: CLI, TUI, and future mobile.
- All three converge on the shared core domain layer.
- The core layer then connects to the physical EP-133 over MIDI SysEx, with protocol docs/captures feeding development and tests verifying behavior against emulation and recorded traffic.
Main entry points: operations.py Operations · client.py Client · cmd_transfer.py CLI cmds · types.py Protocol types
Components 21
Client surfaces
User-facing entry points that invoke the shared core layer.
- krate.py · Top-level script entry into the CLI experience.
krate.py - CLI main · Initializes command-line execution and dispatch.
src/cli/cli_main.py - Parser · Routes subcommands into command handlers.
src/cli/parser.py - CLI cmds · Audio, slot, system, and transfer command modules.
src/cli/cmd_transfer.py - CLI view · Output abstraction and formatters for terminal, silent, and JSON rendering.
src/cli/display.py - TUI app · Textual-based terminal application entrypoint.
src/tui/app.py - TUI UI · Screens, actions, selectors, dialogs, and state for the terminal interface.
src/tui/ui.py - Worker · Runs blocking device calls off the UI thread.
src/tui/worker.py - Mobile app · Planned mobile-facing shell that reuses the shared protocol layer.
src/mobile/app.py - Mobile screens · Slot list and upload queue screens for the mobile roadmap.
src/mobile/screens/slot_list.py
Core domain
Protocol, transport, and device workflows for the EP-133.
- Client · Low-level MIDI-facing EP-133 client used by all frontends.
src/core/client.py - Operations · Stateful multi-message workflows such as uploads and recovery.
src/core/operations.py - Protocol types · Wire primitives, packed 7-bit encoding, and protocol data structures.
src/core/types.py - Models · Protocol-facing domain objects and metadata structures.
src/core/models.py - Audio flow · PCM/sample conversion, validation, and upload/download preparation.
src/core/audio.py - Backup · Backup and restore logic for device content.
src/core/backup.py - Waveforms · Fingerprint and waveform cache to avoid redundant device round-trips.
src/core/waveform_store.py - MIDI transport · Underlying MIDI I/O adapter beneath the client.
src/core/midi_transport.py
Protocol evidence
Docs, captures, and emulator-backed verification that shape the implementation.
- PROTOCOL.md · Primary reverse-engineered protocol specification.
PROTOCOL.md - Captures · Recorded device traffic and traces used as source evidence.
captures - Emulator tests · Simulated device boundary used for end-to-end verification.
tests/emulator.py
Connections 21
- krate.py → CLI main: starts · Top-level script launches CLI execution.
- CLI main → Parser: dispatches · CLI startup routes into subcommand parsing.
- Parser → CLI cmds: invokes · Parsed subcommands enter command modules.
- CLI cmds → CLI view: renders via · Command output flows through the injected view layer.
- CLI cmds → Operations: uses · Commands call shared workflows rather than device APIs directly.
- TUI app → TUI UI: composes · Textual app builds screens and actions from UI modules.
- TUI UI → Worker: offloads · Blocking device operations are sent to the background worker.
- Worker → Client: calls · Worker executes EP-133 client operations off the UI thread.
- Mobile app → Mobile screens: navigates · Mobile shell presents the roadmap screens.
- Mobile screens → Operations: reuses · Mobile UI is expected to share the same workflow layer.
- Operations → Client: orchestrates · Workflows coordinate protocol exchanges through the client.
- Client → MIDI transport: transports over · Client depends on MIDI I/O for hardware communication.
- Client → Protocol types: encodes/decodes · Client uses wire primitives and packed 7-bit payloads.
- Protocol types → Models: shapes · Wire primitives feed protocol-domain models.
- Operations → Audio flow: coordinates · Upload/download flows convert and sequence audio payloads.
- Operations → Backup: manages · Backup and restore behavior is implemented in workflows.
- Audio flow → Waveforms: consults · Audio handling uses waveform fingerprints and cache state.
- PROTOCOL.md → Protocol types: defines · Protocol documentation informs the wire layer.
- Captures → PROTOCOL.md: evidences · Captured traffic underpins the protocol specification.
- Emulator tests → Operations: verifies · Integration tests exercise workflows against an emulated device.
- Emulator tests → Client: simulates · Emulator-backed tests stand in for the hardware boundary.