effects

Documentation

Overview

Package effects provides additional audio effects for the Beep library.

Index

• func Doppler(quality int, samplesPerMeter float64, s beep.Streamer, ...) beep.Streamer
• func Mono(s beep.Streamer) beep.Streamer
• func NewEqualizer(st beep.Streamer, sr beep.SampleRate, s EqualizerSections) beep.Streamer
• func Swap(s beep.Streamer) beep.Streamer
• func TransitionEqualPower(percent float64) float64
• func TransitionLinear(percent float64) float64
• type EqualizerSections
• type Gain
  • func (g *Gain) Err() error
  • func (g *Gain) Stream(samples [][2]float64) (n int, ok bool)
• type MonoEqualizerSection
• type MonoEqualizerSections
• type Pan
  • func (p *Pan) Err() error
  • func (p *Pan) Stream(samples [][2]float64) (n int, ok bool)
• type StereoEqualizerSection
• type StereoEqualizerSections
• type TransitionFunc
• type TransitionStreamer
  • func Transition(s beep.Streamer, len int, startGain, endGain float64, ...) *TransitionStreamer
  • func (t *TransitionStreamer) Err() error
  • func (t *TransitionStreamer) Stream(samples [][2]float64) (n int, ok bool)
• type Volume
  • func (v *Volume) Err() error
  • func (v *Volume) Stream(samples [][2]float64) (n int, ok bool)

Examples

• Transition

Functions

func Doppler

func Doppler(quality int, samplesPerMeter float64, s beep.Streamer, distance func(delta int) float64) beep.Streamer

Doppler simulates a "sound at a distance". If the sound starts at a far distance, it'll take some time to reach the ears of the listener.

The distance of the sound can change dynamically. Doppler adjusts the density of the sound (affecting its speed) to remain consistent with the distance. This is called the Doppler effect.

The arguments are:

quality:         the quality of the underlying resampler (1 or 2 is usually okay)
samplesPerMeter: sample rate / speed of sound
s:               the source streamer
distance:        a function to calculate the current distance; takes number of
                 samples Doppler wants to stream at the moment

This function is experimental and may change any time!

func Mono

func Mono(s beep.Streamer) beep.Streamer

Mono converts the wrapped Streamer to a mono buffer by downmixing the left and right channels together.

The returned Streamer propagates s's errors through Err.

func NewEqualizer

func NewEqualizer(st beep.Streamer, sr beep.SampleRate, s EqualizerSections) beep.Streamer

NewEqualizer returns a beep.Streamer that modifies the stream based on the EqualizerSection slice that is passed in. The SampleRate (sr) must match that of the Streamer.

func Swap

func Swap(s beep.Streamer) beep.Streamer

Swap swaps the left and right channel of the wrapped Streamer.

The returned Streamer propagates s's errors through Err.

func TransitionEqualPower

func TransitionEqualPower(percent float64) float64

TransitionEqualPower transitions the gain of a streamer in such a way that the total perceived volume stays constant if mixed together with another streamer doing the inverse transition.

See https://www.oreilly.com/library/view/web-audio-api/9781449332679/ch03.html#s03_2 for more information.

func TransitionLinear

func TransitionLinear(percent float64) float64

TransitionLinear transitions the gain linearly from the start to end value.

Types

type EqualizerSections

type EqualizerSections interface {
	// contains filtered or unexported methods
}

EqualizerSections is the interfacd that is passed into NewEqualizer

type Gain

type Gain struct {
	Streamer beep.Streamer
	Gain     float64
}

Gain amplifies the wrapped Streamer. The output of the wrapped Streamer gets multiplied by 1+Gain.

Note that gain is not equivalent to the human perception of volume. Human perception of volume is roughly exponential, while gain only amplifies linearly.

func (*Gain) Err

func (g *Gain) Err() error

Err propagates the wrapped Streamer's errors.

func (*Gain) Stream

func (g *Gain) Stream(samples [][2]float64) (n int, ok bool)

Stream streams the wrapped Streamer amplified by Gain.

type MonoEqualizerSection

type MonoEqualizerSection struct {
	// F0 (center frequency) sets the mid-point of the section’s
	// frequency range and is given in Hertz [Hz].
	F0 float64

	// Bf (bandwidth) represents the width of the section across
	// frequency and is measured in Hertz [Hz]. A low bandwidth
	// corresponds to a narrow frequency range meaning that the
	// section will concentrate its operation to only the
	// frequencies close to the center frequency. On the other hand,
	// a high bandwidth yields a section of wide frequency range —
	// affecting a broader range of frequencies surrounding the
	// center frequency.
	Bf float64

	// GB (bandwidth gain) is given in decibels [dB] and represents
	// the level at which the bandwidth is measured. That is, to
	// have a meaningful measure of bandwidth, we must define the
	// level at which it is measured.
	GB float64

	// G0 (reference gain) is given in decibels [dB] and simply
	// represents the level of the section’s offset.
	G0 float64

	// G (boost/cut gain) is given in decibels [dB] and prescribes
	// the effect imposed on the audio loudness for the section’s
	// frequency range. A boost/cut level of 0 dB corresponds to
	// unity (no operation), whereas negative numbers corresponds to
	// cut (volume down) and positive numbers to boost (volume up).
	G float64
}

