feat: add an interactive audio synthesizer

Author: rubiojr

.gitignore

@@ -0,0 +1 @@
+.octmp

README.md

@@ -1,6 +1,6 @@
 ## Pirate Audio Go Module
 
-Go module to control Pimoroni's Pirate Audio LCD and buttons.
+Go module to control Pimoroni's Pirate Audio sound output, LCD, and buttons.
 
 ⚠️   Highly Experimental, API subject to change, may set your device on fire ⚠️ 
 
@@ -24,9 +24,25 @@ ls -l /dev/spidev0.1
 
 If configuring SPI manually, add `dtparam=spi=on` to
 `/boot/firmware/config.txt` on current Raspberry Pi OS releases, or
-`/boot/config.txt` on older releases. See the
+`/boot/config.txt` on older releases.
+
+The DAC is exposed as an ALSA device by the `hifiberry-dac` overlay. Add the
+following lines to the same configuration file and reboot:
+
+```ini
+dtoverlay=hifiberry-dac
+gpio=25=op,dh
+dtparam=audio=off
+```
+
+`dtparam=audio=off` is optional, but prevents the built-in Raspberry Pi audio
+device from being selected as the default output. See the
 [official Pirate Audio repository](https://github.com/pimoroni/pirate-audio)
-for the remaining hardware configuration.
+for more hardware configuration details.
+
+The `audio` package accesses ALSA directly without cgo or development headers.
+It finds the `sndrpihifiberry` card automatically and uses device `0`. To select
+a card number explicitly, clear `audio.Options.CardName` and set `Card`.
 
 The `textview` package loads Roboto Medium or falls back to DejaVu Sans Mono
 and DejaVu Sans. Install the packages that provide those fonts on Raspberry Pi
@@ -39,6 +55,85 @@ sudo apt install fonts-roboto-unhinted fonts-dejavu-core
 
 Alternatively, set `textview.Options.FontPath` to another TrueType font file.
 
+## Audio
+
+The `audio` package plays [`beep.Streamer`](https://pkg.go.dev/github.com/gopxl/beep/v2#Streamer)
+values and provides oscillators, white noise, and ADSR envelopes. Use Beep for
+gain, panning, mixing, sequencing, duration limits, and decoded audio. The
+engine opens the selected ALSA hardware device at 48 kHz, S32_LE stereo. Only
+one engine may be created at a time because direct hardware access is exclusive.
+
+```Go
+package main
+
+import (
+	"log"
+	"time"
+
+	"github.com/gopxl/beep/v2/effects"
+	"github.com/rubiojr/go-pirateaudio/audio"
+)
+
+func main() {
+	engine, err := audio.New()
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer engine.Close()
+
+	tone, err := audio.Saw(engine.SampleRate(), 220)
+	if err != nil {
+		log.Fatal(err)
+	}
+	sound, err := audio.Envelope(
+		&effects.Gain{Streamer: tone, Gain: -0.5},
+		engine.SampleRate(),
+		300*time.Millisecond,
+		audio.ADSR{
+			Attack:  10 * time.Millisecond,
+			Decay:   80 * time.Millisecond,
+			Sustain: 0.5,
+			Release: 200 * time.Millisecond,
+		},
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+	voice, err := engine.Play(sound)
+	if err != nil {
+		log.Fatal(err)
+	}
+	if err := voice.Wait(); err != nil {
+		log.Fatal(err)
+	}
+}
+```
+
+Beep streamers are stateful. Construct a fresh oscillator, envelope, decoder,
+or other stream graph for every call to `Engine.Play`; do not replay the same
+`Streamer` value.
+
+Streaming runs under Beep's mixer lock. A `Streamer` or `beep.Callback` must
+not call `Engine` or `Voice` methods synchronously; hand that work to another
+goroutine instead. Custom `Streamer.Stream` methods must also return promptly
+so they cannot stall the real-time mixer or shutdown.
+
+The default master volume is deliberately limited to 20 percent. Copy and
+modify `audio.DefaultOptions`, then call `audio.Open(options)` to change it. The
+same options expose `CardName`, `Card`, `Device`, and `BufferSize` for ALSA
+configuration. Mixing many simultaneous voices can exceed the normalized range;
+the final PCM output is hard-clipped to protect the DAC from numeric overflow.
+
+Run the four-button synthesizer with:
+
+```shell
+go run ./examples/synth
+```
+
+The display shows a live triangle-wave scope and four color-coded note pads.
+Button callbacks enqueue notes, audio starts independently of display updates,
+and the display redraws only while a note animation is active.
+
 ## ST7789
 
 The driver package for the 240x240px [Pirate Audio display](https://shop.pimoroni.com/products/pirate-audio-headphone-amp).

audio/audio_test.go

@@ -0,0 +1,34 @@
+package audio
+
+import (
+	"testing"
+
+	"github.com/gopxl/beep/v2"
+	"github.com/stretchr/testify/require"
+)
+
+func collectSamples(t *testing.T, stream beep.Streamer, bufferSize int) [][2]float64 {
+	t.Helper()
+	var samples [][2]float64
+	buffer := make([][2]float64, bufferSize)
+	for {
+		n, ok := stream.Stream(buffer)
+		require.GreaterOrEqual(t, n, 0)
+		require.LessOrEqual(t, n, len(buffer))
+		samples = append(samples, buffer[:n]...)
+		if !ok || n < len(buffer) {
+			require.NoError(t, stream.Err())
+			return samples
+		}
+		require.NotZero(t, n, "stream made no progress")
+	}
+}
+
+func constant(sample [2]float64) beep.Streamer {
+	return beep.StreamerFunc(func(samples [][2]float64) (int, bool) {
+		for i := range samples {
+			samples[i] = sample
+		}
+		return len(samples), true
+	})
+}