pcm

Documentation

Index

• Constants
• Variables
• func Init(d Driver) error
• func InitDefault() error
• func Play(ctx context.Context, dst Writer, src Reader, options ...PlayOption) error
• func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)
• func ReadFull(r Reader, buf []byte) (n int, err error)
• type BytesReader
  • func (b *BytesReader) ReadPCM(p []byte) (n int, err error)
• type Driver
  • func (d Driver) String() string
• type Format
  • func (f Format) BytesPerSecond() uint32
  • func (f Format) PCMFormat() Format
• type Formatted
• type IOReader
  • func (ior *IOReader) ReadPCM(p []byte) (n int, err error)
• type LoopingReader
  • func (l *LoopingReader) ReadPCM(p []byte) (n int, err error)
• type PlayOption
• type PlayOptions
• type Reader
  • func LoopReader(r Reader) Reader
• type Writer
  • func NewWriter(f Format) (Writer, error)

Constants

const WriterBufferLengthInSeconds = 1

WriterBufferLengthInSeconds defines how much data os-level writers provided by this package will rotate through in a theoretical circular buffer.

Variables

var ErrMismatchedPCMFormat = fmt.Errorf("source and destination have differing PCM formats")

ErrMismatchedPCMFormat will be returned by operations streaming from Readers to Writers where the PCM formats of those Readers and Writers are not equivalent.

Functions

func Init

func Init(d Driver) error

Init initializes the pcm package to create writer objects with a specific audio driver.

func InitDefault

func InitDefault() error

InitDefault calls Init with the following value by OS: windows: DriverDirectSound linux,osx: DriverPulse

func Play

func Play(ctx context.Context, dst Writer, src Reader, options ...PlayOption) error

Play will copy data from the provided src to the provided dst until ctx is cancelled. This copy is not constant. The copy will occur in two phases: first, an initial population of the writer to give distance between the read cursor and write cursor; immediately upon this write, the writer should begin playback. Following this setup, a sub-second amount of data will streamed from src to dst after waiting that same duration. These wait times can be configured via PlayOptions.

func ReadAtLeast

func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)

ReadAtLeast acts like io.ReadAtLeast with a pcm Reader. It will read until at least min bytes have been read into the provided buffer.

func ReadFull

func ReadFull(r Reader, buf []byte) (n int, err error)

ReadFull acts like io.ReadFull with a pcm Reader. It will read until the provided buffer is competely populated by the reader.

Types

type BytesReader

type BytesReader struct {
	Format
	Buffer []byte
	Offset int
}

A BytesReader acts like a bytes.Buffer for converting raw []bytes into pcm Readers.

func (*BytesReader) ReadPCM

func (b *BytesReader) ReadPCM(p []byte) (n int, err error)

type Driver

type Driver int

A Driver defines the underlying interface that should be used for initializing PCM audio writers by this package.

const (
	// DriverDefault indicates to this package to use a default driver based on the OS.
	// Currently, for windows the default is DirectSound and for unix the default is PulseAudio.
	DriverDefault Driver = iota
	DriverPulse
	DriverDirectSound
)

func (Driver) String

func (d Driver) String() string

type Format

type Format struct {
	SampleRate uint32
	Channels   uint16
	Bits       uint16
}

Format is a PCM format. Equivalent to klang.Format.

func (Format) BytesPerSecond

func (f Format) BytesPerSecond() uint32

BytesPerSecond returns how many bytes this format would be encoded into per second in an audio stream.

func (Format) PCMFormat

func (f Format) PCMFormat() Format

PCMFormat returns this format.

type Formatted

type Formatted interface {
	// PCMFormat will return the Format used by an encoded audio or expected by an audio consumer.
	// Implementations can embed a Format struct to simplify this.
	PCMFormat() Format
}

The Formatted interface represents types that are aware of a PCM Format they expect or provide.

type IOReader

type IOReader struct {
	Format
	io.Reader
}

An IOReader converts an io.Reader into a pcm.Reader

func (*IOReader) ReadPCM

func (ior *IOReader) ReadPCM(p []byte) (n int, err error)

type LoopingReader

type LoopingReader struct {
	Reader
	// contains filtered or unexported fields
}

A LoopingReader will read from Reader continually, even after it has been fully consumed. The data read from the reader will be cached after read within the LoopingReader structure, potentially inflating memory if provided a large stream.

func (*LoopingReader) ReadPCM

func (l *LoopingReader) ReadPCM(p []byte) (n int, err error)

type PlayOption

type PlayOption func(*PlayOptions)

A PlayOption sets some value on a PlayOptions struct.

type PlayOptions

type PlayOptions struct {
	// The span of data that should be copied from reader to writer
	// at a time. If too low, may lose accuracy on windows. If too high,
	// may require manual resets when changing audio sources.
	// Defaults to 125 Milliseconds.
	CopyIncrement time.Duration
	// How many increments should make up the time between our read and write
	// cursors-- i.e. the audio will be playing at X and we will be writing to
	// X + ChaseIncrements * CopyIncrement.
	// This must be at least 2 to avoid the read and write buffers clipping.
	// Defaults to 2.
	ChaseIncrements int
	// If AllowMismatchedFormats is false, Play will error when a reader's PCM format
	// disagrees with a writer's expected PCM format. Defaults to false.
	AllowMismatchedFormats bool
}

PlayOptions define ways to configure how playback of some audio proceeds

type Reader

type Reader interface {
	Formatted
	ReadPCM(b []byte) (n int, err error)
}

A Reader mimics io.Reader for pcm data.

func LoopReader

func LoopReader(r Reader) Reader

LoopReader will cache read bytes as they are read and resend them after the reader returns EOF.

type Writer

type Writer interface {
	io.Closer
	Formatted
	// WritePCM expects PCM bytes matching the format this speaker was initialized with.
	// WritePCM will block until all of the bytes are consumed.
	WritePCM([]byte) (n int, err error)
	// Reset must clear out any written data from buffers, without stopping playback
	// TODO: do we need this?
	Reset() error
}

A Writer can have PCM formatted audio data written to it. It mimics io.Writer.

func NewWriter

func NewWriter(f Format) (Writer, error)

NewWriter returns a writer which can accept audio streamed matching the given format