type MonoEqualizerSections

type MonoEqualizerSections []MonoEqualizerSection

MonoEqualizerSections implements EqualizerSections and can be passed into NewEqualizer

type Pan

type Pan struct {
	Streamer beep.Streamer
	Pan      float64
}

Pan balances the wrapped Streamer between the left and the right channel. The Pan field value of -1 means that both original channels go through the left channel. The value of +1 means the same for the right channel. The value of 0 changes nothing.

func (*Pan) Err

func (p *Pan) Err() error

Err propagates the wrapped Streamer's errors.

func (*Pan) Stream

func (p *Pan) Stream(samples [][2]float64) (n int, ok bool)

Stream streams the wrapped Streamer balanced by Pan.

type StereoEqualizerSection

type StereoEqualizerSection struct {
	Left  MonoEqualizerSection
	Right MonoEqualizerSection
}

type StereoEqualizerSections

type StereoEqualizerSections []StereoEqualizerSection

StereoEqualizerSections implements EqualizerSections and can be passed into NewEqualizer

type TransitionFunc

type TransitionFunc func(percent float64) float64

TransitionFunc defines a function used in a transition to describe the progression curve from one value to the next. The input 'percent' always ranges from 0.0 to 1.0, where 0.0 represents the starting point and 1.0 represents the end point of the transition.

The returned value from TransitionFunc is expected to be in the normalized range of [0.0, 1.0]. However, it may exceed this range, providing flexibility to generate curves with momentum. The Transition() function then maps this normalized output to the actual desired range.

type TransitionStreamer

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

func Transition

func Transition(s beep.Streamer, len int, startGain, endGain float64, transitionfunc TransitionFunc) *TransitionStreamer

Transition gradually adjusts the gain of the source streamer 's' from 'startGain' to 'endGain' over the entire duration of the stream, defined by the number of samples 'len'. The transition is defined by the provided 'transitionFunc' function, which determines the gain at each point during the transition.

Example

Cross-fade between two sine tones.

package main

import (
	"time"

	"github.com/gopxl/beep"
	"github.com/gopxl/beep/effects"
	"github.com/gopxl/beep/generators"
	"github.com/gopxl/beep/speaker"
)

func main() {
	sampleRate := beep.SampleRate(44100)

	s1, err := generators.SineTone(sampleRate, 261.63)
	if err != nil {
		panic(err)
	}
	s2, err := generators.SineTone(sampleRate, 329.628)
	if err != nil {
		panic(err)
	}

	crossFades := beep.Seq(
		// Play s1 normally for 3 seconds
		beep.Take(sampleRate.N(time.Second*3), s1),
		// Play s1 and s2 together. s1 transitions from a gain of 1.0 (normal volume)
		// to 0.0 (silent) whereas s2 does the opposite. The equal power transition
		// function helps keep the overall volume constant.
		beep.Mix(
			effects.Transition(
				beep.Take(sampleRate.N(time.Second*2), s1),
				sampleRate.N(time.Second*2),
				1.0,
				0.0,
				effects.TransitionEqualPower,
			),
			effects.Transition(
				beep.Take(sampleRate.N(time.Second*2), s2),
				sampleRate.N(time.Second*2),
				0.0,
				1.0,
				effects.TransitionEqualPower,
			),
		),
		// Play the rest of s2 normally for 3 seconds
		beep.Take(sampleRate.N(time.Second*3), s2),
	)

	err = speaker.Init(sampleRate, sampleRate.N(time.Second/30))
	if err != nil {
		panic(err)
	}

	done := make(chan struct{})
	speaker.Play(beep.Seq(
		crossFades,
		beep.Callback(func() {
			done <- struct{}{}
		}),
	))
	<-done
}

func (*TransitionStreamer) Err

func (t *TransitionStreamer) Err() error

Err propagates the original Streamer's errors.

func (*TransitionStreamer) Stream

func (t *TransitionStreamer) Stream(samples [][2]float64) (n int, ok bool)

Stream fills samples with the gain-adjusted samples of the source streamer.

type Volume

type Volume struct {
	Streamer beep.Streamer
	Base     float64
	Volume   float64
	Silent   bool
}

Volume adjusts the volume of the wrapped Streamer in a human-natural way. Human's perception of volume is roughly logarithmic to gain and thus the natural way to adjust volume is exponential.

Natural Base for the exponentiation is somewhere around 2. In order to adjust volume along decibells, pick 10 as the Base and set Volume to dB/10. However, adjusting volume along decibells is nowhere as natural as with bases around 2.

Volume of 0 means no change. Negative Volume will decrease the perceived volume and positive will increase it.

With exponential gain it's impossible to achieve the zero volume. When Silent field is set to true, the output is muted.

func (*Volume) Err

func (v *Volume) Err() error

Err propagates the wrapped Streamer's errors.

func (*Volume) Stream

func (v *Volume) Stream(samples [][2]float64) (n int, ok bool)

Stream streams the wrapped Streamer with volume adjusted according to Base, Volume and Silent fields.