catglow

README

catglow

ESP32-based music visualizer for WS2812 LED strips.

Working Mechanism

This project uses noriah/catnip to process audio on the system into frequency bins, and then uses those frequency bins to render a visualization to be sent to the ESP32, which acts as a controller for a WS2812 LED strip.

Diagram

┌───────────────────────────────────────────────────────────────────┐
│                                                                   │
│   Linux Machine                                                   │
│                      ┌──────────────────────┐                     │
│                      │                      │                     │   ┌─────────────┐
│                      │  ┌────────────────┐  │  ┌──────────────┐   │   │             │
│                      │  │                │  │  │              │   │   │             │
│                      │  │  LED Renderer  ├──┼──► /dev/ttyUSB0 ├───┼───►    ESP32    │
│                      │  │                │  │  │              │   │   │             │
│                      │  └───────▲────────┘  │  └──────────────┘   │   │ <ledserial> │
│   ┌───────────────┐  │          │           │                     │   │             │
│   │ Audio Players │  │  ┌───────┴────────┐  │                     │   │             │
│   │               │  │  │                │  │                     │   └──────┬──────┘
│   │ Spotify       ├──┼──►     catnip     │  │                     │          │
│   │ Firefox       │  │  │                │  │                     │          │
│   │ Mixxx         │  │  └────────────────┘  │                     │   ┌──────▼───────
│   │ ...           │  │                      │                     │   │
│   └───────────────┘  └──────────────────────┘                     │   │    LEDs...
│                                                                   │   │
└───────────────────────────────────────────────────────────────────┘   └──────────────

Build

go build

Usage

./catglow -c catglow.toml # run with a config file

Configuration

[[led]]
  range = [40, 192]

  [led.visualizer]
   kind = "glowing" # see #Visualizers
   flip = true # flip the LED strip
   bins = -1 # use as many bins as there are LEDs, otherwise bins are sectioned
   backend = "pipewire"
   device = "spotify"
   smooth = 0.5

   gradients = [
     [255, 0, 0],
     [0, 255, 0],
     [0, 0, 255],
   ]
   gradient_mode = "peak"      # "peak" or "duration" or "static"
   gradient_peak_switch = 0.85 # switch to the next gradient when the peak is above 85%
   gradient_peak_bin = 0       # use the first frequency bin for the peak
   gradient_duration = "1s"    # used if gradient_mode is "duration"

[[led]]
  range = [0, 40]
  color = [255, 255, 255] # static color

Visualizers

• glowing: glow each LED based on the frequency bin.
• blinking: blink the entire LED strip based on the normalized amplitude.
• meter: show a horizontal meter based on the normalized amplitude.

Documentation

Index

• type Animator
• type Config
  • func ParseConfig(r io.Reader) (*Config, error)
  • func (c *Config) NumLEDs() int
  • func (c *Config) Validate() error
• type Daemon
  • func NewDaemon(cfg *Config, logger *slog.Logger) (*Daemon, error)
  • func (d *Daemon) QueueRefresh()
  • func (d *Daemon) Run(ctx context.Context) error
• type GradientMode
• type LEDConfig
• type RefreshQueuer
• type SnakeAnimationChunk
• type SnakeAnimationConfig
• type TOMLDuration
  • func (d TOMLDuration) MarshalText() ([]byte, error)
  • func (d *TOMLDuration) UnmarshalText(text []byte) error
• type VisualizerConfig
• type VisualizerKind

Types

type Animator

type Animator interface {
	// AcquireFrame acquires a frame from the animator. The frame is passed to
	// the callback function. The callback function must not be called after
	// AcquireFrame returns.
	// Usually, the daemon will call this method when QueueRefresh is called.
	AcquireFrame(f func(led.LEDs))
}

Animator is the interface for types that can animate the LEDs. It is kept to a minimum.

type Config

type Config struct {
	// Device is the path to the device file for catglow.
	// This is usually /dev/ttyUSB0 or /dev/ttyACM0.
	Device string `toml:"device"`
	// Baud is the baud rate for the serial connection.
	Baud int `toml:"baud"`
	// Rate is the refresh rate for the LEDs.
	Rate int `toml:"rate"`
	// LEDs is a list of LED configurations.
	LEDs []LEDConfig `toml:"led"`
}

Config is the configuration for the Catglow server.

func ParseConfig

