Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
f2c9aeb3a8
|
No files matched your search
@@ -16,8 +16,6 @@
|
|||||||
|
|
||||||
!README.md
|
!README.md
|
||||||
!LICENSE
|
!LICENSE
|
||||||
!/AGENTS.md
|
|
||||||
!/docs/agents/*.md
|
|
||||||
|
|
||||||
# README screenshots and wiring illustrations
|
# README screenshots and wiring illustrations
|
||||||
!/asset/image/beatglow-*.gif
|
!/asset/image/beatglow-*.gif
|
||||||
|
|||||||
@@ -1,100 +0,0 @@
|
|||||||
# 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.
|
|
||||||
@@ -59,6 +59,16 @@ During the shader, running various shader effects, running 44.1kHz stereo audio:
|
|||||||
|
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
|
When the audio source uses `type = "fifo"`, MPD-based players check the output
|
||||||
|
status after connecting and every 15 seconds. BeatGlow logs a warning if the
|
||||||
|
matching output is disabled or missing, and reports when it becomes enabled.
|
||||||
|
It does not enable outputs automatically. A single FIFO output is selected
|
||||||
|
automatically. If MPD has multiple FIFO outputs, set `output = "BeatGlow"` in
|
||||||
|
the `audio` block, using the name of the MPD output that writes to your FIFO.
|
||||||
|
Older MPD versions that omit the output plugin also require this name.
|
||||||
|
MPD does not expose FIFO paths through its output status, so the configured
|
||||||
|
output must write to the same path as the audio source.
|
||||||
|
|
||||||
Minimal requirements:
|
Minimal requirements:
|
||||||
- Linux Computer (Raspberry Pi 3B+)
|
- Linux Computer (Raspberry Pi 3B+)
|
||||||
- Supported display
|
- Supported display
|
||||||
|
|||||||
@@ -161,6 +161,10 @@ audio {
|
|||||||
# Path to the audio stream.
|
# Path to the audio stream.
|
||||||
path = "/tmp/beatglow.fifo"
|
path = "/tmp/beatglow.fifo"
|
||||||
|
|
||||||
|
# MPD output name (optional when MPD has exactly one FIFO output).
|
||||||
|
# Must match the name of the output writing to the path above.
|
||||||
|
# output = "BeatGlow"
|
||||||
|
|
||||||
# Rate is the sampling rate.
|
# Rate is the sampling rate.
|
||||||
rate = 44100
|
rate = 44100
|
||||||
|
|
||||||
|
|||||||
@@ -88,6 +88,7 @@ type Encoder struct {
|
|||||||
|
|
||||||
// Audio source provides PCM samples.
|
// Audio source provides PCM samples.
|
||||||
type Audio struct {
|
type Audio struct {
|
||||||
|
Output string `hcl:"output,optional"`
|
||||||
Type string `hcl:"type"`
|
Type string `hcl:"type"`
|
||||||
Path string `hcl:"path,optional"`
|
Path string `hcl:"path,optional"`
|
||||||
Host string `hcl:"host,optional"`
|
Host string `hcl:"host,optional"`
|
||||||
|
|||||||
@@ -30,6 +30,10 @@ type Controller struct {
|
|||||||
recorderPalette color.Palette
|
recorderPalette color.Palette
|
||||||
}
|
}
|
||||||
|
|
||||||
|
type audioSourceConfigurator interface {
|
||||||
|
SetAudioSource(config.Audio)
|
||||||
|
}
|
||||||
|
|
||||||
func New(config *config.Config) (*Controller, error) {
|
func New(config *config.Config) (*Controller, error) {
|
||||||
log := logrus.NewEntry(logrus.StandardLogger())
|
log := logrus.NewEntry(logrus.StandardLogger())
|
||||||
|
|
||||||
@@ -59,6 +63,9 @@ func New(config *config.Config) (*Controller, error) {
|
|||||||
c.teardown(log)
|
c.teardown(log)
|
||||||
return nil, err
|
return nil, err
|
||||||
}
|
}
|
||||||
|
if p, ok := c.ctx.player.(audioSourceConfigurator); ok {
|
||||||
|
p.SetAudioSource(config.Audio)
|
||||||
|
}
|
||||||
if err := c.configureInputs(log, &config.Input); err != nil {
|
if err := c.configureInputs(log, &config.Input); err != nil {
|
||||||
log.WithError(err).Error("fatal error setting up inputs")
|
log.WithError(err).Error("fatal error setting up inputs")
|
||||||
c.teardown(log)
|
c.teardown(log)
|
||||||
|
|||||||
@@ -1,19 +0,0 @@
|
|||||||
# Coding conventions
|
|
||||||
|
|
||||||
- Use idiomatic Go, `goimports`, and the surrounding package's naming and import style.
|
|
||||||
Extend existing contracts instead of introducing parallel registries or layers.
|
|
||||||
- Wrap propagated errors with useful context and `%w`. Use `errors.Is` or
|
|
||||||
`errors.As` when callers need to recognize them.
|
|
||||||
- Decide recovery at the caller: a disconnected MPD server can be retried, while
|
|
||||||
unusable startup configuration should return an error. Explain intentional
|
|
||||||
recovery; avoid silent failures and unnecessary process termination.
|
|
||||||
- Use structured Logrus fields for component, device, connection and path context.
|
|
||||||
Keep frame/sample loops quiet; log meaningful transitions and actionable failures.
|
|
||||||
- Keep display refreshes and controller event handling responsive. Close owned
|
|
||||||
connections, files and tickers; make goroutine shutdown explicit. Review channel
|
|
||||||
ownership and synchronization when changing lifecycle behavior.
|
|
||||||
- Validate protocol responses, HCL values, dimensions and PCM formats before use.
|
|
||||||
Respect Linux build constraints and hardware-specific dependencies.
|
|
||||||
- Put focused tests beside implementations. Cover parsing, malformed input,
|
|
||||||
detection precedence, failures and recovery with temporary files or fake servers.
|
|
||||||
Unit tests should run without physical GPIO, displays or a live MPD instance.
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
# Go documentation
|
|
||||||
|
|
||||||
- Document new or changed exported APIs and interfaces. Explain private code when
|
|
||||||
its lifecycle, protocol behavior or invariants are not clear from the code.
|
|
||||||
- Start API comments with the declared name and write complete sentences. Use
|
|
||||||
paragraphs and Go doc links such as `[Player]` for relevant Go identifiers.
|
|
||||||
- Describe the contract: parameter constraints, units, defaults, return values,
|
|
||||||
blocking behavior and resource ownership when they matter to callers.
|
|
||||||
- For error returns, explain actionable failure conditions and recognizable
|
|
||||||
sentinel errors that the implementation actually returns. Do not invent error
|
|
||||||
types, guarantees or recovery behavior.
|
|
||||||
- State concurrency restrictions explicitly. Do not assume a type is safe for
|
|
||||||
concurrent use simply because no warning exists.
|
|
||||||
- Keep interface contracts and implementations consistent. Explain meaningful
|
|
||||||
deviations rather than copying comments mechanically.
|
|
||||||
- For documentation-only tasks, preserve runtime behavior. Correct inaccurate
|
|
||||||
documentation after checking the implementation; keep separate logic fixes scoped.
|
|
||||||
- Wrap prose around 100 characters where practical. Avoid documenting obvious
|
|
||||||
implementation steps or adding repetitive boilerplate.
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
# Operational guidance
|
|
||||||
|
|
||||||
- Follow the user's task and established preferences. Continue authorized work
|
|
||||||
without repeatedly asking for confirmation; clarify genuinely missing decisions.
|
|
||||||
- Inspect the code, branch, diff and relevant documentation before making changes.
|
|
||||||
Verify external protocol behavior against upstream documentation when needed.
|
|
||||||
- Keep changes within scope and preserve unrelated work. Explain a necessary
|
|
||||||
scope change instead of silently bundling cleanup or dependency updates.
|
|
||||||
- Communicate directly and briefly. Explain findings, behavior changes and remaining
|
|
||||||
uncertainty; avoid flattery and unsupported claims.
|
|
||||||
- Review the surrounding component after editing, including configuration,
|
|
||||||
registration, lifecycle and callers affected by an interface change.
|
|
||||||
- Test the behavior that changed. State which tests ran, which checks only
|
|
||||||
compiled, and what requires Linux, hardware, network access or authentication.
|
|
||||||
- Describe recoverable device/server failures realistically. Do not label an issue
|
|
||||||
critical without evidence or claim a fix is verified on hardware without testing it.
|
|
||||||
- Finish with concise results, links to changed files or the PR, and material
|
|
||||||
limitations. Never report a PR created when only its branch was pushed.
|
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
package mpd
|
||||||
|
|
||||||
|
import "github.com/BeatGlow/beatglow/config"
|
||||||
|
|
||||||
|
// SetAudioSource configures FIFO output monitoring before Events is called.
|
||||||
|
func (p *Player) SetAudioSource(source config.Audio) {
|
||||||
|
p.audioSource = source
|
||||||
|
}
|
||||||
|
|
||||||
|
func (p *Player) checkFIFOOutput(conn *clientConn) {
|
||||||
|
lines, err := p.sendDataCommand(conn, "outputs")
|
||||||
|
if err == nil {
|
||||||
|
err = fifoOutputState(parseOutputs(lines), p.audioSource.Output)
|
||||||
|
}
|
||||||
|
state := "enabled"
|
||||||
|
if err != nil {
|
||||||
|
state = err.Error()
|
||||||
|
}
|
||||||
|
if state == p.fifoState {
|
||||||
|
return
|
||||||
|
}
|
||||||
|
p.fifoState = state
|
||||||
|
log := conn.log().WithField("fifo", p.audioSource.Path).WithField("output", p.audioSource.Output)
|
||||||
|
if err != nil {
|
||||||
|
log.WithError(err).Warn("FIFO audio source may not receive samples")
|
||||||
|
} else {
|
||||||
|
log.Info("MPD FIFO output is enabled")
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,61 @@
|
|||||||
|
package mpd
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
"strings"
|
||||||
|
)
|
||||||
|
|
||||||
|
type output struct {
|
||||||
|
name, plugin string
|
||||||
|
enabled bool
|
||||||
|
}
|
||||||
|
|
||||||
|
func parseOutputs(lines []string) []output {
|
||||||
|
var outputs []output
|
||||||
|
for _, line := range lines {
|
||||||
|
key, value, ok := strings.Cut(line, ": ")
|
||||||
|
if !ok {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
if key == "outputid" {
|
||||||
|
outputs = append(outputs, output{})
|
||||||
|
}
|
||||||
|
if len(outputs) == 0 {
|
||||||
|
continue
|
||||||
|
}
|
||||||
|
o := &outputs[len(outputs)-1]
|
||||||
|
switch key {
|
||||||
|
case "outputname":
|
||||||
|
o.name = value
|
||||||
|
case "plugin":
|
||||||
|
o.plugin = value
|
||||||
|
case "outputenabled":
|
||||||
|
o.enabled = value == "1"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return outputs
|
||||||
|
}
|
||||||
|
|
||||||
|
func fifoOutputState(outputs []output, name string) error {
|
||||||
|
var matches []output
|
||||||
|
for _, o := range outputs {
|
||||||
|
if name != "" {
|
||||||
|
if o.name == name && (o.plugin == "fifo" || o.plugin == "") {
|
||||||
|
matches = append(matches, o)
|
||||||
|
}
|
||||||
|
} else if o.plugin == "fifo" {
|
||||||
|
matches = append(matches, o)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
switch len(matches) {
|
||||||
|
case 0:
|
||||||
|
return fmt.Errorf("no matching MPD FIFO output; check MPD configuration and audio.output")
|
||||||
|
case 1:
|
||||||
|
if !matches[0].enabled {
|
||||||
|
return fmt.Errorf("MPD FIFO output %q is disabled", matches[0].name)
|
||||||
|
}
|
||||||
|
return nil
|
||||||
|
default:
|
||||||
|
return fmt.Errorf("multiple matching MPD FIFO outputs; set audio.output to the output name")
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,33 @@
|
|||||||
|
package mpd
|
||||||
|
|
||||||
|
import (
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestFIFOOutputState(t *testing.T) {
|
||||||
|
for _, tt := range []struct {
|
||||||
|
name, response, output, want string
|
||||||
|
}{
|
||||||
|
{"enabled", "outputid: 0\noutputname: DAC\nplugin: alsa\noutputenabled: 0\noutputid: 1\noutputname: Visualizer\nplugin: fifo\noutputenabled: 1", "", ""},
|
||||||
|
{"disabled", "outputid: 2\noutputname: Visualizer\nplugin: fifo\noutputenabled: 0", "", "disabled"},
|
||||||
|
{"missing", "outputid: 0\noutputname: DAC\nplugin: alsa\noutputenabled: 1", "", "no matching"},
|
||||||
|
{"ambiguous", "outputid: 1\noutputname: One\nplugin: fifo\noutputenabled: 1\noutputid: 2\noutputname: Two\nplugin: fifo\noutputenabled: 0", "", "multiple"},
|
||||||
|
{"select named disabled", "outputid: 1\noutputname: One\nplugin: fifo\noutputenabled: 1\noutputid: 2\noutputname: Two\nplugin: fifo\noutputenabled: 0", "Two", "disabled"},
|
||||||
|
{"legacy named", "outputid: 1\noutputname: Visualizer\noutputenabled: 1", "Visualizer", ""},
|
||||||
|
{"legacy unidentified", "outputid: 1\noutputname: Visualizer\noutputenabled: 1", "", "no matching"},
|
||||||
|
{"wrong plugin", "outputid: 1\noutputname: Visualizer\nplugin: alsa\noutputenabled: 1", "Visualizer", "no matching"},
|
||||||
|
{"empty", "", "", "no matching"},
|
||||||
|
} {
|
||||||
|
t.Run(tt.name, func(t *testing.T) {
|
||||||
|
err := fifoOutputState(parseOutputs(strings.Split(tt.response, "\n")), tt.output)
|
||||||
|
if tt.want == "" {
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
} else if err == nil || !strings.Contains(err.Error(), tt.want) {
|
||||||
|
t.Fatalf("got %v, want error containing %q", err, tt.want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -33,6 +33,8 @@ type Player struct {
|
|||||||
Version Version
|
Version Version
|
||||||
|
|
||||||
name string
|
name string
|
||||||
|
audioSource config.Audio
|
||||||
|
fifoState string
|
||||||
addr string
|
addr string
|
||||||
password string
|
password string
|
||||||
idleSubsystems []string
|
idleSubsystems []string
|
||||||
@@ -226,6 +228,10 @@ func (p *Player) sendDataCommand(conn *clientConn, format string, args ...interf
|
|||||||
if line == "OK" {
|
if line == "OK" {
|
||||||
break
|
break
|
||||||
}
|
}
|
||||||
|
if strings.HasPrefix(line, "ACK ") {
|
||||||
|
err = textproto.ProtocolError(line)
|
||||||
|
break
|
||||||
|
}
|
||||||
|
|
||||||
lines = append(lines, line)
|
lines = append(lines, line)
|
||||||
}
|
}
|
||||||
@@ -443,6 +449,7 @@ func (p *Player) mainLoop(conn *clientConn, events chan player.Event) {
|
|||||||
defer ticker.Stop()
|
defer ticker.Stop()
|
||||||
|
|
||||||
var err error
|
var err error
|
||||||
|
var outputCheck time.Time
|
||||||
loop:
|
loop:
|
||||||
for {
|
for {
|
||||||
select {
|
select {
|
||||||
@@ -469,6 +476,10 @@ loop:
|
|||||||
}
|
}
|
||||||
|
|
||||||
case <-ticker.C:
|
case <-ticker.C:
|
||||||
|
if p.audioSource.Type == "fifo" && time.Since(outputCheck) >= 15*time.Second {
|
||||||
|
outputCheck = time.Now()
|
||||||
|
p.checkFIFOOutput(conn)
|
||||||
|
}
|
||||||
var status map[string]string
|
var status map[string]string
|
||||||
if status, err = p.sendMapCommand(conn, "status"); err != nil {
|
if status, err = p.sendMapCommand(conn, "status"); err != nil {
|
||||||
log.WithError(err).Error("error retrieving status")
|
log.WithError(err).Error("error retrieving status")
|
||||||
|
|||||||
@@ -67,6 +67,8 @@ func (p *Player) Events() (<-chan player.Event, error) {
|
|||||||
return p.mpd.Events()
|
return p.mpd.Events()
|
||||||
}
|
}
|
||||||
|
|
||||||
|
func (p *Player) SetAudioSource(source config.Audio) { p.mpd.SetAudioSource(source) }
|
||||||
|
|
||||||
func (p *Player) AlbumArt(t *player.Track) (image.Image, bool) {
|
func (p *Player) AlbumArt(t *player.Track) (image.Image, bool) {
|
||||||
log := p.log()
|
log := p.log()
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user