Files

101 lines
5.1 KiB
Markdown

# 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 `feature/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 `goimports` 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.