Skip to content

glyphtune

glyphtune

glyphtune is in pre-alpha, and so is this documentation.

glyphtune.signal

Audio signal representation and manipulation.

Signal

Bases: NDArrayOperatorsMixin

Class representing audio signals.

Basically a wrapper around a Numpy array with validation, properties, and manipulation methods specific to audio signals. Can be indexed like Numpy arrays, and can be passed to Python operators and Numpy functions in most ways, which returns a new signal if possible, or, if no possible signal results from an operation, a normal Numpy array is returned instead.

data: np.ndarray[Any, np.dtype[Any]] property writable

Array containing the data of the signal.

shape: tuple[int, ...] property

Shape of the signal array.

channels: int property

The number of channels of the signal.

length: int property

The length, in samples, of the signal.

is_mono: bool property

Equivalent to signal.channels == 1.

is_stereo: bool property

Equivalent to signal.channels == 2.

absolute_peak: numbers.Real property

Equivalent to max(abs(signal.data)).

dc_offset: np.ndarray[Any, np.dtype[Any]] property

DC offset (also known as DC bias) along each channel of the signal.

__init__(data: npt.ArrayLike) -> None

Initializes an audio signal with an array-like.

Parameters:

  • data (ArrayLike) –

    numerical array-like of the shape (channels, samples).

to_mono() -> Signal

Returns the signal converted to mono.

This is done by taking the mean along all channels of every sample.

expand_channels(channels: int) -> Signal

Returns the expansion of a mono signal into an arbitrary number of channels.

This is done by tiling copies of the mono signal for each channel.

normalize() -> Signal

Returns the signal normalized between -1 and 1.

remove_dc_offset() -> Signal

Returns the signal with the DC offset removed.

reverse() -> Signal

Returns the signal reversed.

is_signal_like(data: npt.ArrayLike) -> bool

Returns whether the given data can be a signal.

Parameters:

  • data (ArrayLike) –

    data to check.

glyphtune.waveforms

A hierarchy of classes for creating waveforms and sampling them into audio signals.

Waveform

Bases: NDArrayOperatorsMixin

Base class representing waveforms.

Waveform objects do not store any audio data. Instead, they must generate that data when one of their sampling functions is called.

Waveform objects can be used as operands with Python operators and as inputs to NumPy functions along with other waveforms and numbers. This returns a waveforms.OperationWaveform.

sample_time(time: signal.Signal) -> signal.Signal

Samples audio data given a time variable signal.

Parameters:

  • time (Signal) –

    signal containing the values of the time variable at each sample point.

Returns:

  • Signal –

    The sampled signal of the waveform. The returned signal will be of the same shape as time. Each value in the returned signal is the sample of the waveform at the corresponding time value (in seconds) in time.

sample_seconds(duration: float = 1, sampling_rate: int = 44100, start_offset: float = 0, channels: int = 2) -> signal.Signal

Samples audio data given time information in seconds.

Parameters:

  • duration (float, default: 1 ) –

    the duration of time to be sampled in seconds.

  • sampling_rate (int, default: 44100 ) –

    the sampling rate to use in samples per second.

  • start_offset (float, default: 0 ) –

    the starting offset in seconds.

  • channels (int, default: 2 ) –

    the number of channels to return.

Returns:

  • Signal –

    The sampled signal of the waveform. The returned signal will have the shape (channels, ceil(sampling_rate*duration)), containing ceil(sampling_rate*duration) samples for each channel.

sample_samples(count: int | None = None, sampling_rate: int = 44100, start_offset: int = 0, channels: int = 2) -> signal.Signal

Samples audio data given sample count information.

Parameters:

  • count (int | None, default: None ) –

    the number of samples to take. If None, will be equal to sampling_rate.

  • sampling_rate (int, default: 44100 ) –

    the sampling rate to use in samples per second.

  • start_offset (int, default: 0 ) –

    the starting offset in samples.

  • channels (int, default: 2 ) –

    the number of channels to return.

Returns:

  • Signal –

    The sampled signal of the waveform. The returned signal will have the shape (channels, count), containing count samples for each channel.

OperationWaveform

