Audio

https://github.com/xaionaro-go/audio
Admin
Audio is a Go collection of packages for handling audio inputs, outputs, and processing with support...
Tokens:46,655
Snippets:498
Trust Score:8.2
License:CC0-1.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Dummy Noise Suppression Example

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppression.md

Demonstrates how to initialize and use the dummy noise suppression. The example shows setting up encoding, creating a dummy instance, and then using it similarly to a regular noise suppression implementation. Remember to close the dummy instance when done.

```go
import (
    "github.com/xaionaro-go/audio/pkg/noisesuppression"
)

encoding := audio.EncodingPCM{
    PCMFormat:  audio.PCMFormatFloat32LE,
    SampleRate: 48000,
}

dummy := noisesuppression.NewDummy(encoding, 1)
deffer dummy.Close()

// Use like normal NoiseSuppression
confidence, err := dummy.SuppressNoise(ctx, input, output)
// Returns 1.0 (full confidence), input == output
```

--------------------------------

### RecordStream Usage Example

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/types.md

Shows how to initiate PCM audio recording and record for a specified duration.

```go
stream, err := recorder.RecordPCM(ctx, sr, ch, fmt, writer)
deferr stream.Close()

time.Sleep(5 * time.Second)  // Record for 5 seconds
```

--------------------------------

### PlayStream Usage Example

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/types.md

Demonstrates how to play PCM audio and wait for the playback to complete using the Drain method.

```go
stream, err := player.PlayPCM(ctx, sr, ch, fmt, bufSize, reader)
defer stream.Close()

// Wait for playback to complete
if err := stream.Drain(); err != nil {
    log.Fatal(err)
}
```

--------------------------------

### CalculateShiftBetween Method Example

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/syncer.md

Demonstrates how to use the `CalculateShiftBetween` method to align multiple comparison audio tracks to a reference track. Ensure to handle potential errors and close the syncer when done.

```go
import (
    "context"
    "github.com/xaionaro-go/audio/pkg/syncer"
)

syncer, err := createSyncerImplementation()
if err != nil {
    log.Fatal(err)
}
def syncer.Close()

// Align two comparison tracks to reference
results, err := syncer.CalculateShiftBetween(
    context.Background(),
    referenceAudio,
    comparisonTrack1,
    comparisonTrack2,
)
if err != nil {
    log.Fatal(err)
}

for i, result := range results {
    fmt.Printf("Track %d: shift=%f samples, confidence=%f\n",
        i+1, result.Shift, result.Confidence)
}
```

--------------------------------

### Backend-Specific Error Examples

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

Demonstrates how backend-specific errors are wrapped while preserving the underlying error type. These examples show errors from PortAudio and PulseAudio.

```go
// PortAudio error
"unable to initialize a resampler: portaudio error"
```

```go
// PulseAudio error
"unable to initialize a client to Pulse: connection refused"
```

--------------------------------

### Example: Using RNNoise Suppression

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppression.md

Demonstrates how to initialize RNNoise noise suppression, process an audio chunk, and retrieve voice confidence. Ensure input and output buffers match the chunk size.

```go
import (
    "github.com/xaionaro-go/audio/pkg/noisesuppression/implementations/rnnoise"
)

ns, err := rnnoise.NewNoiseSuppression()
if err != nil {
    log.Fatal(err)
}
deferr ns.Close()

chunkSize := ns.ChunkSize()
input := make([]byte, chunkSize)
output := make([]byte, chunkSize)

// Fill input with audio data...

confidence, err := ns.SuppressNoise(context.Background(), input, output)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Voice confidence: %f\n", confidence)
```

--------------------------------

### Example Buffer Sizing for Noise Suppression Stream

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppressionstream.md

Demonstrates calculating appropriate input and output buffer sizes for the noise suppression stream, considering RNNoise chunk size and desired buffering.

```go
// For 48kHz stereo float32 RNNoise
// Chunk size: 480 * 2 channels * 4 bytes = 3840 bytes
inputSize := 8 * 3840    // 8 chunks buffered
outputSize := 2 * 3840   // 2 chunks buffered

stream, _ := noisesuppressionstream.NewNoiseSuppressionStream(
    ctx, input, ns,
    uint(inputSize), uint(outputSize),
)
```

--------------------------------

### Error Wrapping Example

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

Illustrates the common pattern of wrapping errors with additional context. This format helps in debugging by showing the operation that failed and the underlying cause.

```go
"unable to initialize a vorbis reader: unexpected end of file"
```

--------------------------------

### Get Configured Encoding

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppression.md

Returns the audio encoding that was configured when the dummy noise suppression instance was created. It always returns a nil error.

```go
func (s *Dummy) Encoding(context.Context) (audio.Encoding, error)
```

--------------------------------

### Auto-Select Audio Backend

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Use `NewPlayerAuto` to automatically select an available audio backend. The library tries backends in a predefined order, typically starting with higher-priority ones like PulseAudio.

