pulse

package module
v0.0.5 Latest Latest
Warning

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

 Go to latest Published: Mar 29, 2023 License: MIT Imports: 10 Imported by: 0

README

pulse

GoDoc

PulseAudio client implementation in pure Go.

Based on github.com/yobert/pulse, which provided a very useful starting point.

Uses the pulseaudio native protocol to play audio without any CGO. The proto package exposes a very low-level API while the pulse package is more convenient to use.

status

  • proto supports almost all of the protocol, shm support is still missing.

  • pulse implements sufficient functionality for most audio playing/recording applications.

examples

see demo/play and demo/record

Documentation

Overview

Package pulse implements the pulseaudio protocol in pure go.

Index

Constants

View Source 
const EndOfData endOfData = false

EndOfData is a special error value that can be returned by a reader to stop the stream.

View Source 
const ErrConnectionClosed = pulseError("pulseaudio: connection closed")

ErrConnectionClosed is a special error value indicating that the server closed the connection.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

The Client is the connection to the pulseaudio server. An application typically only uses a single client.

func NewClient 

func NewClient(opts ...ClientOption) (*Client, error)

NewClient connects to the server.

func (*Client) Close 

func (c *Client) Close()

Close closes the client. Calling methods on a closed client may panic.

func (*Client) DefaultSink 

func (c *Client) DefaultSink() (*Sink, error)

DefaultSink returns the default output device.

func (*Client) DefaultSource 

func (c *Client) DefaultSource() (*Source, error)

DefaultSource returns the default input device.

func (*Client) ListSinks 

func (c *Client) ListSinks() ([]*Sink, error)

ListSinks returns a list of all available output devices.

func (*Client) ListSources 

func (c *Client) ListSources() ([]*Source, error)

ListSources returns a list of all available input devices.

func (*Client) NewPlayback 

func (c *Client) NewPlayback(r Reader, opts ...PlaybackOption) (*PlaybackStream, error)

NewPlayback creates a playback stream. The created stream wil not be running, it must be started with Start(). If the reader returns any error, the stream will be stopped. The special error value EndOfData can be used to intentionally stop the stream from within the callback. The order of options is important in some cases, see the documentation of the individual PlaybackOptions.

func (*Client) NewRecord 

func (c *Client) NewRecord(w Writer, opts ...RecordOption) (*RecordStream, error)

NewRecord creates a record stream. If the reader returns any error, the stream will be stopped. The created stream wil not be running, it must be started with Start(). The order of options is important in some cases, see the documentation of the individual RecordOptions.

func (*Client) RawRequest 

func (c *Client) RawRequest(req proto.RequestArgs, rpl proto.Reply) error

RawRequest can be used to send arbitrary requests.

req should be one of the request types defined by the proto package.

rpl must be a pointer to the correct reply type or nil. This funcion will panic if rpl has the wrong type.

The returned error can be compared against errors defined by the proto package to check for specific errors.

The function will always block until the server has replied, even if rpl is nil.

func (*Client) SetDefaultSink 

func (c *Client) SetDefaultSink(sinkName string) error

SetDefaultSink sets the default sink.

func (*Client) SetSinkPort 

func (c *Client) SetSinkPort(sinkIndex uint32, sinkName, port string) error

SetSinkPort sets port to the sink.

func (*Client) SetSinkVolume added in v0.0.3 

func (c *Client) SetSinkVolume(sinkIndex uint32, sinkName string, volume float64) error

SetSinkVolume toggles mute on a sink.

func (*Client) SinkByID 

func (c *Client) SinkByID(name string) (*Sink, error)

SinkByID looks up a sink id.

func (*Client) SinkMuteToggle added in v0.0.3 

func (c *Client) SinkMuteToggle(sinkIndex uint32, sinkName string) error

SinkMuteToggle toggles mute on a sink.

func (*Client) SourceByID 

func (c *Client) SourceByID(name string) (*Source, error)

SourceByID looks up a source id.

type ClientOption 

type ClientOption func(*Client)

A ClientOption supplies configuration when creating the client.

func ClientApplicationIconName 

func ClientApplicationIconName(name string) ClientOption

ClientApplicationIconName sets the application icon using an xdg icon name. This will e.g. be displayed by a volume control application to identity the application.

func ClientApplicationName 

func ClientApplicationName(name string) ClientOption

ClientApplicationName sets the application name. This will e.g. be displayed by a volume control application to identity the application. It should be human-readable and localized.

func ClientServerString 

func ClientServerString(s string) ClientOption