Bases: Waveform

Waveform that is the result of an operation on other waveforms and numbers.

"lazily" samples audio by recursively sampling the operands as needed and applying the operator on the resulting audio data. The operands may be waveforms or scalar values.

Attributes:

  • operator –

    the operator to be called on the operand signals when this waveform is sampled.

  • operands –

    the operands whose signals are passed to operator when this waveform is sampled.

  • operator_kwargs –

    the keyword arguments this waveform passes to operator when sampled.

__init__(operator: Callable[..., Any], *operands: Waveform | float, **operator_kwargs: Any)

Initializes an operation waveform with operands and operator information.

Parameters:

  • operator (Callable[..., Any]) –

    the operator to use on the operand signals when the waveform is sampled. The operator should accept and return numerical array-like objects.

  • *operands (Waveform | float, default: () ) –

    operands whose signals are passed to operator when the waveform is sampled.

  • **operator_kwargs (Any, default: {} ) –

    keyword arguments to pass to operator when the waveform is sampled.

ResampleWaveform

Bases: Waveform

Waveform for resampling audio data.

Attributes:

  • time_multiplier –

    time/speed multiplier. Can be negative for reverse resampling.

  • loop –

    whether to replay the sample after it finishes.

original_audio: signal.Signal property writable

Signal containing the audio data to resample.

sampling_rate: int property writable

The original sampling rate of the audio data, in samples per second.

__init__(original_audio: signal.Signal, sampling_rate: int, time_multiplier: float = 1, loop: bool = False) -> None

Initializes a resample waveform with audio data.

Parameters:

  • original_audio (Signal) –

    signal containing the audio data to resample.

  • sampling_rate (int) –

    the original sampling rate of original_audio, in samples per second.

  • time_multiplier (float, default: 1 ) –

    time/speed multiplier. Can be negative for reverse resampling.

  • loop (bool, default: False ) –

    whether to replay the sample after it finishes.

full_repr() -> str

Returns the string representation including the audio data array in its entirety.

approx_equal(other: Any, absolute_tolerance: float = 1e-05, relative_tolerance: float = 1e-08) -> bool

Returns whether this waveform is approximately equal to another within a tolerence.

Parameters:

  • other (Any) –

    waveform to compare to.

  • absolute_tolerance (float, default: 1e-05 ) –

    the absolute tolerance of the comparison.

  • relative_tolerance (float, default: 1e-08 ) –

    the relative tolerance of the comparison.

PeriodicWave

Bases: Waveform

Periodic wave base class.

Attributes:

  • phase –

    initial phase offset of the periodic wave as a ratio of the period.

frequency: float property writable

Frequency of the periodic wave in Hz.

__init__(frequency: float, phase: float = 0)

Initializes a periodic wave.

Parameters:

  • frequency (float) –

    frequency of the periodic wave in Hz.

  • phase (float, default: 0 ) –

    initial phase offset of the periodic wave as a ratio of the period.

Sine

Bases: PeriodicWave

Waveform with a sine shape.

Sawtooth

Bases: PeriodicWave

Waveform with a sawtooth shape.

Pulse

Bases: PeriodicWave

Waveform with a pulse shape.

duty_cycle: float property writable

The fraction of one period in which the signal is high.

__init__(frequency: float, phase: float = 0, duty_cycle: float = 0.5) -> None

Initializes a pulse wave.

Parameters:

  • frequency (float) –

    frequency of the pulse wave in Hz.

  • phase (float, default: 0 ) –

    initial phase offset as a ratio of the period.

  • duty_cycle (float, default: 0.5 ) –

    the fraction of one period in which the signal is high.

Square

Bases: PeriodicWave

Waveform with a square shape.

Special case of a pulse wave where the duty cycle is equal to 0.5.

Triangle

Bases: PeriodicWave

Waveform with a triangle shape.

rising_part: float property writable

The fraction of one period in which the signal is rising.

__init__(frequency: float, phase: float = 0, rising_part: float = 0.5) -> None

Initializes a triangle wave.