```go
import _ "github.com/xaionaro-go/audio/pkg/audio/backends/oto"
import _ "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
import _ "github.com/xaionaro-go/audio/pkg/audio/backends/pulseaudio"

// Will try in order: PulseAudio, PortAudio, Oto
player := audio.NewPlayerAuto(ctx)
```

--------------------------------

### Get Configured Channels

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppression.md

Returns the number of audio channels that was configured when the dummy noise suppression instance was created. It always returns a nil error.

```go
func (s *Dummy) Channels(context.Context) (audio.Channel, error)
```

--------------------------------

### Fallback Audio Backend Chain

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Implement a fallback mechanism to use alternative backends if the preferred one fails. This example attempts to use PortAudio and falls back to Oto if PortAudio is unavailable.

```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
    "github.com/xaionaro-go/audio/pkg/audio/backends/oto"
)

var backend audio.PlayerPCM

ba, err := portaudio.NewPlayerPCM()
if err == nil {
    backend = ba
} else {
    backend, _ = oto.NewPlayerPCM()  // Fallback
}

player := audio.NewPlayer(backend)
```

--------------------------------

### Wrap Reader for Noise Suppression

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppression.md

This example shows how to wrap an existing reader to automatically suppress noise using NoiseSuppressionStream. It initializes the stream with input reader, noise suppression instance, and buffer sizes. Subsequent reads from the stream will return noise-suppressed audio data.

```go
import (
    "github.com/xaionaro-go/audio/pkg/noisesuppressionstream"
)

// Wrap reader to automatically suppress noise
nsStream, err := noisesuppressionstream.NewNoiseSuppressionStream(
    context.Background(),
    inputReader,
    noiseSuppression,
    8192,    // input buffer
    8192,    // output buffer
)
if err != nil {
    log.Fatal(err)
}
defer nsStream.Close()

// Read from nsStream gets noise-suppressed audio
data := make([]byte, 1024)
n, err := nsStream.Read(data)
```

--------------------------------

### Record PCM Audio with PortAudio

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Records audio data using the PortAudio backend and writes it to a provided io.Writer. Supports the same LE PCM formats as PlayPCM. Starts recording immediately and writes data asynchronously. The recording duration is controlled externally, for example, by a time.Sleep.

```go
stream, err := backend.RecordPCM(
    ctx,
    48000,
    2,
    audio.PCMFormatFloat32LE,
    outputFile,
)
defere stream.Close()

time.Sleep(5 * time.Second)  // Record for 5 seconds
```

--------------------------------

### Retry with Different Backends

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

Illustrates how to attempt initialization with a list of specific audio backends if the automatic backend selection fails. This allows for graceful fallback to known working backends.

```go
// Use specific backend if auto-selection fails
backends := []func() (audio.PlayerPCM, error){
    oto.NewPlayerPCM,
    portaudio.NewPlayerPCM,
    pulseaudio.NewPlayerPCM,
}

for _, factory := range backends {
    backend, err := factory()
    if err == nil {
        player := audio.NewPlayer(backend)
        return player
    }
}
```

--------------------------------

### Basic Audio Playback in Go

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/README.md

Demonstrates how to initialize a player and play an audio file. Ensure the audio file exists and the context is valid.

```go
player := audio.NewPlayerAuto(ctx)
file, _ := os.Open("audio.ogg")
stream, _ := player.PlayVorbis(ctx, file)
stream.Drain()
```

--------------------------------

### Get VAD Encoding (No Error)

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/vad.md

A convenience method to get the audio encoding without an error return value.

```go
func (v *VAD) EncodingNoErr() audio.EncodingPCM
```

--------------------------------

### Accessing and Using Registered Backends

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Demonstrates how to retrieve all registered audio backend factories, sorted by priority, and iterate through them to find a suitable backend for playback. The first backend that initializes without error is used.

```go
import "github.com/xaionaro-go/audio/pkg/audio/registry"

// Get all factories sorted by priority
factories := registry.PlayerFactories()

// Try each in order
for _, factory := range factories {
    player, err := factory.NewPlayerPCM()
    if err == nil {
        // Use this backend
    }
}
```

--------------------------------

### EncodingPCM: BytesForSecond Example

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/types.md

Calculates bytes per second for a given PCM encoding. This example uses S16LE format at 48000 Hz.

```go
enc := audio.EncodingPCM{
    PCMFormat:  audio.PCMFormatS16LE,
    SampleRate: 48000,
}
// BytesForSecond() = 2 * 48000 = 96,000 bytes/sec
```

--------------------------------

### Basic Audio Playback

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/INDEX.md

Demonstrates how to initialize an audio player, play a Vorbis file, and ensure playback completion. Requires importing the 'oto' backend.

```go
import "github.com/xaionaro-go/audio/pkg/audio"
import _ "github.com/xaionaro-go/audio/pkg/audio/backends/oto"

player := audio.NewPlayerAuto(ctx)
defer player.Close()

file, _ := os.Open("audio.ogg")
stream, _ := player.PlayVorbis(ctx, file)
stream.Drain()
```