ClientServerString will override the default server strings. Server strings are used to connect to the server. For the server string format see https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/ServerStrings/

type Float32Reader 

type Float32Reader func([]float32) (int, error)

Float32Reader implements the Reader interface. The semantics are the same as io.Reader's Read, but it returns the number of float32 values read, not the number of bytes.

func (Float32Reader) Format 

func (c Float32Reader) Format() byte

func (Float32Reader) Read 

func (c Float32Reader) Read(buf []byte) (int, error)

type Float32Writer 

type Float32Writer func([]float32) (int, error)

Float32Writer implements the Writer interface. The semantics are the same as io.Writer's Write, but it returns the number of float32 values written, not the number of bytes.

func (Float32Writer) Format 

func (c Float32Writer) Format() byte

func (Float32Writer) Write 

func (c Float32Writer) Write(buf []byte) (int, error)

type Int16Reader 

type Int16Reader func([]int16) (int, error)

Int16Reader implements the Reader interface. The semantics are the same as io.Reader's Read, but it returns the number of int16 values read, not the number of bytes.

func (Int16Reader) Format 

func (c Int16Reader) Format() byte

func (Int16Reader) Read 

func (c Int16Reader) Read(buf []byte) (int, error)

type Int16Writer 

type Int16Writer func([]int16) (int, error)

Int16Writer implements the Writer interface. The semantics are the same as io.Writer's Write, but it returns the number of int16 values written, not the number of bytes.

func (Int16Writer) Format 

func (c Int16Writer) Format() byte

func (Int16Writer) Write 

func (c Int16Writer) Write(buf []byte) (int, error)

type Int32Reader 

type Int32Reader func([]int32) (int, error)

Int32Reader implements the Reader interface. The semantics are the same as io.Reader's Read, but it returns the number of int32 values read, not the number of bytes.

func (Int32Reader) Format 

func (c Int32Reader) Format() byte

func (Int32Reader) Read 

func (c Int32Reader) Read(buf []byte) (int, error)

type Int32Writer 

type Int32Writer func([]int32) (int, error)

Int32Writer implements the Writer interface. The semantics are the same as io.Writer's Write, but it returns the number of int32 values written, not the number of bytes.

func (Int32Writer) Format 

func (c Int32Writer) Format() byte

func (Int32Writer) Write 

func (c Int32Writer) Write(buf []byte) (int, error)

type PlaybackOption 

type PlaybackOption func(*PlaybackStream)

A PlaybackOption supplies configuration when creating streams. 

var PlaybackMono PlaybackOption = func(p *PlaybackStream) {
	p.createRequest.ChannelMap = proto.ChannelMap{proto.ChannelMono}
	p.createRequest.Channels = 1
}

PlaybackMono sets a stream to a single channel. 

var PlaybackStereo PlaybackOption = func(p *PlaybackStream) {
	p.createRequest.ChannelMap = proto.ChannelMap{proto.ChannelLeft, proto.ChannelRight}
	p.createRequest.Channels = 2
}

PlaybackStereo sets a stream to two channels.

func PlaybackBufferSize 

func PlaybackBufferSize(samples int) PlaybackOption

PlaybackBufferSize sets the size of the server-side buffer. Setting the buffer size too small causes underflows, resulting in audible artifacts.

Buffer size and latency should not be set at the same time.

func PlaybackChannels 

func PlaybackChannels(m proto.ChannelMap) PlaybackOption

PlaybackChannels sets a stream to use a custom channel map.

func PlaybackLatency 

func PlaybackLatency(seconds float64) PlaybackOption

PlaybackLatency sets the stream's latency in seconds. Setting the latency too low causes underflows, resulting in audible artifacts. Applications should generally use the highest acceptable latency.

This should be set after sample rate and channel options.

Buffer size and latency should not be set at the same time.

func PlaybackMediaIconName 

func PlaybackMediaIconName(name string) PlaybackOption

PlaybackMediaIconName sets the streams media icon using an xdg icon name. This will e.g. be displayed by a volume control application to identity the stream.

func PlaybackMediaName 

func PlaybackMediaName(name string) PlaybackOption

PlaybackMediaName sets the streams media name. This will e.g. be displayed by a volume control application to identity the stream.

func PlaybackRawOption 

func PlaybackRawOption(o func(*proto.CreatePlaybackStream)) PlaybackOption

PlaybackRawOption can be used to create custom options.

This is an advanced function, similar to (*Client).RawRequest.

func PlaybackSampleRate 

func PlaybackSampleRate(rate int) PlaybackOption

PlaybackSampleRate sets the stream's sample rate.

