From 8488e6ae646743369d2244656d8ce1d54532af0f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 02:43:13 +0000 Subject: [PATCH 1/2] core: Add a README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The repository had no README.md at the root and none in docs/, so the GitHub landing page for the project that every plugin in the ecosystem depends on was empty — despite CONTRIBUTING.md, CHANGELOG.md and a 23-file docs/ tree all existing. Covers what FeedBack is, Docker and bare-metal quick starts, the environment variables, both song formats (including that feedpak-spec is the authority for the format, not this repo), an orientation to the plugin system with pointers into docs/, and the development commands. Two things contributors get wrong are called out explicitly: the plugin directory name must equal plugin.json's id, and commits need a DCO sign-off. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01B4NYejYW2dW7dNtYh7srDy Signed-off-by: Claude --- CHANGELOG.md | 5 ++ README.md | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f9e277d0..5cfa7167 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -73,6 +73,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 falling through to a future anchor. ### Added +- **README.** The repository had no `README.md` at the root or in `docs/`, so + the landing page for the project every plugin depends on was blank. Covers + what FeedBack is, Docker and bare-metal quick starts, the environment + variables, both song formats and where the format spec actually lives, an + orientation to the plugin system, and the development commands. - Library card actions can now provide per-song label and icon callbacks, so plugins can render dynamic card badges without DOM patching. - **Core reader for source rigs (feedpak 1.18.0).** A pack can declare what a diff --git a/README.md b/README.md new file mode 100644 index 00000000..da9396f1 --- /dev/null +++ b/README.md @@ -0,0 +1,147 @@ +# FeedBack + +A self-hosted web app for browsing, playing, and practicing interactive music +notation — a scrolling note highway, standard notation, synced lyrics, and live +note detection from your instrument, all running on hardware you own. + +Charts come from importing Guitar Pro (GP3–GP8) or MusicXML, or from authoring +in the built-in editor. FeedBack stores them in its own open, hand-editable +package format. + +[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) + +--- + +## Quick start + +FeedBack ships as a Docker container. + +```bash +git clone https://github.com/get-flashbacks/feedBack.git +cd feedBack +LIBRARY_PATH=/path/to/your/songs docker compose up -d +``` + +Open . + +`LIBRARY_PATH` points at the folder holding your songs; it defaults to +`./library` if unset. Config and caches persist in a named `feedBack-config` +volume, so they survive a container rebuild. + +There is a separate `docker-compose.nas.yml` for NAS deployments, and +`build-proxmox-ct.sh` for a Proxmox container. + +### Running without Docker + +```bash +pip install -r requirements.txt +python main.py # 0.0.0.0:8000 +HOST=127.0.0.1 PORT=8001 python main.py # or pick your own +``` + +### Configuration + +Set these in `docker-compose.yml` or the environment: + +| Variable | Purpose | +| --- | --- | +| `DLC_DIR` | Song library folder inside the container (default `/dlc`) | +| `CONFIG_DIR` | Persistent config + cache (default `/config`) | +| `LOG_LEVEL` | `DEBUG` \| `INFO` \| `WARNING` \| `ERROR` (default `INFO`) | +| `LOG_FORMAT` | `json` \| `text` (default `text`, coloured console) | +| `APP_SOURCE_URL` | Overrides the Settings → About source link | +| `APP_LICENSE_URL` | Overrides the licence link — set this explicitly if you host on a non-GitHub forge | + +--- + +## Song formats + +**Loose folder** — a directory of arrangement XML plus an audio file, with an +optional `manifest.json` and album art. Played directly, no import step. + +**Sloppak** — FeedBack's own package format, and the preferred one for new +work. It exists interchangeably as a `.sloppak` zip (for distribution) or a +`.sloppak/` directory (for authoring), holding a YAML manifest, per-arrangement +note data, audio stems, cover art, and syllable-level lyrics. + +The format itself is specified outside this repo, in +[got-feedback/feedpak-spec](https://github.com/got-feedback/feedpak-spec) — +published there as **feedpak**; the same on-disk format this codebase still +calls **sloppak** internally. **The spec is the authority: a new manifest key +is not part of the format until it lands there.** CI enforces this, and there +is no in-repo bypass. See [docs/sloppak-spec.md](docs/sloppak-spec.md) for the +local code map and [docs/feedpak-spec-gate.md](docs/feedpak-spec-gate.md) for +how the gate works. + +--- + +## Plugins + +Plugins are the main extension point, and most of FeedBack's features are built +as one. A plugin lives in `plugins//` with a `plugin.json` manifest and can +contribute any mix of frontend screen, backend routes, and settings panel. + +> The directory name must equal the manifest's `id` exactly, case-sensitive. A +> mismatch is a silent skip at discovery, and it is the most common reason a +> plugin "won't load". + +A few of the things a plugin can do: + +- **Replace the highway renderer** — declare `"type": "visualization"` and + export a `window.feedBackViz_` factory. Works in the main player and + per-panel under split screen. +- **Layer an overlay** on top of whichever renderer is active — fretboard + diagrams, chord labels, practice feedback. +- **Score playing** and feed per-note judgments back so any renderer can light + up the gems. +- **Register a mixer fader**, keyboard shortcuts, a library source, or a + detachable pane the user can pop into its own window. + +Start with [feedBack-plugin-template](https://github.com/get-flashbacks/feedBack-plugin-template). +The contracts are documented in [CLAUDE.md](CLAUDE.md), with deeper guides in +[docs/](docs/) — see [plugin-v3-ui.md](docs/plugin-v3-ui.md), +[plugin-styles.md](docs/plugin-styles.md), +[plugin-modules.md](docs/plugin-modules.md), +[plugin-panes.md](docs/plugin-panes.md), and +[capability-recipes.md](docs/capability-recipes.md). + +--- + +## Development + +```bash +pip install -r requirements.txt -r requirements-test.txt +pytest # Python suite +npm run test:js # JS unit tests +npm test # Playwright end-to-end +npm run lint # ESLint +bash scripts/build-tailwind.sh # regenerate static/tailwind.min.css +``` + +Tailwind is served as a **prebuilt** stylesheet, never the Play CDN — the CDN's +runtime JIT rescanned the DOM on the main thread and cost ~26% of frames. CI +rebuilds and diffs the committed CSS, so run the build script and commit the +result when you add new classes. + +`VERSION` at the repo root is the single source of truth for the version, and +is synced automatically when a desktop release is cut. `GET /api/version` +serves it. + +--- + +## Contributing + +Please read [CONTRIBUTING.md](CONTRIBUTING.md) first. Two things to know up +front: + +- **Every commit needs a DCO sign-off** (`git commit -s`). +- **Never push directly to `main`** — branch, then open a PR. + +Curated plugins should be AGPL-3.0 or AGPL-compatible (MIT, BSD, Apache-2.0). + +--- + +## License + +[AGPL-3.0-only](LICENSE). Contributions are inbound = outbound under the same +terms. From ad48da0f4183e4e08643987e83dc14eb1a3bd422 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 03:00:04 +0000 Subject: [PATCH 2/2] core: correct three README claims flagged in review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All three verified against the source rather than taken on faith. The folder-name rule was simply wrong, and it is worth being precise because the claim is repeated across several plugin repos' CLAUDE.md files: discovery in plugins/__init__.py registers each plugin under its manifest id and never compares that to the directory name. The only dirname-vs-id comparison is _is_bundled (plugins/__init__.py:1227), which needs all three of PLUGINS_DIR location, "bundled": true, and a matching name — and it decides duplicate-resolution precedence, not whether a plugin is discovered. A mismatched folder loads fine. The real skip conditions are a missing plugin.json, a manifest that fails to parse, or an id that is absent, empty, or not a string. CONFIG_DIR's /config default holds only inside the container, where docker-compose sets it; bare metal falls back to ~/.local/share/feedback (server.py:157). The DLC_DIR row already carried that qualifier. The editor is a separate plugin, not bundled — the Dockerfile ships this repo's plugins/ tree, which has no editor, and v3 only reveals the handoff when window.editSong exists. Links to the plugin instead of implying it ships in the box. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01B4NYejYW2dW7dNtYh7srDy Signed-off-by: Claude --- README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index da9396f1..589789f9 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,8 @@ notation — a scrolling note highway, standard notation, synced lyrics, and liv note detection from your instrument, all running on hardware you own. Charts come from importing Guitar Pro (GP3–GP8) or MusicXML, or from authoring -in the built-in editor. FeedBack stores them in its own open, hand-editable -package format. +in the [Song Editor plugin](https://github.com/got-feedback/feedBack-plugin-editor). +FeedBack stores them in its own open, hand-editable package format. [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) @@ -46,7 +46,7 @@ Set these in `docker-compose.yml` or the environment: | Variable | Purpose | | --- | --- | | `DLC_DIR` | Song library folder inside the container (default `/dlc`) | -| `CONFIG_DIR` | Persistent config + cache (default `/config`) | +| `CONFIG_DIR` | Persistent config + cache. `/config` inside the container; on bare metal it defaults to `~/.local/share/feedback` | | `LOG_LEVEL` | `DEBUG` \| `INFO` \| `WARNING` \| `ERROR` (default `INFO`) | | `LOG_FORMAT` | `json` \| `text` (default `text`, coloured console) | | `APP_SOURCE_URL` | Overrides the Settings → About source link | @@ -81,9 +81,12 @@ Plugins are the main extension point, and most of FeedBack's features are built as one. A plugin lives in `plugins//` with a `plugin.json` manifest and can contribute any mix of frontend screen, backend routes, and settings panel. -> The directory name must equal the manifest's `id` exactly, case-sensitive. A -> mismatch is a silent skip at discovery, and it is the most common reason a -> plugin "won't load". +> Name the directory to match the manifest's `id` (case-sensitive). That +> pairing is what marks a plugin as a bundled core one for duplicate +> resolution — it is *not* a discovery requirement, since the loader registers +> plugins by their manifest `id` whatever the folder is called. A plugin that +> genuinely won't load is usually missing `plugin.json`, has a manifest that +> fails to parse, or has an `id` that is absent, empty, or not a string. A few of the things a plugin can do: