audio

Documentation

Overview

Package audio provides utilities for playing or writing audio streams to OS consumers

Index

• Constants
• Variables
• func BatchLoad(baseFolder string) error
• func BlankBatchLoad(baseFolder string) error
• func FadeIn(dur time.Duration, in pcm.Reader) pcm.Reader
• func FadeOut(dur time.Duration, in pcm.Reader) pcm.Reader
• func Get(file string) (pcm.Reader, error)
• func Init(d Driver) error
• func InitDefault() error
• func Load(file string) (pcm.Reader, error)
• func LoopReader(r pcm.Reader) pcm.Reader
• func MustNewWriter(f pcm.Format) pcm.Writer
• func NewWriter(f pcm.Format) (pcm.Writer, error)
• func Play(ctx context.Context, src pcm.Reader, options ...PlayOption) error
• func ReadAtLeast(r pcm.Reader, buf []byte, min int) (n int, err error)
• func ReadFull(r pcm.Reader, buf []byte) (n int, err error)
• type BytesReader
  • func ReadAll(r pcm.Reader) *BytesReader
  • func (b *BytesReader) Copy() *BytesReader
  • func (b *BytesReader) ReadPCM(p []byte) (n int, err error)
• type Cache
  • func NewCache() *Cache
  • func (c *Cache) Clear(key string)
  • func (c *Cache) ClearAll()
  • func (c *Cache) Get(file string) (pcm.Reader, error)
  • func (c *Cache) Load(file string) (pcm.Reader, error)
• type Driver
  • func (d Driver) String() string
• type LoopingReader
  • func (l *LoopingReader) ReadPCM(p []byte) (n int, err error)
• type PlayOption
• type PlayOptions

Constants

const WriterBufferLengthInSeconds float64 = .5

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

Variables

var DefaultCache = NewCache()

DefaultCache is the receiver for package level loading operations.

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.

var SkipDevicesContaining string = "HDMI"

TODO: do other drivers need this? Can we pick devices more intelligently?

Functions

func BatchLoad

func BatchLoad(baseFolder string) error

BatchLoad attempts to load all audio files within a given directory should their file ending match a registered audio file parser

func BlankBatchLoad

func BlankBatchLoad(baseFolder string) error

BlankBatchLoad acts like BatchLoad, but replaces all loaded assets with empty audio constructs. This is intended to reduce start-up times in development.

func FadeIn

func FadeIn(dur time.Duration, in pcm.Reader) pcm.Reader

FadeIn wraps a reader such that it will linearly fade in over the given duration.

func FadeOut

func FadeOut(dur time.Duration, in pcm.Reader) pcm.Reader

FadeOut wraps a reader such that it will linearly fade out over the given duration.

func Get

func Get(file string) (pcm.Reader, error)

Get calls Get on the Default Cache.

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 Load

func Load(file string) (pcm.Reader, error)

Load calls Load on the Default Cache.

func LoopReader

func LoopReader(r pcm.Reader) pcm.Reader

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

func MustNewWriter

func MustNewWriter(f pcm.Format) pcm.Writer

MustNewWriter calls NewWriter and panics if an error is returned.

func NewWriter

func NewWriter(f pcm.Format) (pcm.Writer, error)

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

func Play

func Play(ctx context.Context, src pcm.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 pcm.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 pcm.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 {
	pcm.Format
	Buffer []byte
	Offset int
}

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

func ReadAll

func ReadAll(r pcm.Reader) *BytesReader

ReadAll will read all of the content within a reader and convert it into a BytesReader. Use carefully; use on a LoopingReader or reader which generates its data (e.g. synth types) will likely read until OOM.

func (*BytesReader) Copy

func (b *BytesReader) Copy() *BytesReader

func (*BytesReader) ReadPCM

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

type Cache

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

Cache is a simple audio data cache

func NewCache

func NewCache() *Cache

NewCache returns an empty Cache

func (*Cache) Clear

func (c *Cache) Clear(key string)

Clear will remove elements matching the given key from the Cache.

func (*Cache) ClearAll

func (c *Cache) ClearAll()

ClearAll will remove all elements from a Cache

func (*Cache) Get

func (c *Cache) Get(file string) (pcm.Reader, error)

Get will read cached audio data from Load, or error if the given file is not in the cache.

func (*Cache) Load

func (c *Cache) Load(file string) (pcm.Reader, error)

Load loads the given file and caches it by two keys: the full file name given and the final element of the file's path. If the file cannot be found or if its extension is not supported an error will be returned.

type Driver

type Driver int

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

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
	DriverALSA
)

func (Driver) String

func (d Driver) String() string

type LoopingReader

type LoopingReader struct {
	pcm.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 {
	// If FadeOutOnStop is non-zero, when this play is stopped early it will fade out for this duration.
	FadeOutOnStop time.Duration

	// If Destination is not provided, Play will create a new writer which will be
	// closed after Play is complete.
	Destination pcm.Writer

	// 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 50 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

	ClearBufferOnStop bool
}

PlayOptions define ways to configure how playback of some audio proceeds