func PlaybackSink 

func PlaybackSink(sink *Sink) PlaybackOption

PlaybackSink sets the sink the stream should send audio to.

type PlaybackStream 

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

A PlaybackStream is used for playing audio. When creating a stream, the user must provide a callback that will be used to buffer audio data.

func (*PlaybackStream) BufferSize 

func (p *PlaybackStream) BufferSize() int

BufferSize returns the size of the server-side buffer in samples.

func (*PlaybackStream) BufferSizeBytes 

func (p *PlaybackStream) BufferSizeBytes() int

BufferSizeBytes returns the size of the server-side buffer in bytes.

func (*PlaybackStream) Channels 

func (p *PlaybackStream) Channels() int

Channels returns the number of channels.

func (*PlaybackStream) Close 

func (p *PlaybackStream) Close()

Close closes the stream.

func (*PlaybackStream) Closed 

func (p *PlaybackStream) Closed() bool

Closed returns wether the stream was closed.

func (*PlaybackStream) Drain 

func (p *PlaybackStream) Drain()

Drain waits until the playback has ended. Drain does not return when the stream is paused.

func (*PlaybackStream) Error 

func (p *PlaybackStream) Error() error

Error returns the last error returned by the stream's reader.

func (*PlaybackStream) Pause 

func (p *PlaybackStream) Pause()

Pause stops playing audio immediately.

func (*PlaybackStream) Resume 

func (p *PlaybackStream) Resume()

Resume resumes a paused stream.

func (*PlaybackStream) Running 

func (p *PlaybackStream) Running() bool

Running returns wether the stream is currently playing.

func (*PlaybackStream) SampleRate 

func (p *PlaybackStream) SampleRate() int

SampleRate returns the stream's sample rate (samples per second).

func (*PlaybackStream) Start 

func (p *PlaybackStream) Start()

Start starts playing audio.

func (*PlaybackStream) Stop 

func (p *PlaybackStream) Stop()

Stop stops playing audio; the callback will no longer be called. If the buffer size/latency is large, audio may continue to play for some time after the call to Stop.

func (*PlaybackStream) StreamIndex 

func (p *PlaybackStream) StreamIndex() uint32

StreamIndex returns the stream index. This should only be used together with (*Cient).RawRequest.

func (*PlaybackStream) StreamInputIndex 

func (p *PlaybackStream) StreamInputIndex() uint32

func (*PlaybackStream) Underflow 

func (p *PlaybackStream) Underflow() bool

Underflow returns true if any underflows happend since the last call to Start or Resume. Underflows usually happen because the latency/buffer size is too low or because the callback takes too long to run.

type Reader 

type Reader interface {
	io.Reader
	Format() byte // Format should return one of the format constants defined by the proto package
}

A Reader provides audio data in a specific format.

func NewReader 

func NewReader(r io.Reader, format byte) Reader

NewReader creates a reader from an io.Reader and a format. The format must be one of the constants defined in the proto package.

type RecordOption 

type RecordOption func(*RecordStream)

A RecordOption supplies configuration when creating streams. 

var RecordMono RecordOption = func(r *RecordStream) {
	r.createRequest.ChannelMap = proto.ChannelMap{proto.ChannelMono}
	r.createRequest.Channels = 1
}

RecordMono sets a stream to a single channel. 

var RecordStereo RecordOption = func(r *RecordStream) {
	r.createRequest.ChannelMap = proto.ChannelMap{proto.ChannelLeft, proto.ChannelRight}
	r.createRequest.Channels = 2
}

RecordStereo sets a stream to two channels.

func RecordBufferFragmentSize 

func RecordBufferFragmentSize(size uint32) RecordOption

RecordBufferFragmentSize sets the fragment size. This is the size (in bytes) of the buffer passed to the callback. Lower values reduce latency, at the cost of more overhead.

Fragment size and latency should not be set at the same time.

func RecordChannels 

func RecordChannels(m proto.ChannelMap) RecordOption

RecordChannels sets a stream to use a custom channel map.

func RecordLatency 

func RecordLatency(seconds float64) RecordOption

RecordLatency sets the stream's latency in seconds.

This should be set after sample rate and channel options.

Fragment size and latency should not be set at the same time.

func RecordMediaIconName 

func RecordMediaIconName(name string) RecordOption

RecordMediaIconName sets the streams media icon using an xdg icon name. This will e.g. be displayed by a volume control application to identity the stream.

func RecordMediaName 

func RecordMediaName(name string) RecordOption

RecordMediaName sets the streams media name. This will e.g. be displayed by a volume control application to identity the stream.