Parameters:

  • frequency (float) –

    frequency of the square wave in Hz.

  • phase (float, default: 0 ) –

    initial phase offset as a ratio of the period.

  • rising_part (float, default: 0.5 ) –

    the fraction of one period in which the signal is rising.

PhaseModulation

Bases: Waveform

Modulates a periodic wave's phase by another waveform's amplitude.

Attributes:

  • modulator –

    the modulator waveform.

carrier: periodic_waves.PeriodicWave property writable

The periodic carrier of the modulation.

__init__(carrier: periodic_waves.PeriodicWave, modulator: waveform.Waveform) -> None

Initializes a phase modulation waveform.

Parameters:

  • carrier (PeriodicWave) –

    the periodic wave whose phase will be modulated.

  • modulator (Waveform) –

    the waveform used for the modulation.

phase_modulate(carrier: periodic_waves.PeriodicWave, *modulators: waveform.Waveform) -> waveform.Waveform

Returns a waveform resulting from phase modulation.

The carrier's phase is shifted according to the amplitude of the sum of the modulators.

Parameters:

  • carrier (PeriodicWave) –

    the periodic carrier waveform.

  • *modulators (Waveform, default: () ) –

    any number of modulator waveforms.

amplitude_modulate(carrier: waveform.Waveform, *modulators: waveform.Waveform) -> waveform.Waveform

Returns a waveform resulting from amplitude modulation.

The carrier's amplitude is shifted according to the amplitude of the sum of the modulators.

Parameters:

  • carrier (Waveform) –

    the carrier waveform.

  • *modulators (Waveform, default: () ) –

    any number of modulator waveforms.

ring_modulate(carrier: waveform.Waveform, *modulators: waveform.Waveform) -> waveform.Waveform

Returns a waveform resulting from ring modulation.

The carrier's amplitude is multiplied by the amplitude of the product of the modulators.

Parameters:

  • carrier (Waveform) –

    the carrier waveform.

  • *modulators (Waveform, default: () ) –

    any number of modulator waveforms.

glyphtune.waveforms.effects

Waveforms that are effects that can be applied on other waveforms.

Effect

Bases: Waveform

Base class representing effects.

Attributes:

  • input_waveform –

    the input waveform of the effect.

mix: float property writable

Proportional multiplier of the effect's wet signal.

The effect's wet signal will be multiplied by this value (therefore negative values mean inverted effect output). The dry signal will be multiplied by 1-abs(mix).

__init__(input_waveform: waveform.Waveform, mix: float = 0.5) -> None

Initializes an effect.

Parameters:

  • input_waveform (Waveform) –

    the input waveform of the effect.

  • mix (float, default: 0.5 ) –

    multiplier of the wet signal. The dry signal will be multiplied by 1-abs(mix).

sample_dry_wet(time: signal.Signal) -> tuple[signal.Signal, signal.Signal]

Samples the dry and wet signals of the effect given a time variable signal.

Parameters:

  • time (Signal) –

    signal containing the values of the time variable at each sample point.

Returns:

  • tuple[Signal, Signal] –

    A tuple (dry_signal, wet_signal). Both dry_signal and wet_signal are of the same shape as time. dry_signal contains the signal of the input waveform without applying the effect, and wet_signal contains the signal of the applied effect.

apply(input_signal: signal.Signal) -> signal.Signal

Applies the effect on the given input signal.

Effects that can generate output by simply altering the input audio should only have to implement this method. Effects that deal with more complex time-related manipulation should instead override sample_dry_wet and may just raise NotImplementedError in apply.

Parameters:

  • input_signal (Signal) –

    input signal of the effect.

Returns:

  • Signal –

    The wet signal of the effect after being applied on input_signal. The returned signal will be of the same shape as input_signal.

StereoPan

Bases: Effect

Stereo pan effect.

pan: float property writable

Stereo pan value in the range [-1, 1] i.e., from entirely left to entirely right.

__init__(input_waveform: waveform.Waveform, pan: float = 0, mix: float = 1) -> None

Initializes a stereo pan effect.

