Files
beatglow/AGENTS.md
T

5.1 KiB

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:

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.

# 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. The linked local guides are project-specific adaptations, not verbatim imports.