docs: README and AGENTS.md

- README.md: project overview, quickstart (mise/docker/build), architecture diagram, feature roadmap linking to issues #1-#9 - AGENTS.md: development guide covering toolchain, key patterns, API conventions, akaiutil integration, formatting rules
2026-06-21 19:46:38 -07:00
parent 9657aaa523
commit 649a73984d
2 changed files with 220 additions and 0 deletions
@@ -0,0 +1,99 @@
+# AKAI Utils
+
+AKAI sampler toolkit — search, download, browse, extract, and package AKAI S900/S950/S1000/S1100/S3000/CD3000 sample libraries.
+
+Two interfaces:
+- **CLI** (`akai-fetch`) — search archive.org, download ISOs, extract WAVs
+- **Web UI / Electron** — full visual browser with disk inspection, sample preview, and disk packaging
+
+## Quickstart
+
+### Toolchain (mise)
+```bash
+mise trust        # first time only
+mise install      # installs go 1.26, node 22
+mise run build    # → ./fetch
+```
+
+### Docker
+```bash
+docker compose up --build
+# Open http://localhost:8080
+```
+
+### Build from source
+```bash
+# CLI
+mise run build
+./fetch search --filter vocal
+
+# Web server
+mise run serve
+# Open http://localhost:8080
+
+# Electron (macOS)
+mise run electron-deps
+mise run electron-build-mac
+```
+
+### CLI Usage
+```
+akai-fetch search [flags]          search archive.org for AKAI sampler ISOs
+akai-fetch list <identifier>       list downloadable ISO files in an item
+akai-fetch download [flags]        download ISOs from archive.org
+akai-fetch extract [flags]         extract WAVs from downloaded ISOs
+akai-fetch pipeline [flags]        search → download → extract in one command
+akai-fetch serve [flags]           start HTTP server with web UI
+```
+
+## Architecture
+
+```
+fetch serve (Go HTTP server, embedded web UI)
+  ├── /api/search       archive.org search
+  ├── /api/list         list ISO files in an item
+  ├── /api/download     download ISOs with SSE progress
+  ├── /api/extract      extract WAVs via akaiutil
+  └── /api/progress     SSE download progress stream
+
+electron/               Electron wrapper (spawns fetch serve as sidecar)
+  ├── main.js           main process
+  ├── preload.js        context bridge
+  └── package.json      electron-builder config
+
+third_party/akaiutil/   Vendored akaiutil 4.6.7 (C, GPLv2)
+scripts/extract_wavs.sh Bash wrapper for batch WAV extraction
+```
+
+## Tech Stack
+
+| Component   | Tech               | External Deps |
+|-------------|--------------------|---------------|
+| CLI server  | Go 1.26, stdlib    | 0             |
+| Web UI      | HTML/CSS/JS (vanilla) | 0          |
+| Electron    | Electron 33, electron-builder | Node deps |
+| Extraction  | akaiutil (C), bash | vendored      |
+
+Zero Go dependencies. The web UI uses no framework — vanilla JS, Web Audio API, Server-Sent Events.
+
+## Feature Roadmap
+
+See [open issues](https://git.notsosm.art/david/akai-utils/issues).
+
+| # | Feature | Status |
+|---|---------|--------|
+| — | Search, download, extract, pipeline (CLI) | done |
+| — | HTTP server + web UI + Electron shell | done |
+| #1 | Disk Browser — browse AKAI filesystem in web UI | todo |
+| #2 | Disk Inspector — detailed disk metadata | todo |
+| #3 | WAV→Disk Packager — create AKAI ISOs from WAVs | todo |
+| #4 | Batch S900 Compressor | todo |
+| #5 | Partition Backup/Restore | todo |
+| #6 | Direct-to-Disk Take Extraction | todo |
+| #7 | TAR Bulk Import/Export | todo |
+| #8 | Sample Tag Editor | todo |
+| #9 | Audio Preview Player | todo |
+
+## License
+
+MIT. Contains vendored [akaiutil 4.6.7](https://github.com/kmi9000/akaiutil) (GPLv2, (c) Klaus Michael Indlekofer).