chaudio.util

Utility Functions (chaudio.util)

This module provides useful utilities and classes to be used elsewhere. Note that most of these functions are aliased directly to the main chaudio module. Ones that are not aliased are often lower level and may not support all input types.

Functions

cents(hz)	Returns the number of cents (off of 1hz)
concatenate(data)
ensure_lr_dict(val)	Ensures the input is returned as a dictionary object with right and left specifiers
fft_phase(fft_domain)
glissando_freq(sfreq, efreq, t[, discrete])	Returns an array of frequencies of a glissando starting at sfreq and ending at efreq
hz(cents)
lambda_mask(data, qualifier)
map_domain(domain, chunk, conversion_lambda)
normalize(v)	Return a scaled version of v in the [-1.0, +1.0] range
normalize_factor(v)	The factor needed to scale v in order to normalize to [-1.0, +1.0] range
note(name)	Frequency (in hz) of the note as indicated by name
sumdup(key, val)	sums duplicates
times(t[, hz])	Returns time sample values
transpose(hz, val[, use_cents])	Transposes a frequency value by a number of cents or semitones

Classes

Chunker(audio[, n, hop])
FFTChunker(audio[, n, hop])
TimeSignature(beats, division[, bpm])	Represents a time signature.

chaudio.util.times(t, hz=None)

Returns time sample values

Returns an np.ndarray of time values representing points taken for t seconds, at samplerate hz.

The length of the resulting object is t * hz

Parameters:

• t (float, int, np.ndarray, chaudio.source.Source) – If float or int, it represents the number of seconds to generate time sample values for. If a numpy ndarray, it assumes the number of seconds is len(t)/hz. If it is a chaudio.source.Source, it gets the number of seconds and sample rate (if hz is None), and uses those.
• hz (float, int) – The sample rate (samples per second)

Returns:

An array of time sample values, taken at hz samples per second, and lasting t (or value derived from t) seconds.

Return type:

np.ndarray

chaudio.util.sumdup(key, val)

sums duplicates

chaudio.util.transpose(hz, val, use_cents=True)

Transposes a frequency value by a number of cents or semitones

Note that if both hz and val are np arrays, their shapes must be equivalent.

When, use_cents==True The effects are thus: +1200 val results in a shift up one octave, -1200 is a shift down one octave.

When, use_cents==False The effects are thus: +12 val results in a shift up one octave, -12 is a shift down one octave.

Parameters:

• hz (float, int, np.ndarray) – Frequency, in oscillations per second
• val (float, int, np.ndarray) – The number of cents (or semitones if use_cents==False) to transpose hz. It can be positive or negative.
• use_cents=True (bool) – Whether or not use use cents or semitones

Returns:

Frequency, in hz, of hz shifted by val

Return type:

float

chaudio.util.cents(hz)

Returns the number of cents (off of 1hz)

Parameters:hz (float, int, np.ndarray) – Frequency, in oscillations per second Returns:Cents off of 1 hz Return type:float, np.ndarray

chaudio.util.note(name)

Frequency (in hz) of the note as indicated by name

name should begin with a note name (like A, B, C, … , G), then optionally a # or b reflecting a sharp or flat (respectively) tone, and finally an optional octave number (starting with 0 up to 8).

If no octave number is given, it defaults to 4.

Parameters:name (str) – String representation of a note, like A or C#5 Returns:Frequency, in hz, of the note described by name Return type:float

Examples

>>> chaudio.note("A")
440.0
>>> chaudio.note("A5")
880.0
>>> chaudio.note("A#5")
932.327523
>>> chaudio.note("TESTING7")
ValueError: invalid note name: TESTING

chaudio.util.ensure_lr_dict(val)

Ensures the input is returned as a dictionary object with right and left specifiers

If val is a dictionary, look for left or right keys. If both exist, return those as a new dictionary. If only one exists, assume that value stands for both sides.

If val is a tuple/list, and it has 1 value, assume that is for both left and right. If it has length of 2, assum val[0] is the left value and val[1] is right.

Else, assume the single val is the value for left and right, i.e. there is no difference between the two sides.

If val does not fit these rules, a ValueException is raised.

Parameters:val (any) – value to be ensured as a left/right dictionary Returns:Value with keys ‘left’ and ‘right’, determined by the input value Return type:dict

chaudio.util.normalize_factor(v)

The factor needed to scale v in order to normalize to [-1.0, +1.0] range

In the case that v is a chaudio.source.Source, return the highest of any sample in any channel.

Parameters:v (chaudio.source.Source or np.ndarray) – The collection of amplitudes Returns:The highest maximum amplitude of the absolute value of v Return type:float

chaudio.util.normalize(v)

Return a scaled version of v in the [-1.0, +1.0] range

Normalize v such that all values are scaled by the same linear factor, and \(-1.0 <= k <= +1.0\) for all values k in v. If given a chaudio.source.Source, all channels are scaled by the same factor (so that the channels will still be even).

Parameters:v (chaudio.source.Source or np.ndarray) – The source being normalized Returns:v such that all amplitudes have been scaled to fit inside the [-1.0, +1.0] range Return type:chaudio.source.Source or np.ndarray

class chaudio.util.TimeSignature(beats, division, bpm=60)

Represents a time signature.

__init__(beats, division, bpm=60)

TimeSignature creation routine

Return a time signature representing measures each with beats beats (or pulses).

The note represented as division getting a single beat.

If division is 4, the quarter note gets the beat, 8 means the 8th note gets the beat, and so on.

Parameters:

• v (chaudio.source.Source or np.ndarray) – The source being normalized
• beats (int, float) – Number of beats (or pulses) per measure
• division (int, float) – Note division that represents a single pulse
• bpm (int, optional) – The speed, in beats per minute

__getitem__(key)

Returns the time in seconds of a number of beats, or a number of measures and beats.

(this method is an alias for subscripting, so tsig.__getitem__(key) is equivelant to tsig[key])

If key is a tuple, return the number of seconds that is equivalant to key[0] measures, and key[1] beats.

In all cases, tsig[a] == tsig[a//tsig.beats, a%tsig.beats].

When calling using a key that is a tuple, key[1] must not exceed the number of beats. This is to prevent errors arising from improper lengths. However, the number of beats can be any non-negative value if using a key that is a float or int.

Parameters:key (int, float, tuple) – Either a tuple containing (measure, beat), or a number of beats Returns:The amount of time that key represents (in seconds) Return type:float

__weakref__

list of weak references to the object (if defined)

chaudio.util.glissando_freq(sfreq, efreq, t, discrete=False)

Returns an array of frequencies of a glissando starting at sfreq and ending at efreq

Parameters:

• sfreq (float) – Frequency at the start of the time array
• efreq (float) – Frequency at the end of the time array
• t (np.ndarray) – Array of time sample values
• discrete (bool) – Default=False, but if true, they are truncated to note values

Returns:

Array of frequencies in corresponding to t

Return type:

np.ndarray