pulse

package module
v0.0.0-...-75ac54e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 6, 2017 License: MIT Imports: 5 Imported by: 15

README

pulse-simple

Cgo bindings to PulseAudio's Simple API, for easily playing or capturing raw audio.

The full Simple API is supported, including channel mapping and setting buffer attributes.

prerequisites

These bindings require the pulseaudio C headers to be available. On Ubuntu they can be installed by sudo apt install libpulse-dev, and on other distros there should be a similar package available.

quick test

If everything is configured correctly, go run examples/sinewave.go should output some simple tones via pulseaudio.

usage

Basic usage is to request a playback or capture stream, then write bytes to or read bytes from it.

Reading and writing will block until the given byte slice is completely consumed or filled, or an error occurs.

The format of the data will be as requested on stream creation.

For example, assuming "data" contains raw bytes representing stereophonic audio in little-endian 16-bit integer PCM format, the following will obtain a playback stream and play the given data as audio on the default sound device.

ss := pulse.SampleSpec{pulse.SAMPLE_S16LE, 44100, 2}
stream, _ := pulse.Playback("my app", "my stream", &ss)
defer stream.Free()
defer stream.Drain()
stream.Write(data)

More example usage can be found in the examples folder.

For more information, see the PulseAudio Simple API documentation at http://www.freedesktop.org/software/pulseaudio/doxygen/simple.html

license

MIT (see the included LICENSE file for full license text)

Documentation

Overview

pulse-simple wraps PulseAudio's Simple API using cgo, for easy audio playback and capture via PulseAudio.

Basic usage is to request a playback or capture stream, then write bytes to or read bytes from it.

Reading and writing will block until the given byte slice is completely consumed or filled, or an error occurs.

The format of the data will be as requested on stream creation. 

ss := pulse.SampleSpec{pulse.SAMPLE_S16LE, 44100, 2}
stream, _ := pulse.Playback("my app", "my stream", &ss)
defer stream.Free()
defer stream.Drain()
stream.Write(data)

More example usage can be found in the examples folder.

For more information, see the PulseAudio Simple API documentation at http://www.freedesktop.org/software/pulseaudio/doxygen/simple.html

Index

Constants

