# BeatGlow agent guide BeatGlow is a Go music visualizer for embedded Linux audio players, especially Raspberry Pi systems. Read the relevant code and these guides before changing it: - [Coding conventions](docs/agents/CodingConventions.md) - [Operational guidance](docs/agents/OperationalDoctrine.md) - [Go documentation](docs/agents/GoDocs.md) ## Git and Gitea workflow - Create and switch to a feature branch before editing files or making commits. - Never commit directly on `main` or `master`. - Use descriptive branch names, such as `feat/mpd-fifo-output-monitoring`, `fix/readme-images`, or `chore/agent-instructions`. - Continue on an existing feature branch when working on the same task. Create a separate branch from the target branch for unrelated work. - If changes already exist on `main` or `master`, create a feature branch that preserves those changes before committing them. - Open pull requests against the target branch; do not merge or push changes directly to `main` or `master` unless the user explicitly requests it. - Base new work on `main` (normally `origin/main`); fetch when remote state matters. Do not discard local changes or rewrite unrelated commits to update the base. - Make focused commits with concise, descriptive subjects. - Use the configured remote; this project uses Gitea. MR and PR refer to the same review workflow here. Do not assume GitHub tooling works with Gitea. - PR descriptions should explain the problem, resulting behavior, verification, and remaining limitations. Reference an issue only when one exists, and mark it closed only if the change completes it. Target the branch the work is based on. - When API authentication is unavailable, push the requested feature branch and provide the creation link; distinguish a pushed branch from a submitted PR. ## Project map | Location | Responsibility | | --- | --- | | `cmd/beatglow/` | CLI, configuration discovery, installation and startup | | `controller.go`, `context.go`, `hardware.go` | Component setup, events, rendering and audio processing | | `config/` | HCL configuration and user settings; examples in `beatglow.conf` | | `app/layout/`, `app/widget/`, `app/shader/`, `app/font/` | Screens, widgets, visual effects and embedded fonts | | `player/` | Player contracts, registration and automatic detection | | `player/mpd/` | MPD connections, commands, metadata and artwork | | `player/raudio/`, `player/volumio/`, `player/moode/`, `player/runeaudio/` | Distribution-specific integrations; inspect implementation completeness | | `player/all/` | Side-effect imports that load player drivers | | `sound/` | PCM file/FIFO sources and audio diagnostics | | `hardware/` | Display setup, combined displays, Linux network information and inputs | | `internal/`, `testdata/` | Internal helpers and test fixtures | | `asset/image/`, `doc/hardware/` | README illustrations and hardware references | Player detection runs in ascending priority order. Register distribution-specific detectors ahead of generic MPD and import new drivers through `player/all/`. Keep PCM sample format, channels and rate consistent with the configured producer. ## Build and verification Use the Go version required by `go.mod` or newer. The display dependency currently resolves to `../display`; check that checkout exists before diagnosing dependencies. Do not silently remove the replacement or upgrade dependencies for unrelated work. ```sh # Existing Makefile target: Linux ARM binary, written to ./beatglow make beatglow # Linux ARM64 binary without overwriting the repository's local executable GOOS=linux GOARCH=arm64 go build -o /tmp/beatglow ./cmd/beatglow # Execute on Linux; narrow package paths for focused changes go test ./... go vet ./... # On macOS: compile Linux tests only; /usr/bin/true does not execute them GOOS=linux GOARCH=arm64 go test -exec /usr/bin/true ./player/... git diff --check ``` Run `gofmt` on changed Go files. The Makefile has no test, lint, integration-test, or generation targets. Linux wireless helpers prevent some packages from building natively on macOS. Report cross-compilation separately from executed tests and hardware verification. Use race tests on Linux when changing shared state. Known failures observed during setup include a log-format vet error in `app/font/font.go` and a float32/float64 test mismatch in `internal/calc/calc_test.go`. Recheck their current status; report unrelated failures without hiding them or expanding scope automatically. ## Assets and dependencies The repository uses an allowlist `.gitignore`. Verify new docs and assets appear in Git; add narrow exceptions when needed. README images belong in `asset/image/`. Check that all Markdown image targets exist and are tracked. PDF, BDF and TTF filters are configured in local `.gitattributes`; check the actual attributes and Git LFS availability before adding or changing these files. Preserve real assets and LFS objects. Never substitute placeholders to pass a build. ## Sources Structure inspired by [Flow's AGENTS.md](https://github.com/onflow/flow-go/blob/master/AGENTS.md). The linked local guides are project-specific adaptations, not verbatim imports.