func ParseConfig(r io.Reader) (*Config, error)

ParseConfig parses a configuration from a reader.

func (*Config) NumLEDs

func (c *Config) NumLEDs() int

NumLEDs returns the number of LEDs configured.

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the configuration.

type Daemon

type Daemon struct {
	// contains filtered or unexported fields
}

Daemon is the main catglow daemon.

func NewDaemon

func NewDaemon(cfg *Config, logger *slog.Logger) (*Daemon, error)

NewDaemon creates a new catglow daemon.

func (*Daemon) QueueRefresh

func (d *Daemon) QueueRefresh()

QueueRefresh queues a refresh of the led.LEDs. This method is mainly used internally.

func (*Daemon) Run

func (d *Daemon) Run(ctx context.Context) error

Run starts the daemon. It blocks until the given context is canceled.

type GradientMode

type GradientMode string

GradientMode is the mode for the gradient.

const (
	// PeakGradientMode means the gradient is changed based on the peak bin.
	PeakGradientMode GradientMode = "peak"
	// DurationGradientMode means the gradient is changed based on the duration.
	DurationGradientMode GradientMode = "duration"
	// StaticGradientMode means to only use the first color in the gradient.
	StaticGradientMode GradientMode = "static"
)

type LEDConfig

type LEDConfig struct {
	// Range is the range of LEDs to configure.
	Range [2]int `toml:"range"`

	// Color is the color to set the LEDs to.
	Color *led.RGBColor `toml:"color,omitempty"`
	// Snake is the configuration for the snake animation.
	Snake *SnakeAnimationConfig `toml:"snake,omitempty"`
	// Visualizer is the configuration for the visualizer.
	Visualizer *VisualizerConfig `toml:"visualizer,omitempty"`
}

LEDConfig is the configuration for a range of LEDs.

type RefreshQueuer

type RefreshQueuer interface {
	// QueueRefresh queues a refresh of the LEDs.
	// The daemon may choose to ignore this request if it is already refreshing
	// the LEDs.
	QueueRefresh()
}

RefreshQueuer is the interface for types that can queue a refresh of the LEDs. LED animations use this interface to queue a refresh when they are done.

type SnakeAnimationChunk

type SnakeAnimationChunk struct {
	// Color is the color for the chunk.
	Color led.RGBColor `toml:"color"`
}

SnakeAnimationChunk is a chunk for the snake animation.

type SnakeAnimationConfig

type SnakeAnimationConfig struct {
	// Chunks is the list of chunks for the snake animation.
	Chunks []SnakeAnimationChunk `toml:"chunk"`
	// Speed is the speed of the snake animation.
	Speed TOMLDuration `toml:"speed"`
}

SnakeAnimationConfig is the configuration for the snake animation.

type TOMLDuration

type TOMLDuration time.Duration

TOMLDuration is a duration that can be parsed from TOML.

func (TOMLDuration) MarshalText

func (d TOMLDuration) MarshalText() ([]byte, error)

func (*TOMLDuration) UnmarshalText

func (d *TOMLDuration) UnmarshalText(text []byte) error

type VisualizerConfig

type VisualizerConfig struct {
	Kind    VisualizerKind `toml:"kind"`
	Flip    bool           `toml:"flip"`
	Bins    int            `toml:"bins"`
	Backend string         `toml:"backend"`
	Device  string         `toml:"device"`
	Smooth  float64        `toml:"smooth"`

	Gradients          []led.RGBColor `toml:"gradients"`
	GradientMode       GradientMode   `toml:"gradient_mode"`
	GradientPeakSwitch float64        `toml:"gradient_peak_switch"`
	GradientPeakBin    int            `toml:"gradient_peak_bin"`
	GradientDuration   TOMLDuration   `toml:"gradient_duration"`
}

VisualizerConfig is the configuration for the visualizer.

type VisualizerKind

type VisualizerKind string

VisualizerKind is the kind of visualizer to use.

const (
	// GlowingVisualizer means glow each LED based on its frequency bin.
	GlowingVisualizer VisualizerKind = "glowing"
	// BlinkingVisualizer means glowing the entire strip based on the normalized
	// amplitude.
	BlinkingVisualizer VisualizerKind = "blinking"
	// MeterVisualizer shows a horizontal meter based on the normalized
	// amplitude.
	MeterVisualizer VisualizerKind = "meter"
)