Parameters:

  • input_waveform (Waveform) –

    the input waveform of the effect.

  • pan (float, default: 0 ) –

    stereo pan value in the range [-1, 1] i.e., from entirely left to entirely right.

  • mix (float, default: 1 ) –

    multiplier of the wet signal. The dry signal will be multiplied by 1-abs(mix).

StereoLevels

Bases: Effect

An effect for setting each stereo channel's level independently.

Attributes:

  • left_level –

    the level of the left channel.

  • right_level –

    the level of the right channel.

__init__(input_waveform: waveform.Waveform, left_level: float = 1, right_level: float = 1, mix: float = 1) -> None

Initializes a stereo levels effect.

Parameters:

  • input_waveform (Waveform) –

    the input waveform of the effect.

  • left_level (float, default: 1 ) –

    the level of the left channel.

  • right_level (float, default: 1 ) –

    the level of the right channel.

  • mix (float, default: 1 ) –

    multiplier of the wet signal. The dry signal will be multiplied by 1-abs(mix).

StereoInterMix

Bases: Effect

An effect that sends signal from the left channel to the right channel and vice versa.

Attributes:

  • right_to_left –

    how much of the right channel to send to the left channel.

  • left_to_right –

    how much of the left channel to send to the right channel.

__init__(input_waveform: waveform.Waveform, right_to_left: float = 1, left_to_right: float = 1, mix: float = 0.5) -> None

Initializes a stereo inter-mix effect.

Parameters:

  • input_waveform (Waveform) –

    the input waveform of the effect.

  • right_to_left (float, default: 1 ) –

    how much of the right channel to send to the left channel.

  • left_to_right (float, default: 1 ) –

    how much of the left channel to send to the right channel.

  • mix (float, default: 0.5 ) –

    multiplier of the wet signal. The dry signal will be multiplied by 1-abs(mix).

StereoDelay

Bases: Effect

An effect that introduces a delay between the left and right channels (Haas effect).

Attributes:

  • left_right_delay –

    the delay between the left and right channels in seconds. A positive value means that the right channel's signal is delayed, and a negative value means that the left channel's signal is delayed.

__init__(input_waveform: waveform.Waveform, left_right_delay: float = 0, mix: float = 1) -> None

Initializes a stereo delay effect.

Parameters:

  • input_waveform (Waveform) –

    the input waveform of the effect.

  • left_right_delay (float, default: 0 ) –

    the delay between the left and right channels in seconds. A positive value means that the right channel's signal is delayed, and a negative value means that the left channel's signal is delayed.

  • mix (float, default: 1 ) –

    multiplier of the wet signal. The dry signal will be multiplied by 1-abs(mix).

glyphtune.io

Audio I/O.

StreamParameters dataclass

Parameters used in audio stream I/O.

Attributes:

  • channels (int) –

    number of channels.

  • sampling_rate (int) –

    the sampling rate in samples per second.

  • buffer_size (int) –

    the size of chunks to be streamed in samples.

StreamHandler

Abstract class for handling reading and writing to audio streams.

Attributes:

  • stream_parameters –

    audio I/O stream parameters.

read(size: int) -> bytes

Returns audio data bytes from the stream.

Parameters:

  • size (int) –

    the number of frames to read.

write(data: bytes, size: int) -> None

Writes audio data bytes to the stream.

Parameters:

  • data (bytes) –

    data to write.

  • size (int) –

    the number of frames to write.

close() -> None

Closes the stream.

PyAudioHandler

Bases: StreamHandler

A stream handler using PyAudio.

FileParameters dataclass

Parameters used in audio file I/O.

Attributes:

  • channels (int) –

    number of channels.

  • sample_width (int) –

    the sample width in bytes.

  • sampling_rate (int) –

    the sampling rate in samples per second.

FileHandler

Abstract class for handling reading and writing an audio file format.

Attributes:

  • path –

    the path of the file being handled.

read() -> tuple[FileParameters, bytes]

Reads an audio file.

Returns a tuple (parameters, read_signal) containing metadata and data read from the file.

write(parameters: FileParameters, data: bytes) -> None

Writes an audio file.

Parameters:

  • parameters (FileParameters) –

    file I/O parameters.

  • data (bytes) –

    audio bytes to write.

WavHandler