func RecordMonitor 

func RecordMonitor(sink *Sink) RecordOption

RecordMonitor sets the stream to receive audio sent to the sink.

func RecordRawOption 

func RecordRawOption(o func(*proto.CreateRecordStream)) RecordOption

RecordRawOption can be used to create custom options.

This is an advanced function, similar to (*Client).RawRequest.

func RecordSampleRate 

func RecordSampleRate(rate int) RecordOption

RecordSampleRate sets the stream's sample rate.

func RecordSource 

func RecordSource(source *Source) RecordOption

RecordSource sets the source the stream should receive audio from.

type RecordStream 

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

A RecordStream is used for recording audio. When creating a stream, the user must provide a callback that will be called with the recorded audio data.

func (*RecordStream) Channels 

func (r *RecordStream) Channels() int

Channels returns the number of channels.

func (*RecordStream) Close 

func (r *RecordStream) Close()

Close closes the stream.

func (*RecordStream) Closed 

func (r *RecordStream) Closed() bool

Closed returns wether the stream was closed. Calling other methods on a closed stream may panic.

func (*RecordStream) Error 

func (r *RecordStream) Error() error

Error returns the last error returned by the stream's writer.

func (*RecordStream) Running 

func (r *RecordStream) Running() bool

Running returns wether the stream is currently recording.

func (*RecordStream) SampleRate 

func (r *RecordStream) SampleRate() int

SampleRate returns the stream's sample rate (samples per second).

func (*RecordStream) Start 

func (r *RecordStream) Start()

Start starts recording audio.

func (*RecordStream) Stop 

func (r *RecordStream) Stop()

Stop stops recording audio; the callback will no longer be called.

func (*RecordStream) StreamIndex 

func (r *RecordStream) StreamIndex() uint32

StreamIndex returns the stream index. This should only be used together with (*Cient).RawRequest.

type Sink 

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

A Sink is an output device.

func (*Sink) Channels 

func (s *Sink) Channels() proto.ChannelMap

Channels returns the default channel map.

func (*Sink) ID 

func (s *Sink) ID() string

ID returns the sink name. Sink names are unique identifiers, but not necessarily human-readable.

func (*Sink) Info 

func (s *Sink) Info() proto.GetSinkInfoReply

Info is a helper method that exposes Sink properties.

func (*Sink) Name 

func (s *Sink) Name() string

Name is a human-readable name describing the sink.

func (*Sink) SampleRate 

func (s *Sink) SampleRate() int

SampleRate returns the default sample rate.

func (*Sink) SinkIndex 

func (s *Sink) SinkIndex() uint32

SinkIndex returns the sink index. This should only be used together with (*Client).RawRequest.

func (*Sink) Volume added in v0.0.3 

func (s *Sink) Volume() float64

Volume returns the sink volume.

type Source 

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

A Source is an input device.

func (*Source) Channels 

func (s *Source) Channels() proto.ChannelMap

Channels returns the default channel map.

func (*Source) ID 

func (s *Source) ID() string

ID returns the source name. Source names are unique identifiers, but not necessarily human-readable.

func (*Source) Name 

func (s *Source) Name() string

Name is a human-readable name describing the source.

func (*Source) SampleRate 

func (s *Source) SampleRate() int

SampleRate returns the default sample rate.

func (*Source) SourceIndex 

func (s *Source) SourceIndex() uint32

SourceIndex returns the source index. This should only be used together with (*Cient).RawRequest.

type Uint8Reader 

type Uint8Reader func([]byte) (int, error)

Uint8Reader implements the Reader interface. The semantics are the same as io.Reader's Read.

func (Uint8Reader) Format 

func (c Uint8Reader) Format() byte

func (Uint8Reader) Read 

func (c Uint8Reader) Read(buf []byte) (int, error)

type Uint8Writer 

type Uint8Writer func([]byte) (int, error)

Uint8Writer implements the Writer interface. The semantics are the same as io.Writer's Write.

func (Uint8Writer) Format 

func (c Uint8Writer) Format() byte

func (Uint8Writer) Write 

func (c Uint8Writer) Write(buf []byte) (int, error)

type Writer 

type Writer interface {
	io.Writer
	Format() byte // Format should return one of the format constants defined by the proto package
}

A Writer accepts audio data in a specific format.

func NewWriter 

func NewWriter(w io.Writer, format byte) Writer

NewWriter creates a writer from an io.Writer and a format. The format must be one of the constants defined in the proto package.

Source Files

View all Source files

Directories

Path Synopsis
demo
play
record
subscription

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.