pyglet.media.synthesis

class ADSREnvelope

A four-part Attack, Decay, Suspend, Release envelope.

This is a four part ADSR envelope. The attack, decay, and release parameters should be provided in seconds. For example, a value of 0.1 would be 100ms. The sustain_amplitude parameter affects the sustain volume. This defaults to a value of 0.5, but can be provided on a scale from 0.0 to 1.0.

Parameters:

  • attack (float) – The attack time, in seconds.

  • decay (float) – The decay time, in seconds.

  • release (float) – The release time, in seconds.

  • sustain_amplitude (float) – The sustain amplitude (volume), from 0.0 to 1.0.

__init__(
attack: float,
decay: float,
release: float,
sustain_amplitude: float = 0.5,
)
get_generator(sample_rate: float, duration: float) → Generator[float]

Get a generator instance.

Parameters:

  • sample_rate – The sample rate of the Source this will be applied to.

  • duration – The duration of the Source. This is used to calculate the number of bytes for some Envelopes.

class Envelope

Base class for SynthesisSource amplitude envelopes.

Custom Envelopes need only provide a single get_generator method that takes the sample rate, and duration as arguments.

get_generator(sample_rate: float, duration: float) → Generator[float]

Get a generator instance.

Parameters:

  • sample_rate – The sample rate of the Source this will be applied to.

  • duration – The duration of the Source. This is used to calculate the number of bytes for some Envelopes.

class FlatEnvelope

A flat envelope, providing basic amplitude setting.

Parameters:

amplitude (float) – The amplitude (volume) of the wave, from 0.0 to 1.0. Values outside this range will be clamped.

__init__(amplitude: float = 0.5)
get_generator(
sample_rate: float = None,
duration: float = None,
) → Generator[float]

Get a generator instance.

Parameters:

  • sample_rate – The sample rate of the Source this will be applied to.

  • duration – The duration of the Source. This is used to calculate the number of bytes for some Envelopes.

class LinearDecayEnvelope

A linearly decaying envelope.

This envelope linearly decays the amplitude from the peak value to 0, over the length of the waveform.

Parameters:
peakfloat

The Initial peak value of the envelope, from 0.0 to 1.0. Values outside this range will be clamped.

__init__(peak=1.0)
get_generator(
sample_rate: float,
duration: float,
) → Generator[float]

Get a generator instance.

Parameters:

  • sample_rate – The sample rate of the Source this will be applied to.

  • duration – The duration of the Source. This is used to calculate the number of bytes for some Envelopes.

class Sawtooth
__init__(
duration: float,
frequency: int = 440,
sample_rate: int = 44800,
envelope: Envelope = None,
)

Create a Sawtooth waveform.

class Silence
__init__(
duration: float,
frequency: int = 440,
sample_rate: int = 44800,
envelope: Envelope = None,
)

Create a Silent waveform.

class Sine
__init__(
duration: float,
frequency: int = 440,
sample_rate: int = 44800,
envelope: Envelope = None,
)

Create a sinusoid (sine) waveform.

class Square
__init__(
duration: float,
frequency: int = 440,
sample_rate: int = 44800,
envelope: Envelope = None,
)

Create a Square (pulse) waveform.

class SynthesisSource

Base class for synthesized waveforms.

Parameters:

  • generator (Generator) – A waveform generator that produces a stream of floats from (-1.0, 1.0)

  • duration (float) – The length, in seconds, of audio that you wish to generate.

  • sample_rate (int) – Audio samples per second. (CD quality is 44100).

  • envelope (Envelope | None) – An optional Envelope to apply to the waveform.

__init__(
generator: Generator,
duration: float,
sample_rate: int = 44800,
envelope: Envelope | None = None,
)
get_audio_data(
num_bytes: int,
compensation_time: float = 0.0,
) → AudioData | None

Return num_bytes bytes of audio data.

Return type:

AudioData | None

is_precise() → bool

bool: Whether this source is considered precise.

x bytes on source s are considered aligned if x % s.audio_format.bytes_per_frame == 0, so there’d be no partial audio frame in the returned data.

