README
¶
Beep 
A little package that brings sound to any Go application. Suitable for playback and audio-processing.
go get -u github.com/faiface/beep
Features
Beep is built on top of its Streamer interface, which is like io.Reader, but for audio. It was one of the best design decisions I've ever made and it enabled all the rest of the features to naturally come together with not much code.
- Decode and play WAV, MP3, OGG, and FLAC.
- Encode and save WAV.
- Very simple API. Limiting the support to stereo (two channel) audio made it possible to simplify the architecture and the API.
- Rich library of compositors and effects. Loop, pause/resume, change volume, mix, sequence, change playback speed, and more.
- Easily create new effects. With the
Streamerinterface, creating new effects is very easy. - Generate completely own artificial sounds. Again, the
Streamerinterface enables easy sound generation. - Very small codebase. The core is just ~1K LOC.
Tutorial
The Wiki contains a handful of tutorials for you to get started. They teach the fundamentals and advanced topics alike. Read them especially if you call speaker.Init every time you play something.
- Hello, Beep!
- Composing and controlling
- To buffer, or not to buffer, that is the question
- Making own streamers
Examples
| Speedy Player | Doppler Stereo Room |
|---|---|
 |
 |
Dependencies
For playback, Beep uses Oto under the hood. Check its requirements to see what you need to install for building your application.
Running an already built application should work with no extra dependencies.
Licence
Projects using beep
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
Buffer is a storage for audio data. You can think of it as a bytes.Buffer for audio samples.
func (*Buffer) Append ¶
Append adds all audio data from the given Streamer to the end of the Buffer.
The Streamer will be drained when this method finishes.
func (*Buffer) Pop ¶
Pop removes n samples from the beginning of the Buffer.
Existing Streamers are not affected.
func (*Buffer) Streamer ¶
func (b *Buffer) Streamer(from, to int) StreamSeeker
Streamer returns a StreamSeeker which streams samples in the given interval (including from, excluding to). If from<0 or to>b.Len() or to<from, this method panics.
When using multiple goroutines, synchronization of Streamers with the Buffer is not required, as Buffer is persistent (but efficient and garbage collected).
type Ctrl ¶
Ctrl allows for pausing a Streamer.
Wrap a Streamer in a Ctrl.
ctrl := &beep.Ctrl{Streamer: s}
Then, we can pause the streaming (this will cause Ctrl to stream silence).
ctrl.Paused = true
To completely stop a Ctrl before the wrapped Streamer is drained, just set the wrapped Streamer to nil.
ctrl.Streamer = nil
If you're playing a Streamer wrapped in a Ctrl through the speaker, you need to lock and unlock the speaker when modifying the Ctrl to avoid race conditions.
speaker.Play(ctrl) // ... speaker.Lock() ctrl.Paused = true speaker.Unlock()
type Format ¶
type Format struct {
// SampleRate is the number of samples per second.
SampleRate SampleRate
// NumChannels is the number of channels. The value of 1 is mono, the value of 2 is stereo.
// The samples should always be interleaved.
NumChannels int
// Precision is the number of bytes used to encode a single sample. Only values up to 6 work
// well, higher values loose precision due to floating point numbers.
Precision int
}
Format is the format of a Buffer or another audio source.
func (Format) DecodeSigned ¶
DecodeSigned decodes a single sample encoded in f.Width() bytes from p in signed format.
func (Format) DecodeUnsigned ¶
DecodeUnsigned decodes a single sample encoded in f.Width() bytes from p in unsigned format.
func (Format) EncodeSigned ¶
EncodeSigned encodes a single sample in f.Width() bytes to p in signed format.
func (Format) EncodeUnsigned ¶
EncodeUnsigned encodes a single sample in f.Width() bytes to p in unsigned format.
type Mixer ¶
type Mixer struct {
// contains filtered or unexported fields
}
Mixer allows for dynamic mixing of arbitrary number of Streamers. Mixer automatically removes drained Streamers. Mixer's stream never drains, when empty, Mixer streams silence.
func (*Mixer) Err ¶
Err always returns nil for Mixer.
There are two reasons. The first one is that erroring Streamers are immediately drained and removed from the Mixer. The second one is that one Streamer shouldn't break the whole Mixer and you should handle the errors right where they can happen.
type Resampler ¶
type Resampler struct {
// contains filtered or unexported fields
}
Resampler is a Streamer created by Resample and ResampleRatio functions. It allows dynamic changing of the resampling ratio, which can be useful for dynamically changing the speed of streaming.
func Resample ¶
func Resample(quality int, old, new SampleRate, s Streamer) *Resampler
Resample takes a Streamer which is assumed to stream at the old sample rate and returns a Streamer, which streams the data from the original Streamer resampled to the new sample rate.
This is, for example, useful when mixing multiple Streamer with different sample rates, either through a beep.Mixer, or through a speaker. Speaker has a constant sample rate. Thus, playing Streamer which stream at a different sample rate will lead to a changed speed and pitch of the playback.
sr := beep.SampleRate(48000) speaker.Init(sr, sr.N(time.Second/2)) speaker.Play(beep.Resample(3, format.SampleRate, sr, s))
In the example, the original sample rate of the source if format.SampleRate. We want to play it at the speaker's native sample rate and thus we need to resample.
The quality argument specifies the quality of the resampling process. Higher quality implies worse performance. Values below 1 or above 64 are invalid and Resample will panic. Here's a table for deciding which quality to pick.
quality | use case --------|--------- 1 | very high performance, on-the-fly resampling, low quality 3-4 | good performance, on-the-fly resampling, good quality 6 | higher CPU usage, usually not suitable for on-the-fly resampling, very good quality >6 | even higher CPU usage, for offline resampling, very good quality
Sane quality values are usually below 16. Higher values will consume too much CPU, giving negligible quality improvements.
Resample propagates errors from s.
func ResampleRatio ¶
ResampleRatio is same as Resample, except it takes the ratio of the old and the new sample rate, specifically, the old sample rate divided by the new sample rate. Aside from correcting the sample rate, this can be used to change the speed of the audio. For example, resampling at the ratio of 2 and playing at the original sample rate will cause doubled speed in playback.
type SampleRate ¶
type SampleRate int
SampleRate is the number of samples per second.
type StreamCloser ¶
type StreamCloser interface {
Streamer
// Close closes the Streamer and releases it's resources. Streamer will no longer stream any
// samples.
Close() error
}
StreamCloser is a Streamer streaming from a resource which needs to be released, such as a file or a network connection.
type StreamSeekCloser ¶
type StreamSeekCloser interface {
Streamer
Len() int
Position() int
Seek(p int) error
Close() error
}
StreamSeekCloser is a union of StreamSeeker and StreamCloser.
type StreamSeeker ¶
type StreamSeeker interface {
Streamer
// Duration returns the total number of samples of the Streamer.
Len() int
// Position returns the current position of the Streamer. This value is between 0 and the
// total length.
Position() int
// Seek sets the position of the Streamer to the provided value.
//
// If an error occurs during seeking, the position remains unchanged. This error will not be
// returned through the Streamer's Err method.
Seek(p int) error
}
StreamSeeker is a finite duration Streamer which supports seeking to an arbitrary position.
type Streamer ¶
type Streamer interface {
// Stream copies at most len(samples) next audio samples to the samples slice.
//
// The sample rate of the samples is unspecified in general, but should be specified for
// each concrete Streamer.
//
// The value at samples[i][0] is the value of the left channel of the i-th sample.
// Similarly, samples[i][1] is the value of the right channel of the i-th sample.
//
// Stream returns the number of streamed samples. If the Streamer is drained and no more
// samples will be produced, it returns 0 and false. Stream must not touch any samples
// outside samples[:n].
//
// There are 3 valid return pattterns of the Stream method:
//
// 1. n == len(samples) && ok
//
// Stream streamed all of the requested samples. Cases 1, 2 and 3 may occur in the following
// calls.
//
// 2. 0 < n && n < len(samples) && ok
//
// Stream streamed n samples and drained the Streamer. Only case 3 may occur in the
// following calls.
//
// 3. n == 0 && !ok
//
// The Streamer is drained and no more samples will come. If Err returns a non-nil error, only
// this case is valid. Only this case may occur in the following calls.
Stream(samples [][2]float64) (n int, ok bool)
// Err returns an error which occurred during streaming. If no error occurred, nil is
// returned.
//
// When an error occurs, Streamer must become drained and Stream must return 0, false
// forever.
//
// The reason why Stream doesn't return an error is that it dramatically simplifies
// programming with Streamer. It's not very important to catch the error right when it
// happens.
Err() error
}
Streamer is able to stream a finite or infinite sequence of audio samples.
func Callback ¶
func Callback(f func()) Streamer
Callback returns a Streamer, which does not stream any samples, but instead calls f the first time its Stream method is called. The speaker is locked while f is called.
func Dup ¶
Dup returns two Streamers which both stream the same data as the original s. The two Streamers can't be used concurrently without synchronization.
func Iterate ¶
Iterate returns a Streamer which successively streams Streamers obtains by calling the provided g function. The streaming stops when g returns nil.
Iterate does not propagate errors from the generated Streamers.
func Loop ¶
func Loop(count int, s StreamSeeker) Streamer
Loop takes a StreamSeeker and plays it count times. If count is negative, s is looped infinitely.
The returned Streamer propagates s's errors.
func Mix ¶
Mix takes zero or more Streamers and returns a Streamer which streams them mixed together.
Mix does not propagate errors from the Streamers.
func Seq ¶
Seq takes zero or more Streamers and returns a Streamer which streams them one by one without pauses.
Seq does not propagate errors from the Streamers.
type StreamerFunc ¶
StreamerFunc is a Streamer created by simply wrapping a streaming function (usually a closure, which encloses a time tracking variable). This sometimes simplifies creating new streamers.
Example:
noise := StreamerFunc(func(samples [][2]float64) (n int, ok bool) {
for i := range samples {
samples[i][0] = rand.Float64()*2 - 1
samples[i][1] = rand.Float64()*2 - 1
}
return len(samples), true
})
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package effects provides additional audio effects for the Beep library.
|
Package effects provides additional audio effects for the Beep library. |
|
examples
|
|
|
Package flac implements audio data decoding in FLAC format.
|
Package flac implements audio data decoding in FLAC format. |
|
Package mp3 implements audio data decoding in MP3 format.
|
Package mp3 implements audio data decoding in MP3 format. |
|
Package speaker implements playback of beep.Streamer values through physical speakers.
|
Package speaker implements playback of beep.Streamer values through physical speakers. |
|
Package vorbis implements audio data decoding in oggvorbis format.
|
Package vorbis implements audio data decoding in oggvorbis format. |
|
Package wav implements audio data decoding and encoding in WAVE format.
|
Package wav implements audio data decoding and encoding in WAVE format. |