--------------------------------

### Get VAD Channels (No Error)

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/vad.md

A convenience method to get the channel count without an error return value. This always returns 1 for mono.

```go
func (v *VAD) ChannelsNoErr() audio.Channel
```

--------------------------------

### EncodingPCM: BytesForDuration Example

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/types.md

Calculates the number of bytes required for a specific duration using PCM encoding. This example uses Float32LE format at 48000 Hz for one second.

```go
enc := audio.EncodingPCM{
    PCMFormat:  audio.PCMFormatFloat32LE,
    SampleRate: 48000,
}
// BytesForDuration(1*time.Second) = 48000 * 4 = 192,000
```

--------------------------------

### Get Audio Encoding

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppressionstream.md

Retrieves the audio encoding used by the noise suppression backend.

```APIDOC
## Get Audio Encoding

### Description
Returns the audio encoding from the noise suppression backend.

### Method
`Encoding(ctx context.Context) (audio.Encoding, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (audio.Encoding)
- **encoding**: The audio encoding required by the noise suppression engine.

#### Error Response
- **error**: An error encountered while retrieving the encoding.

### Example
```go
ctx := context.Background()
encoding, err := stream.Encoding(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Audio Encoding: %s\n", encoding)
```
```

--------------------------------

### Fallback to Dummy Backend

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

Demonstrates how to use `audio.NewPlayerAuto` which falls back to a dummy backend if all other backends fail. This ensures silent success in case of critical errors.

```go
player := audio.NewPlayerAuto(ctx)
// If all backends fail, player uses dummy (silent success)
// Check with test playback
```

--------------------------------

### Audio Format Conversion Pipeline in Go

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/README.md

Illustrates setting up a pipeline for audio processing, including resampling and noise suppression before playback. Requires specifying input and output formats, and noise suppression parameters.

```go
// Read → Resample → Denoise → Play
resampler, _ := resampler.NewResampler(inFmt, file, outFmt)
stream, _ := noisesuppressionstream.NewNoiseSuppressionStream(ctx, resampler, ns, 8192, 8192)
playStream, _ := player.PlayPCM(ctx, sr, ch, fmt, bufSize, stream)
```

--------------------------------

### Get Channel Count

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppressionstream.md

Retrieves the number of audio channels processed by the noise suppression backend.

```APIDOC
## Get Channel Count

### Description
Returns the channel count from the noise suppression backend.

### Method
`Channels(ctx context.Context) (audio.Channel, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (audio.Channel)
- **channels**: The number of channels processed by the engine.

#### Error Response
- **error**: An error encountered while retrieving the channel count.

### Example
```go
ctx := context.Background()
channels, err := stream.Channels(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Number of Channels: %d\n", channels)
```
```

--------------------------------

### Basic PCM Audio Recording

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/INDEX.md

Shows how to set up an audio recorder, specify recording parameters (sample rate, channels, format), and save the output to a PCM file. Requires importing the 'portaudio' backend.

```go
import _ "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"

recorder := audio.NewRecorderAuto(ctx)
defer recorder.Close()

output, _ := os.Create("recording.pcm")
stream, _ := recorder.RecordPCM(ctx, 48000, 2, audio.PCMFormatFloat32LE, output)
time.Sleep(5 * time.Second)
stream.Close()
```

--------------------------------

### NoiseSuppression Interface

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppression.md

Base interface for noise suppression implementations, including methods for getting chunk size and suppressing noise.

```APIDOC
## NoiseSuppression Interface

### Description
Base interface for noise suppression implementations.

### Methods

#### ChunkSize

##### Description
Returns the required chunk size for processing.

##### Method
`ChunkSize()`

##### Returns
- `uint` — Size in bytes for each audio chunk processed.

#### SuppressNoise

##### Description
Processes an audio chunk to suppress noise and returns the voice confidence.

##### Method
`SuppressNoise(ctx context.Context, input []byte, outputVoice []byte) (float64, error)`

##### Parameters
- **ctx** (`context.Context`) - Context for cancellation
- **input** (`[]byte`) - Input audio chunk (must be exactly ChunkSize bytes)
- **outputVoice** (`[]byte`) - Output buffer for denoised audio (must be exactly ChunkSize bytes)

##### Returns
- `float64` — Voice probability/confidence (0.0 = no voice, 1.0 = voice detected)
- `error` — Error if processing fails

##### Example
```go
import (
    "context"
    "fmt"
    "log"

    "github.com/xaionaro-go/audio/pkg/noisesuppression/implementations/rnnoise"
)

func main() {
    ns, err := rnnoise.NewNoiseSuppression()
    if err != nil {
        log.Fatal(err)
    }
    defer ns.Close()

    chunkSize := ns.ChunkSize()
    input := make([]byte, chunkSize)
    output := make([]byte, chunkSize)

    // Fill input with audio data...

    confidence, err := ns.SuppressNoise(context.Background(), input, output)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Voice confidence: %f\n", confidence)
}
```
```

--------------------------------

### Create Recorder with Automatic Backend Selection

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/recorder.md

Use `NewRecorderAuto` to let the library automatically select the best available audio backend. It prioritizes PulseAudio and PortAudio, caches successful initializations, and falls back to a dummy backend if necessary. Pass a `context.Context` for cancellation and logging.

```Go
import (
    "context"
    "io"
    "github.com/xaionaro-go/audio/pkg/audio"
    _ "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
    _ "github.com/xaionaro-go/audio/pkg/audio/backends/pulseaudio"
)

ctx := context.Background()
recorder := audio.NewRecorderAuto(ctx)
defer recorder.Close()

// Ready to record audio
```

--------------------------------

### Registering a Custom Audio Backend

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Implement the `types.PlayerPCM` or `types.RecorderPCM` interface and create an `init()` function to register your custom backend with the registry. Ensure the backend package is imported to enable discovery.

```go
package mybackend

import (
    "github.com/xaionaro-go/audio/pkg/audio/registry"
    "github.com/xaionaro-go/audio/pkg/audio/types"
)

func init() {
    registry.RegisterPlayerFactory(50, MyPlayerFactory{})
}

type MyPlayerFactory struct{}

func (MyPlayerFactory) NewPlayerPCM() (types.PlayerPCM, error) {
    return NewPlayerPCM()
}
```

--------------------------------

### Get VAD Encoding

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/vad.md

Retrieves the required audio encoding for the VAD instance. For libfvad, this is always PCMFormatS16LE with the configured sample rate.

```go
encoding, _ := vad.Encoding(context.Background())
// encoding.PCMFormat == audio.PCMFormatS16LE
// encoding.SampleRate == 16000 (or configured rate)
```

--------------------------------

### Stream audio conversion using Resampler.Read

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/resampler.md

Demonstrates how to stream audio data through a resampler, converting it to a target format. Ensure the resampler is initialized with appropriate input and output formats and an input reader. Handle EOF and other errors during the reading process.

```go
resampler, err := resampler.NewResampler(inFormat, sourceReader, outFormat)
if err != nil {
    log.Fatal(err)
}

// Stream conversion
buffer := make([]byte, 4096)
for {
    n, err := resampler.Read(buffer)
    if err == io.EOF {
        break
    }
    if err != nil {
        log.Fatal(err)
    }
    
    // Write converted data
    outputWriter.Write(buffer[:n])
}
```

--------------------------------

### Get Audio Encoding

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppressionstream.md

Retrieves the audio encoding format used by the noise suppression backend. This is useful for understanding the format of the processed audio.

```go
func (s *NoiseSuppressionStream) Encoding(ctx context.Context) (audio.Encoding, error)
```

--------------------------------

### Create Player with Auto-Detected Backend

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/player.md

This constructor automatically selects the best available audio backend based on a priority list (PulseAudio > PortAudio > Oto). It caches the last successful factory and falls back to a dummy backend if no others are available. This is useful for applications that need to work across different systems without manual backend configuration.

```go
import (
    "context"
    "github.com/xaionaro-go/audio/pkg/audio"
    _ "github.com/xaionaro-go/audio/pkg/audio/backends/oto"
    _ "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
)

ctx := context.Background()
player := audio.NewPlayerAuto(ctx)
deferr player.Close()

// Ready to play audio
```

--------------------------------

### Create Player with Specific Backend

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/player.md

Use this to create a new Player instance when you need to explicitly control the audio backend implementation. Ensure the backend is properly initialized before passing it to NewPlayer.

```go
import (
    "github.com/xaionaro-go/audio/pkg/audio"
    "github.com/xaionaro-go/audio/pkg/audio/backends/oto"
)

// Create with specific backend
backend, err := oto.NewPlayerPCM()
if err != nil {
    log.Fatal(err)
}
player := audio.NewPlayer(backend)
deferr player.Close()
```

--------------------------------

### Get VAD Channels

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/vad.md

Returns the number of audio channels required by the VAD. libfvad only supports mono audio, so this will always return 1.

```go
channels, _ := vad.Channels(context.Background())
// channels == 1
```

--------------------------------

### Handle Backend Initialization Failure with NewPlayerAuto

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

When NewPlayerAuto fails to initialize any audio backend, it returns a dummy player. Check if the player is a dummy or use an explicit backend to avoid silent discards.

```go
player := audio.NewPlayerAuto(ctx)
// If all backends fail:
// - player is of type Player with PlayerPCMDummy backend
// - PlayPCM() returns immediately with no error
// - No audio is actually played
```

--------------------------------

### Backend Initialization Error Recovery

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Demonstrates a fallback mechanism for initializing audio backends. If the preferred backend (e.g., PortAudio) fails to initialize, the code attempts to use an alternative (e.g., Oto). If both fail, a dummy player is used.

```go
backend, err := portaudio.NewPlayerPCM()
if err != nil {
    // Try fallback
    backend, err := oto.NewPlayerPCM()
    if err != nil {
        // Use dummy
        player := audio.NewPlayer(&audio.PlayerPCMDummy{})
    }
}
```

--------------------------------

### Get Audio Channels

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppressionstream.md

Retrieves the number of audio channels processed by the noise suppression backend. This indicates whether the audio is mono or stereo, etc.

```go
func (s *NoiseSuppressionStream) Channels(ctx context.Context) (audio.Channel, error)
```

--------------------------------

### Create PulseAudio Player

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Initializes a new PulseAudio player. Fails if the PulseAudio daemon is not running.

```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/backends/pulseaudio"
)

backend, err := pulseaudio.NewPlayerPCM()
if err != nil {
    log.Fatal(err)
}
defer backend.Close()
```

--------------------------------

### Stereo to Mono Channel Conversion

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/resampler.md

Example of creating a resampler to convert stereo audio to mono. Ensure the input and output formats are correctly defined.

```go
format := resampler.Format{
    Channels:   2,
    SampleRate: 44100,
    PCMFormat:  audio.PCMFormatS16LE,
}

monoFormat := resampler.Format{
    Channels:   1,
    SampleRate: 44100,
    PCMFormat:  audio.PCMFormatS16LE,
}

r, err := resampler.NewResampler(format, stereReader, monoFormat)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Explicitly Select PulseAudio Backend

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Instantiate a specific backend, such as PulseAudio, directly. This method requires handling potential errors during backend initialization.

```go
import "github.com/xaionaro-go/audio/pkg/audio/backends/pulseaudio"

backend, err := pulseaudio.NewPlayerPCM()
if err != nil {
    log.Fatal(err)
}
player := audio.NewPlayer(backend)
```

--------------------------------

### Get Chunk Size for Noise Suppression

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/noisesuppression.md

Returns the required chunk size in bytes for processing audio. Input and output buffers must match this size.

```go
func ChunkSize() uint
```

--------------------------------

### Create PortAudio Recorder

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Initializes a PortAudio recorder. This function is responsible for setting up the recorder instance.

```go
backend, err := portaudio.NewRecorderPCM()
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Create PortAudio Player

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Initializes a PortAudio player. Calls portaudio.Initialize() if it hasn't been called yet. Handles potential PortAudio initialization errors.

```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
)

backend, err := portaudio.NewPlayerPCM()
if err != nil {
    log.Fatal(err)
}
defer backend.Close()
```

--------------------------------

### Handle Context Cancellation During Recording

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

When recording, if the context passed to `RecordPCM` is cancelled, the recording stops and the stream is closed with a `context.Canceled` error. This example shows how to trigger cancellation.

```go
ctx, cancel := context.WithCancel(context.Background())
stream, err := recorder.RecordPCM(ctx, sr, ch, fmt, writer)

time.Sleep(1 * time.Second)
cancel()  // Stops recording

// Next close will succeed, context error is logged internally
stream.Close()
```

--------------------------------

### Create Recorder with Specific Backend

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/recorder.md

Use `NewRecorder` to create a recorder instance when you need to explicitly specify the PCM backend implementation. Ensure the backend is properly initialized before passing it.

```Go
import (
    "github.com/xaionaro-go/audio/pkg/audio"
    "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
)

backend, err := portaudio.NewRecorderPCM()
if err != nil {
    log.Fatal(err)
}
recorder := audio.NewRecorder(backend)
defer recorder.Close()
```

--------------------------------

### EncodingPCM Example: BytesPerSample Calculation

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/types.md

Demonstrates calculating bytes per sample for a Stereo S16LE encoding. Note that BytesPerSample() returns bytes per sample, not accounting for channels.

```go
// Stereo S16LE: 2 bytes per sample × 2 channels = 4 bytes
encoding := audio.EncodingPCM{
    PCMFormat:  audio.PCMFormatS16LE,
    SampleRate: 48000,
}
// BytesPerSample() = 2 (per sample, not accounting for channels)
```

--------------------------------

### Project File Structure

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/MANIFEST.md

This is the directory structure for the audio project. The README.md serves as the entry point, followed by an INDEX.md for master indexing and quick reference. API-specific documentation is organized under the api-reference directory.

```bash
/workspace/home/output/
├── README.md                           # Start here
├── INDEX.md                            # Master index & quick ref
├── types.md                            # Type definitions
├── errors.md                           # Error conditions
└── api-reference/
    ├── player.md                       # Player API
    ├── recorder.md                     # Recorder API
    ├── resampler.md                    # Format conversion
    ├── planar.md                       # Layout conversion
    ├── vad.md                          # Voice detection
    ├── noisesuppression.md             # Noise suppression
    ├── noisesuppressionstream.md       # Streaming denoise
    ├── syncer.md                       # Audio sync
    └── backends.md                     # Backend impls

```

--------------------------------

### Handle Unsupported Channel Conversion in Resampler

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

The `NewResampler` function returns an error if the channel count conversion is not supported. This example demonstrates an unsupported conversion from 3 to 5 channels.

```go
// 3 channels → 5 channels (unsupported)
_, err := resampler.NewResampler(
    Format{Channels: 3, ...},
    reader,
    Format{Channels: 5, ...},
)
// Error: "do not know how to convert 3 channels to 5"
```

--------------------------------

### Multi-track Recording and Sync Detection in Go

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/INDEX.md

Shows how to record multiple audio channels and then align them using a syncer. The results can be used to adjust playback timing or rewrite files with applied shifts. Requires appropriate encoding and channel configuration.

```go
// Record multiple channels, then align them

import (
    "github.com/xaionaro-go/audio/pkg/syncer/gccphat"
    "context"
)

var ctx context.Context
var encoding string
var channels int
// var ch1, ch2, ch3 someAudioStreamType // Placeholder for recorded channels

// Record multiple tracks...
// ch1, ch2, ch3 := recordChannels()

// Align all to ch1
syncer, _ := gccphat.NewSyncer(encoding, channels)
results, _ := syncer.CalculateShiftBetween(ctx, nil, nil, nil) // Placeholder for actual channels

for i, shift := range results {
    // Adjust playback timing or rewrite file with shift applied
}
```

--------------------------------

### Complete Audio Processing Pipeline in Go

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/INDEX.md

Demonstrates a full audio processing pipeline: reading from a file, resampling from 44.1kHz to 48kHz, suppressing noise using RNNoise, and playing the processed audio. Ensure necessary imports and context are available.

```go
// Read → Resample → Denoise → Play

import (
    "github.com/xaionaro-go/audio/pkg/audio"
    "github.com/xaionaro-go/audio/pkg/audio/resampler"
    "github.com/xaionaro-go/audio/pkg/noisesuppressionstream"
    "github.com/xaionaro-go/audio/pkg/rnnoise"
    "context"
    "os"
    "time"
)

var ctx context.Context

file, _ := os.Open("input.pcm")

// Resample 44.1kHz to 48kHz
resamp, _ := resampler.NewResampler(
    resampler.Format{Channels: 2, SampleRate: 44100, PCMFormat: audio.PCMFormatF32LE},
    file,
    resampler.Format{Channels: 2, SampleRate: 48000, PCMFormat: audio.PCMFormatF32LE},
)

// Suppress noise
ns, _ := rnnoise.NewNoiseSuppression()
denoiser, _ := noisesuppressionstream.NewNoiseSuppressionStream(ctx, resamp, ns, 8192, 8192)

// Play
player := audio.NewPlayerAuto(ctx)
stream, _ := player.PlayPCM(ctx, 48000, 2, audio.PCMFormatF32LE, 100*time.Millisecond, denoiser)
stream.Drain()
```

--------------------------------

### Registering a New Backend Factory

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Shows the standard procedure for registering a new audio backend factory with the registry system. This typically involves implementing the `PlayerPCMFactory` interface and calling `registry.RegisterPlayerFactory` within the backend's `init` function.

```go
// In backend's init.go
func init() {
    registry.RegisterPlayerFactory(Priority, PlayerPCMFactory{})
}

type PlayerPCMFactory struct {}

func (PlayerPCMFactory) NewPlayerPCM() (types.PlayerPCM, error) {
    return NewPlayerPCM()
}
```

--------------------------------

### Automatic Format Resampling

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

When the requested audio format differs from the backend's capabilities, the player automatically resamples the audio stream. This example shows a scenario where the application requests 48000Hz S16LE, but the Oto backend expects 44100Hz F32LE.

```go
// Example: Oto expects 44100Hz F32LE, but app requests 48000Hz S16LE
stream, err := player.PlayPCM(ctx, 48000, 2, audio.PCMFormatS16LE, bufSize, reader)
// Internally uses Resampler to convert formats
```

--------------------------------

### Integrate Syncer with Planar Conversion

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/syncer.md

Convert audio format for the sync engine by using a planar conversion reader. Initialize the unplanarize reader with the appropriate format and input source.

```go
// Convert format for sync engine
planar, _ := planar.NewUnplanarizeReader(...)
syncer.CalculateShiftBetween(ctx, ref, planar)
```

--------------------------------

### NewPlayerPCM

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Creates a PortAudio player. Initialization calls portaudio.Initialize() if not already done.

```APIDOC
## NewPlayerPCM

### Description
Creates a PortAudio player.

### Method
`func NewPlayerPCM() (*PlayerPCM, error)`

### Returns
`(*PlayerPCM, error)` - Player or error if PortAudio initialization fails.

### Example
```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
)

backend, err := portaudio.NewPlayerPCM()
if err != nil {
    log.Fatal(err)
}
defer backend.Close()
```
```

--------------------------------

### Handle Invalid Input Size in Resampler Read

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

The `Read` function in the resampler returns an error if the input data size is not a multiple of (sample size × channels). This example shows a scenario where 5 bytes are read but a multiple of 4 was expected.

```go
// If reader returns 5 bytes but needs multiple of 4 (2 channels × 2 bytes)
n, err := resampler.Read(buffer)
// Error: "read a number of bytes (5) that is not a multiple of 4"
```

--------------------------------

### NewRecorderAuto

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/recorder.md

Automatically selects and initializes the best available audio backend for recording.

```APIDOC
## NewRecorderAuto

### Description
Automatically selects and initializes the best available audio backend for recording. Tries backends in priority order (PulseAudio > PortAudio), caches the last successful factory, and falls back to a dummy backend if none are available.

### Signature
```go
func NewRecorderAuto(ctx context.Context) *Recorder
```

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for cancellation and logging

### Returns
- **`*Recorder`** - A Recorder instance with the best available backend, or a dummy backend if initialization fails.

### Behavior
- Uses cached last-successful factory on first attempt for faster initialization
- Iterates through registered factories in priority order
- Pings each backend before returning
- Returns a dummy recorder that silently succeeds if no backends initialize
- Thread-safe caching of factory results

### Example
```go
import (
    "context"
    "io"
    "github.com/xaionaro-go/audio/pkg/audio"
    _ "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
    _ "github.com/xaionaro-go/audio/pkg/audio/backends/pulseaudio"
)

ctx := context.Background()
recorder := audio.NewRecorderAuto(ctx)
defer recorder.Close()

// Ready to record audio
```
```

--------------------------------

### Integrate Syncer with Resampler

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/syncer.md

Normalize audio to the same sample rate before synchronization by using a resampler. Initialize the resampler with the input and output formats and the input audio source.

```go
// Normalize to same sample rate
resampler, _ := resampler.NewResampler(inFmt, input, outFmt)
syncer.CalculateShiftBetween(ctx, ref, resampler)
```

--------------------------------

### NewPlayerAuto

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/player.md

Automatically selects and initializes the best available audio backend for playback.

```APIDOC
## NewPlayerAuto

### Description
Automatically selects and initializes the best available audio backend for playback. Tries backends in priority order (PulseAudio &gt; PortAudio &gt; Oto), caches the last successful factory, and falls back to a dummy backend if none are available.

### Method Signature
```go
func NewPlayerAuto(ctx context.Context) *Player
```

### Parameters
#### Path Parameters
- **ctx** (context.Context) - Required - Context for cancellation and logging

### Returns
- **&Player** - A Player instance with the best available backend, or a dummy backend if initialization fails.

### Behavior
- Uses cached last-successful factory on first attempt
- Iterates through registered factories in priority order
- Pings each backend before returning
- Returns a dummy player that silently succeeds if no backends initialize

### Example
```go
import (
    "context"
    "github.com/xaionaro-go/audio/pkg/audio"
    _ "github.com/xaionaro-go/audio/pkg/audio/backends/oto"
    _ "github.com/xaionaro-go/audio/pkg/audio/backends/portaudio"
)

ctx := context.Background()
player := audio.NewPlayerAuto(ctx)
defer player.Close()

// Ready to play audio
```
```

--------------------------------

### Play Vorbis Audio with Specific Backend

Source: https://github.com/xaionaro-go/audio/blob/main/README.md

This snippet demonstrates playing Vorbis audio using a specific backend, such as PulseAudio. Ensure the backend is initialized.

```go
	pulsePCMPlayer := pulse.NewPlayerPCM()
	player := audio.NewPlayer(pulsePCMPlayer)
	defer player.Close()
	stream, err := player.PlayVorbis(ctx, vorbisReader)
```

--------------------------------

### Play Audio with PlayerAuto

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/README.md

Initialize an automatic player and play a Vorbis audio stream. Ensure the context and file path are valid.

```go
player := audio.NewPlayerAuto(ctx)
stream, _ := player.PlayVorbis(ctx, file)
```

--------------------------------

### Multi-track Audio Alignment in Go

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/README.md

Shows how to calculate the time shift between multiple audio tracks. This is useful for synchronizing recordings.

```go
results, _ := syncer.CalculateShiftBetween(ctx, reference, track1, track2)
for i, r := range results {
    fmt.Printf("Track %d: shift=%.1f samples\n", i, r.Shift)
}
```

--------------------------------

### Handle Invalid Backend Configuration with NewPlayer

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/errors.md

If a provided PCM backend fails to initialize, NewPlayer or NewPlayerAuto will return an error. This error is wrapped with context about the backend type and initialization failure.

```go
backend, err := oto.NewPlayerPCM()
// Error: "unable to get an oto context: ..."
```

--------------------------------

### Audio Synchronization with GCC-PHAT

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/INDEX.md

Demonstrates calculating the time shift and confidence between multiple audio streams using the Generalized Cross-Correlation with Phase Transform (GCC-PHAT) algorithm. Requires specifying encoding and channel count.

```go
import "github.com/xaionaro-go/audio/pkg/syncer"

syncer, _ := gccphat.NewSyncer(encoding, channels)
results, _ := syncer.CalculateShiftBetween(ctx, reference, comparison1, comparison2)

for i, r := range results {
    fmt.Printf("Track %d shift: %.1f samples (confidence: %.2f)\n", i, r.Shift, r.Confidence)
}
```

--------------------------------

### Create Oto PlayerPCM Instance

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Creates an Oto player instance. This function may fail if the audio device is unavailable or if Oto context initialization errors occur.

```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/backends/oto"
)

backend, err := oto.NewPlayerPCM()
if err != nil {
    log.Fatal(err)
}
deferr backend.Close()
```

--------------------------------

### Sample Rate Conversion (44100 Hz to 48000 Hz)

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/resampler.md

Demonstrates setting up a resampler for sample rate conversion from 44100 Hz to 48000 Hz. Linear interpolation is used for this process.

```go
format := resampler.Format{
    Channels:   2,
    SampleRate: 44100,
    PCMFormat:  audio.PCMFormatFloat32LE,
}

higherFormat := resampler.Format{
    Channels:   2,
    SampleRate: 48000,
    PCMFormat:  audio.PCMFormatFloat32LE,
}

r, err := resampler.NewResampler(format, reader, higherFormat)
```

--------------------------------

### Play PCM Audio with Oto Backend

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Plays audio using the Oto backend. Resampling is applied if input parameters differ from the context defaults. An error is returned if the buffer size differs from the compiled default.

```go
stream, err := backend.PlayPCM(
    ctx,
    48000,  // Will resample if != expected
    2,
    audio.PCMFormatFloat32LE,
    100 * time.Millisecond,
    reader,
)
```

--------------------------------

### NewPlanarizeReader Constructor

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/planar.md

Creates a new PlanarizeReader to convert interleaved audio to planar format. Ensure the bufferSize is a multiple of (sampleSize * channels).

```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/planar"
)

// Stereo (2 channels), 16-bit samples (2 bytes), 4KB buffer
reader := planar.NewPlanarizeReader(
    interleavedReader,
    2,      // channels
    2,      // bytes per sample
    4096,   // buffer size (must be divisible by 2*2=4)
)

// Read converts interleaved to planar
planarData := make([]byte, 1024)
n, err := reader.Read(planarData)
```

--------------------------------

### Create UnplanarizeReader

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/planar.md

Use NewUnplanarizeReader to create a reader that converts planar audio to interleaved format on the fly. Ensure bufferSize is a multiple of (sampleSize * channels).

```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/planar"
)

// Stereo, 16-bit samples, 4KB buffer
reader := planar.NewUnplanarizeReader(
    planarReader,
    2,      // channels
    2,      // bytes per sample
    4096,   // buffer size
)

data := make([]byte, 1024)
n, err := reader.Read(data)  // Returns interleaved data
```

--------------------------------

### Create New Resampler

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/resampler.md

Creates a new resampler instance to convert audio data from an input format and reader to a target format. Ensure that the conversion is supported, as unsupported channel conversions will result in an error. The resampler can then be used as an io.Reader.

```go
func NewResampler(
    inFormat Format,
    inReader io.Reader,
    outFormat Format,
) (*Resampler, error)
```

```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/resampler"
    "github.com/xaionaro-go/audio/pkg/audio"
)

inFormat := resampler.Format{
    Channels:   2,
    SampleRate: 44100,
    PCMFormat:  audio.PCMFormatS16LE,
}

outFormat := resampler.Format{
    Channels:   1,
    SampleRate: 48000,
    PCMFormat:  audio.PCMFormatFloat32LE,
}

resampler, err := resampler.NewResampler(inFormat, sourceReader, outFormat)
if err != nil {
    log.Fatal(err)
}

// Use resampler as io.Reader
convertedData := make([]byte, 1024)
n, err := resampler.Read(convertedData)
```

--------------------------------

### Oto Backend PlayerPCM: NewPlayerPCM

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/api-reference/backends.md

Creates an Oto player instance. This function initializes the Oto backend for audio playback.

```APIDOC
## Oto Backend PlayerPCM: NewPlayerPCM

### Description
Creates an Oto player instance. This function initializes the Oto backend for audio playback.

### Method
```go
func NewPlayerPCM() (*PlayerPCM, error)
```

### Parameters
None

### Returns
- `*PlayerPCM` - An initialized Oto player instance.
- `error` - An error if context creation or initialization fails, or if the audio device is unavailable.

### Example
```go
import (
    "github.com/xaionaro-go/audio/pkg/audio/backends/oto"
    "log"
)

backend, err := oto.NewPlayerPCM()
if err != nil {
    log.Fatal(err)
}
defer backend.Close()

// Assuming audio.NewPlayer is a function that takes a backend
// player := audio.NewPlayer(backend)
```

### Source
`pkg/audio/backends/oto/player_pcm.go:20`
```

--------------------------------

### Convert Audio Formats with Resampler

Source: https://github.com/xaionaro-go/audio/blob/main/_autodocs/README.md

Create a new resampler to convert audio between different formats. Provide input format, reader, and desired output format.

```go
r, _ := resampler.NewResampler(inFormat, reader, outFormat)
```
Tokens:
Raw