A source is precise if - for an aligned request of x bytes - it returns::rtype: bool

  • If x or more bytes are available, x bytes.

  • If not enough bytes are available anymore, r bytes where r < x and r is aligned.

A source is not precise if it does any of these:

  • Return less than x bytes for an aligned request of x bytes although data still remains so that an additional request would return additional AudioData / not None.

  • Return more bytes than requested.

  • Return an unaligned amount of bytes for an aligned request.

pyglet’s internals are guaranteed to never make unaligned requests, or requests of less than 1024 bytes.

If this method returns False, pyglet will wrap the source in an alignment-forcing buffer creating additional overhead.

If this method is overridden to return True although the source does not comply with the requirements above, audio playback may be negatively impacted at best and memory access violations occur at worst.

Returns:

bool: Whether the source is precise.

seek(timestamp: float) → None

Seek to given timestamp.

Parameters:

timestamp (float) – Time where to seek in the source. The timestamp will be clamped to the duration of the source.

Return type:

None

class TremoloEnvelope

A tremolo envelope, for modulation amplitude.

A tremolo envelope that modulates the amplitude of the waveform with a sinusoidal pattern. The depth and rate of modulation can be specified. Depth is calculated as a percentage of the maximum amplitude. For example: a depth of 0.2 and amplitude of 0.5 will fluctuate the amplitude between 0.4 an 0.5.

Parameters:

  • depth (float) – The amount of fluctuation, from 0.0 to 1.0.

  • rate (float) – The fluctuation frequency, in seconds.

  • amplitude (float) – The peak amplitude (volume), from 0.0 to 1.0.

__init__(depth: float, rate: float, amplitude: float = 0.5)
get_generator(
sample_rate: float,
duration: float,
) → Generator[float]

Get a generator instance.

Parameters:

  • sample_rate – The sample rate of the Source this will be applied to.

  • duration – The duration of the Source. This is used to calculate the number of bytes for some Envelopes.

class Triangle
__init__(
duration: float,
frequency: int = 440,
sample_rate: int = 44800,
envelope: Envelope = None,
)

Create a Triangle waveform.

class WhiteNoise
__init__(
duration: float,
frequency: int = 440,
sample_rate: int = 44800,
envelope: Envelope = None,
)

Create a random white noise waveform.

composite_operator(*operators: Generator) → Generator

Combine the output from multiple generators.

This does a simple sum & devision of the output of two or more generators. A new generator is returned.

Return type:

Generator

noise_generator(frequency: float, sample_rate: float) → Generator[float]
pulse_generator(
frequency: float,
sample_rate: float,
duty_cycle: float = 50.0,
) → Generator[float]
sawtooth_generator(frequency: float, sample_rate: float) → Generator[float]
silence_generator(frequency: float, sample_rate: float) → Generator[float]
sine_generator(frequency: float, sample_rate: float) → Generator[float]
sine_operator(
sample_rate: int = 44800,
frequency: float = 440,
index: float = 1,
modulator: Generator | None = None,
envelope: Envelope | None = None,
) → Generator[float]

A sine wave generator that can be optionally modulated with another generator.

This generator represents a single FM Operator. It can be used by itself as a simple sine wave, or modulated by another waveform generator. Multiple operators can be linked together in this way. For example:

operator1 = sine_operator(samplerate=44800, frequency=1.22)
operator2 = sine_operator(samplerate=44800, frequency=99, modulator=operator1)
operator3 = sine_operator(samplerate=44800, frequency=333, modulator=operator2)
operator4 = sine_operator(samplerate=44800, frequency=545, modulator=operator3)
Parameters:

  • sample_rate – Audio samples per second. (CD quality is 44100).

  • frequency – The frequency, in Hz, of the waveform you wish to generate.

  • index – The modulation index. Defaults to 1

  • modulator – An optional operator to modulate this one.

  • envelope – An optional Envelope to apply to the waveform.

triangle_generator(frequency: float, sample_rate: float) → Generator[float]