View Source 
const (
	CHANNELS_MAX = C.PA_CHANNELS_MAX // Maximum number of allowed channels
	RATE_MAX     = C.PA_RATE_MAX     // Maximum allowed sample rate
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BufferAttr 

type BufferAttr struct {
	Maxlength uint32 // Playback and Capture, maximum buffer size in bytes
	Tlength   uint32 // Playback-only, target buffer size in bytes
	Prebuf    uint32 // Playback-only, pre-bufferring in bytes
	Minreq    uint32 // Plyback-only, minimum server-client request size in bytes
	Fragsize  uint32 // Capture-only, fragment size in bytes
}

BufferAttr holds information about desired data transfer buffer sizes. All values are recommended to be initialized to (uint32) - 1, which will choose default values depending on the server.

func NewBufferAttr 

func NewBufferAttr() *BufferAttr

NewBufferAttr initializes a BufferAttr with values indicating default.

type ChannelMap 

type ChannelMap struct {
	Channels uint8
	Map      [CHANNELS_MAX]ChannelPosition
}

ChannelMap can be used to attach labels to specific channels of a stream.

These values are relevant for conversion and mixing of streams.

func (*ChannelMap) CanBalance 

func (m *ChannelMap) CanBalance() bool

ChannelMap.CanBalance returns true iff applying a volume 'balance' makes sense with this mapping, i.e. there are left/right channels available.

func (*ChannelMap) CanFade 

func (m *ChannelMap) CanFade() bool

ChannelMap.CanFade returns true iff applying a volume 'fade' makes sense with this mapping, i.e. there are front/rear channels available.

func (*ChannelMap) Compatible 

func (m *ChannelMap) Compatible(spec *SampleSpec) bool

ChannelMap.Compatible returns true iff compatible with the given sample spec.

func (*ChannelMap) Equal 

func (m *ChannelMap) Equal(other *ChannelMap) bool

ChannelMap.Equal compares two channel maps, returning true iff they match.

func (*ChannelMap) HasPosition 

func (m *ChannelMap) HasPosition(p ChannelPosition) bool

ChannelMap.HasPosition returns true iff the specified channel position is available at least once in the channel map.

func (*ChannelMap) Init 

func (m *ChannelMap) Init()

ChannelMap.Init initializes the ChannelMp to a defined state, for which ChannelMap.Valid() will return false.

calling Init() on a ChannelMap is not necessary, but this method is included for compatibility.

func (*ChannelMap) InitAuto 

func (m *ChannelMap) InitAuto(channels uint, mapping ChannelMapDef) error

ChannelMap.InitAuto initializes the ChannelMap using the given mapping and number of channels.

If there is no default channel map known for the given number of channels and mapping, then the ChannelMap remains unchanged and an error is returned.

func (*ChannelMap) InitExtend 

func (m *ChannelMap) InitExtend(channels uint, mapping ChannelMapDef)

ChannelMap.InitExtend initializes the ChannelMap using the given mapping and number of channels.

If there is no default channel map known for the given number of channels and mapping, then it will synthesize a mapping based on a known mapping with fewer channels, and fill up the rest with AUX0...AUX31 channels.

func (*ChannelMap) InitMono 

func (m *ChannelMap) InitMono()

ChannelMap.InitMono initializes the channel map for monaural audio.

func (*ChannelMap) InitStereo 

func (m *ChannelMap) InitStereo()

ChannelMap.InitStereo initializes the channel map for stereophonic audio.

func (*ChannelMap) Mask 

func (m *ChannelMap) Mask() ChannelPositionMask

ChannelMap.Mask generates a bitmask from a ChannelMap.

func (*ChannelMap) Name 

func (m *ChannelMap) Name() (string, error)

ChannelMap.Name tries to find a well-known name for this channel mapping, i.e. "stereo", "surround-71" and so on.

If the channel mapping is unknown, an error will be returned.

func (*ChannelMap) Parse 

func (m *ChannelMap) Parse(s string)

ChannelMap.Parse parses a channel position list or well-known mapping name into a channel map structure.

Input should be as returned by ChannelMap.Name() or ChannelMap.String().

func (*ChannelMap) PrettyName 

func (m *ChannelMap) PrettyName() (string, error)

ChannelMap.PrettyName tries to find a human-readable text label for this channel mapping, i.e. "Stereo", "Surround 7.1" and so on.

If the channel mapping is unknown, an error will be returned.

func (*ChannelMap) String 

func (m *ChannelMap) String() string

ChannelMap.String returns a string describing the mapping.

func (*ChannelMap) Superset 

func (m *ChannelMap) Superset(other *ChannelMap) bool

ChannelMap.Superset returns true iff every channel defined in "other" is also defined in the ChannelMap.

func (*ChannelMap) Valid 

func (m *ChannelMap) Valid() bool

ChannelMap.Valid returns true iff the channel map is considered valid.

type ChannelMapDef 

type ChannelMapDef C.pa_channel_map_def_t
const (
	CHANNEL_MAP_AIFF    ChannelMapDef = C.PA_CHANNEL_MAP_AIFF
	CHANNEL_MAP_ALSA    ChannelMapDef = C.PA_CHANNEL_MAP_ALSA
	CHANNEL_MAP_AUX     ChannelMapDef = C.PA_CHANNEL_MAP_AUX
	CHANNEL_MAP_WAVEEX  ChannelMapDef = C.PA_CHANNEL_MAP_WAVEEX
	CHANNEL_MAP_OSS     ChannelMapDef = C.PA_CHANNEL_MAP_OSS
	CHANNEL_MAP_DEF_MAX ChannelMapDef = C.PA_CHANNEL_MAP_DEF_MAX
	CHANNEL_MAP_DEFAULT ChannelMapDef = C.PA_CHANNEL_MAP_DEFAULT
)

type ChannelPosition 

type ChannelPosition C.pa_channel_position_t
const (
	CHANNEL_POSITION_INVALID ChannelPosition = C.PA_CHANNEL_POSITION_INVALID
	CHANNEL_POSITION_MONO    ChannelPosition = C.PA_CHANNEL_POSITION_MONO

	CHANNEL_POSITION_FRONT_LEFT   ChannelPosition = C.PA_CHANNEL_POSITION_FRONT_LEFT
	CHANNEL_POSITION_FRONT_RIGHT  ChannelPosition = C.PA_CHANNEL_POSITION_FRONT_RIGHT
	CHANNEL_POSITION_FRONT_CENTER ChannelPosition = C.PA_CHANNEL_POSITION_FRONT_CENTER

	CHANNEL_POSITION_LEFT   ChannelPosition = C.PA_CHANNEL_POSITION_LEFT
	CHANNEL_POSITION_RIGHT  ChannelPosition = C.PA_CHANNEL_POSITION_RIGHT
	CHANNEL_POSITION_CENTER ChannelPosition = C.PA_CHANNEL_POSITION_CENTER

	CHANNEL_POSITION_REAR_CENTER ChannelPosition = C.PA_CHANNEL_POSITION_REAR_CENTER
	CHANNEL_POSITION_REAR_LEFT   ChannelPosition = C.PA_CHANNEL_POSITION_REAR_LEFT
	CHANNEL_POSITION_REAR_RIGHT  ChannelPosition = C.PA_CHANNEL_POSITION_REAR_RIGHT

	CHANNEL_POSITION_LFE       ChannelPosition = C.PA_CHANNEL_POSITION_LFE
	CHANNEL_POSITION_SUBWOOFER ChannelPosition = C.PA_CHANNEL_POSITION_SUBWOOFER

	CHANNEL_POSITION_FRONT_LEFT_OF_CENTER  ChannelPosition = C.PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER
	CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER ChannelPosition = C.PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER

	CHANNEL_POSITION_SIDE_LEFT  ChannelPosition = C.PA_CHANNEL_POSITION_SIDE_LEFT
	CHANNEL_POSITION_SIDE_RIGHT ChannelPosition = C.PA_CHANNEL_POSITION_SIDE_RIGHT

	CHANNEL_POSITION_AUX0  ChannelPosition = C.PA_CHANNEL_POSITION_AUX0
	CHANNEL_POSITION_AUX1  ChannelPosition = C.PA_CHANNEL_POSITION_AUX1
	CHANNEL_POSITION_AUX2  ChannelPosition = C.PA_CHANNEL_POSITION_AUX2
	CHANNEL_POSITION_AUX3  ChannelPosition = C.PA_CHANNEL_POSITION_AUX3
	CHANNEL_POSITION_AUX4  ChannelPosition = C.PA_CHANNEL_POSITION_AUX4
	CHANNEL_POSITION_AUX5  ChannelPosition = C.PA_CHANNEL_POSITION_AUX5
	CHANNEL_POSITION_AUX6  ChannelPosition = C.PA_CHANNEL_POSITION_AUX6
	CHANNEL_POSITION_AUX7  ChannelPosition = C.PA_CHANNEL_POSITION_AUX7
	CHANNEL_POSITION_AUX8  ChannelPosition = C.PA_CHANNEL_POSITION_AUX8
	CHANNEL_POSITION_AUX9  ChannelPosition = C.PA_CHANNEL_POSITION_AUX9
	CHANNEL_POSITION_AUX10 ChannelPosition = C.PA_CHANNEL_POSITION_AUX10
	CHANNEL_POSITION_AUX11 ChannelPosition = C.PA_CHANNEL_POSITION_AUX11
	CHANNEL_POSITION_AUX12 ChannelPosition = C.PA_CHANNEL_POSITION_AUX12
	CHANNEL_POSITION_AUX13 ChannelPosition = C.PA_CHANNEL_POSITION_AUX13
	CHANNEL_POSITION_AUX14 ChannelPosition = C.PA_CHANNEL_POSITION_AUX14
	CHANNEL_POSITION_AUX15 ChannelPosition = C.PA_CHANNEL_POSITION_AUX15
	CHANNEL_POSITION_AUX16 ChannelPosition = C.PA_CHANNEL_POSITION_AUX16
	CHANNEL_POSITION_AUX17 ChannelPosition = C.PA_CHANNEL_POSITION_AUX17
	CHANNEL_POSITION_AUX18 ChannelPosition = C.PA_CHANNEL_POSITION_AUX18
	CHANNEL_POSITION_AUX19 ChannelPosition = C.PA_CHANNEL_POSITION_AUX19
	CHANNEL_POSITION_AUX20 ChannelPosition = C.PA_CHANNEL_POSITION_AUX20
	CHANNEL_POSITION_AUX21 ChannelPosition = C.PA_CHANNEL_POSITION_AUX21
	CHANNEL_POSITION_AUX22 ChannelPosition = C.PA_CHANNEL_POSITION_AUX22
	CHANNEL_POSITION_AUX23 ChannelPosition = C.PA_CHANNEL_POSITION_AUX23
	CHANNEL_POSITION_AUX24 ChannelPosition = C.PA_CHANNEL_POSITION_AUX24
	CHANNEL_POSITION_AUX25 ChannelPosition = C.PA_CHANNEL_POSITION_AUX25
	CHANNEL_POSITION_AUX26 ChannelPosition = C.PA_CHANNEL_POSITION_AUX26
	CHANNEL_POSITION_AUX27 ChannelPosition = C.PA_CHANNEL_POSITION_AUX27
	CHANNEL_POSITION_AUX28 ChannelPosition = C.PA_CHANNEL_POSITION_AUX28
	CHANNEL_POSITION_AUX29 ChannelPosition = C.PA_CHANNEL_POSITION_AUX29
	CHANNEL_POSITION_AUX30 ChannelPosition = C.PA_CHANNEL_POSITION_AUX30
	CHANNEL_POSITION_AUX31 ChannelPosition = C.PA_CHANNEL_POSITION_AUX31

	CHANNEL_POSITION_TOP_CENTER ChannelPosition = C.PA_CHANNEL_POSITION_TOP_CENTER

	CHANNEL_POSITION_TOP_FRONT_LEFT   ChannelPosition = C.PA_CHANNEL_POSITION_TOP_FRONT_LEFT
	CHANNEL_POSITION_TOP_FRONT_RIGHT  ChannelPosition = C.PA_CHANNEL_POSITION_TOP_FRONT_RIGHT
	CHANNEL_POSITION_TOP_FRONT_CENTER ChannelPosition = C.PA_CHANNEL_POSITION_TOP_FRONT_CENTER

	CHANNEL_POSITION_TOP_REAR_LEFT   ChannelPosition = C.PA_CHANNEL_POSITION_TOP_REAR_LEFT
	CHANNEL_POSITION_TOP_REAR_RIGHT  ChannelPosition = C.PA_CHANNEL_POSITION_TOP_REAR_RIGHT
	CHANNEL_POSITION_TOP_REAR_CENTER ChannelPosition = C.PA_CHANNEL_POSITION_TOP_REAR_CENTER

	CHANNEL_POSITION_MAX ChannelPosition = C.PA_CHANNEL_POSITION_MAX
)

func ChannelPositionFromString 

func ChannelPositionFromString(s string) ChannelPosition

ChannelPositionFromString returns the ChannelPosition described by the given string.

The string should be as returned by ChannelPosition.String().

func (ChannelPosition) Mask 

func (p ChannelPosition) Mask() ChannelPositionMask

ChannelPosition.Mask makes a bitmask from a ChannelPosition.

func (ChannelPosition) PrettyString 

func (p ChannelPosition) PrettyString() string

ChannelPosition.PrettyString returns a human-readable text label for the channel position.

func (ChannelPosition) String 

func (p ChannelPosition) String() string

ChannelPosition.String returns a text label for the channel position.

type ChannelPositionMask 

type ChannelPositionMask uint64

type SampleFormat 

type SampleFormat C.pa_sample_format_t
const (
	SAMPLE_U8        SampleFormat = C.PA_SAMPLE_U8
	SAMPLE_ALAW      SampleFormat = C.PA_SAMPLE_ALAW
	SAMPLE_ULAW      SampleFormat = C.PA_SAMPLE_ULAW
	SAMPLE_S16LE     SampleFormat = C.PA_SAMPLE_S16LE
	SAMPLE_S16BE     SampleFormat = C.PA_SAMPLE_S16BE
	SAMPLE_FLOAT32LE SampleFormat = C.PA_SAMPLE_FLOAT32LE
	SAMPLE_FLOAT32BE SampleFormat = C.PA_SAMPLE_FLOAT32BE
	SAMPLE_S32LE     SampleFormat = C.PA_SAMPLE_S32LE
	SAMPLE_S32BE     SampleFormat = C.PA_SAMPLE_S32BE
	SAMPLE_S24LE     SampleFormat = C.PA_SAMPLE_S24LE
	SAMPLE_S24BE     SampleFormat = C.PA_SAMPLE_S24BE
	SAMPLE_S24_32LE  SampleFormat = C.PA_SAMPLE_S24_32LE
	SAMPLE_S24_32BE  SampleFormat = C.PA_SAMPLE_S24_32BE
	SAMPLE_MAX       SampleFormat = C.PA_SAMPLE_MAX
	SAMPLE_INVALID   SampleFormat = C.PA_SAMPLE_INVALID
)
const (
	SAMPLE_S16NE     SampleFormat = C.PA_SAMPLE_S16NE
	SAMPLE_FLOAT32NE SampleFormat = C.PA_SAMPLE_FLOAT32NE
	SAMPLE_S32NE     SampleFormat = C.PA_SAMPLE_S32NE
	SAMPLE_S24NE     SampleFormat = C.PA_SAMPLE_S24NE
	SAMPLE_S24_32NE  SampleFormat = C.PA_SAMPLE_S24_32NE
	SAMPLE_S16RE     SampleFormat = C.PA_SAMPLE_S16RE
	SAMPLE_FLOAT32RE SampleFormat = C.PA_SAMPLE_FLOAT32RE
	SAMPLE_S32RE     SampleFormat = C.PA_SAMPLE_S32RE
	SAMPLE_S24RE     SampleFormat = C.PA_SAMPLE_S24RE
	SAMPLE_S24_32RE  SampleFormat = C.PA_SAMPLE_S24_32RE
)
const SAMPLE_FLOAT32 SampleFormat = C.PA_SAMPLE_FLOAT32

func ParseSampleFormat 

func ParseSampleFormat(s string) SampleFormat

ParseSampleFormat returns the SampleFormat described by the given string.

The string should be as returned by SampleFormat.String().

func (SampleFormat) IsBe 

func (f SampleFormat) IsBe() int

SampleFormat.IsBe returns 1 when the format is big endian.

Returns -1 when endianness does not apply to this format.

func (SampleFormat) IsLe 

func (f SampleFormat) IsLe() int

SampleFormat.IsLe returns 1 when the format is little endian.

Returns -1 when endianness does not apply to this format.

func (SampleFormat) IsNe 

func (f SampleFormat) IsNe() int

SampleFormat.IsNe returns 1 when the format is native endian.

Returns -1 when endianness does not apply to this format.

func (SampleFormat) IsRe 

func (f SampleFormat) IsRe() int

SampleFormat.IsRe returns 1 when the format is reverse endian.

Returns -1 when endianness does not apply to this format.

func (SampleFormat) SampleSize 

func (f SampleFormat) SampleSize() uint

SampleFormat.SampleSize returns the size of a single sample in bytes.

func (SampleFormat) String 

func (f SampleFormat) String() string

SampleFormat.String returns a string describing the format.

type SampleSpec 

type SampleSpec struct {
	Format   SampleFormat
	Rate     uint32
	Channels uint8
}

func (*SampleSpec) BytesPerSecond 

func (spec *SampleSpec) BytesPerSecond() uint

SampleSpec.BytesPerSecond returns the number of bytes per second of audio.

func (*SampleSpec) BytesToUsec 

func (spec *SampleSpec) BytesToUsec(bytes uint) uint64

SampleSpec.BytesToUsec returns the number of microseconds taken to play the given number of bytes as audio.

The return value will always be rounded down for non-integral values.

func (*SampleSpec) Equal 

func (spec *SampleSpec) Equal(other *SampleSpec) bool

SampleSpec.Equal returns whether or not the given sample specs match.

func (*SampleSpec) FrameSize 

func (spec *SampleSpec) FrameSize() uint

SampleSpec.FrameSize returns the size of a single audio frame in bytes.

func (*SampleSpec) Init 

func (spec *SampleSpec) Init()

SampleSpec.Init initializes the SampleSpec to a defined state, for which SampleSpec.Valid() will return false.

Calling Init() on a SampleSpec is not necessary, but this method is included for compatibility.

func (*SampleSpec) SampleSize 

func (spec *SampleSpec) SampleSize() uint

SampleSpec.SampleSize returns the size of a single sample in bytes.

func (*SampleSpec) String 

func (spec *SampleSpec) String() string

SampleSpec.String returns a human-readable string describing the spec.

func (*SampleSpec) UsecToBytes 

func (spec *SampleSpec) UsecToBytes(usec uint64) uint

SampleSpec.UsecToBytes returns the number of bytes required for the given number of microseconds of audio.

The return value will always be rounded down for non-integral values.

func (*SampleSpec) Valid 

func (spec *SampleSpec) Valid() bool

SampleSpec.Valid returns whether or not the given sample spec is valid.

type Stream 

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

func Capture 

func Capture(clientName, streamName string, spec *SampleSpec) (*Stream, error)

Capture creates a new stream for recording and returns its pointer.

func NewStream 

func NewStream(
	serverName, clientName string,
	dir StreamDirection,
	deviceName, streamName string,
	spec *SampleSpec,
	cmap *ChannelMap,
	battr *BufferAttr,
) (*Stream, error)

func Playback 

func Playback(clientName, streamName string, spec *SampleSpec) (*Stream, error)

Playback creates a new stream for playback and returns its pointer.

func (*Stream) Drain 

func (s *Stream) Drain() error

Stream.Drain blocks until all buffered data has finished playing.

func (*Stream) Flush 

func (s *Stream) Flush() error

Stream.Flush flushes the playback buffer, discarding any audio therein

func (*Stream) Free 

func (s *Stream) Free()

Stream.Free closes the stream and frees the associated memory. The stream becomes invalid after this has been called. This should usually be deferred immediately after obtaining a stream.

func (*Stream) Latency 

func (s *Stream) Latency() (uint64, error)

Stream.Latency returns the playback latency in microseconds.

func (*Stream) Read 

func (s *Stream) Read(data []byte) (int, error)

Stream.Read reads data from the stream, blocking until it has filled the provided slice.

func (*Stream) Write 

func (s *Stream) Write(data []byte) (int, error)

Stream.Write writes the given data to the stream, blocking until the data has been written.

type StreamDirection 

type StreamDirection C.pa_stream_direction_t
const (
	STREAM_NODIRECTION StreamDirection = C.PA_STREAM_NODIRECTION
	STREAM_PLAYBACK    StreamDirection = C.PA_STREAM_PLAYBACK
	STREAM_RECORD      StreamDirection = C.PA_STREAM_RECORD
	STREAM_UPLOAD      StreamDirection = C.PA_STREAM_UPLOAD
)

Source Files

View all Source files

Directories

Path Synopsis
capture some audio from the default device, and play it back.
 capture some audio from the default device, and play it back.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.