Bases: FileHandler

A file handler for uncompressed wav files in integer format.

record(duration: float = np.inf, stream_parameters: StreamParameters = StreamParameters(1), handler_type: type[StreamHandler] = PyAudioHandler) -> signal.Signal

Returns signal of recorded audio input.

Parameters:

  • duration (float, default: inf ) –

    the duration of time to record input, in seconds. If set to infinity, recording will continue until interrupted. Note that the recording may last longer than the specified duration until the last buffer is over. This is more noticeable with a large buffer_size.

  • stream_parameters (StreamParameters, default: StreamParameters(1) ) –

    the stream parameters to use.

  • handler_type (type[StreamHandler], default: PyAudioHandler ) –

    subclass of StreamHandler that can handle audio stream I/O.

record_resample(duration: float = np.inf, stream_parameters: StreamParameters = StreamParameters(1), handler_type: type[StreamHandler] = PyAudioHandler) -> waveforms.ResampleWaveform

Returns a waveform that resamples the recorded audio input.

Parameters:

  • duration (float, default: inf ) –

    the duration of time to record input, in seconds. If set to infinity, recording will continue until interrupted. Note that the recording may last longer than the specified duration until the last buffer is over. This is more noticeable with a large buffer_size.

  • stream_parameters (StreamParameters, default: StreamParameters(1) ) –

    the stream parameters to use.

  • handler_type (type[StreamHandler], default: PyAudioHandler ) –

    subclass of StreamHandler that can handle audio stream I/O.

play(waveform: waveforms.Waveform, duration: float = np.inf, stream_parameters: StreamParameters = StreamParameters(), start_offset: float = 0, handler_type: type[StreamHandler] = PyAudioHandler) -> None

Samples and streams a waveform's output.

Parameters:

  • waveform (Waveform) –

    waveform to be streamed.

  • duration (float, default: inf ) –

    the duration of time to sample the waveform for output, in seconds. If set to infinity, playback will continue until interrupted. Note that the playback may last longer than the specified duration until the last buffer is over. This is more noticeable with a large buffer_size.

  • start_offset (float, default: 0 ) –

    the starting offset with which to sample the waveform for output, in seconds.

  • stream_parameters (StreamParameters, default: StreamParameters() ) –

    the stream parameters to use.

  • handler_type (type[StreamHandler], default: PyAudioHandler ) –

    subclass of StreamHandler that can handle audio stream I/O.

read(path: pathlib.Path | str, handler_type: type[FileHandler] | None = None) -> tuple[FileParameters, signal.Signal]

Reads an audio file.

Parameters:

  • path (Path | str) –

    the path of the input file.

  • handler_type (type[FileHandler] | None, default: None ) –

    subclass of FileHandler that can handle the format of the input file. If None, an attempt will be made to find the right handler type from the file extension.

Returns:

  • tuple[FileParameters, Signal] –

    A tuple (parameters, read_signal) containing metadata and data read from the file.

read_resample(path: pathlib.Path | str, handler_type: type[FileHandler] | None = None) -> waveforms.ResampleWaveform

Reads an aduio file into a resample waveform.

Parameters:

  • path (Path | str) –

    the path of the input file.

  • handler_type (type[FileHandler] | None, default: None ) –

    subclass of FileHandler that can handle the format of the input file. If None, an attempt will be made to find the right handler type from the file extension.

Returns:

write(waveform: waveforms.Waveform, path: pathlib.Path | str, duration: float, parameters: FileParameters, start_offset: float = 0, handler_type: type[FileHandler] | None = None) -> None

Writes waveform to file.

Parameters:

  • waveform (Waveform) –

    the waveform to write.

  • path (Path | str) –

    the path of the output file.

  • duration (float) –

    the duration of time to sample the waveform for output, in seconds.

  • start_offset (float, default: 0 ) –

    the starting offset with which to sample the waveform for output, in seconds.

  • parameters (FileParameters) –

    file I/O parameters.

  • handler_type (type[FileHandler] | None, default: None ) –

    subclass of FileHandler that can handle the format of the input file. If None, an attempt will be made to find the right handler type from the file extension.