chaudio.util package¶
Submodules¶
Module contents¶
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.
-
chaudio.util.
times
(t, hz=None)[source]¶ Returns time sample values
Returns an np.ndarray of time values representing points taken for
t
seconds, at sampleratehz
.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 (ifhz
isNone
), 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 lastingt
(or value derived fromt
) seconds.Return type: np.ndarray
- 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
-
class
chaudio.util.
Chunker
(audio, n=8192, hop=None)[source]¶ Bases:
object
-
__dict__
= mappingproxy({'__getitem__': <function Chunker.__getitem__>, 'recombo': <function Chunker.recombo>, 'chunk': <function Chunker.chunk>, 'chunk_time_offset': <function Chunker.chunk_time_offset>, 'chunk_time': <function Chunker.chunk_time>, '__weakref__': <attribute '__weakref__' of 'Chunker' objects>, '__dict__': <attribute '__dict__' of 'Chunker' objects>, '__init__': <function Chunker.__init__>, '__doc__': None, '__module__': 'chaudio.util', '__len__': <function Chunker.__len__>, 'chunks': <function Chunker.chunks>})¶
-
__module__
= 'chaudio.util'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
chaudio.util.
FFTChunker
(audio, n=8192, hop=None)[source]¶ Bases:
chaudio.util.Chunker
-
__module__
= 'chaudio.util'¶
-
-
chaudio.util.
transpose
(hz, val, use_cents=True)[source]¶ Transposes a frequency value by a number of cents or semitones
Note that if both
hz
andval
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 transposehz
. 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 byval
Return type: float
-
chaudio.util.
cents
(hz)[source]¶ 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)[source]¶ Frequency (in hz) of the note as indicated by
name
name
should begin with a note name (likeA
,B
,C
, … ,G
), then optionally a#
orb
reflecting a sharp or flat (respectively) tone, and finally an optional octave number (starting with0
up to8
).If no octave number is given, it defaults to
4
.Parameters: name (str) – String representation of a note, like A
orC#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)[source]¶ Ensures the input is returned as a dictionary object with right and left specifiers
If
val
is a dictionary, look forleft
orright
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, assumval[0]
is the left value andval[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, aValueException
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)[source]¶ The factor needed to scale
v
in order to normalize to [-1.0, +1.0] rangeIn 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)[source]¶ Return a scaled version of
v
in the [-1.0, +1.0] rangeNormalize
v
such that all values are scaled by the same linear factor, and \(-1.0 <= k <= +1.0\) for all valuesk
inv
. 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] rangeReturn type: chaudio.source.Source or np.ndarray
-
class
chaudio.util.
TimeSignature
(beats, division, bpm=60)[source]¶ Bases:
object
Represents a time signature.
-
__init__
(beats, division, bpm=60)[source]¶ 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)[source]¶ 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 totsig[key]
)If
key
is a tuple, return the number of seconds that is equivalant tokey[0]
measures, andkey[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
-
__repr__
()¶
-
__dict__
= mappingproxy({'copy': <function TimeSignature.copy>, '__getitem__': <function TimeSignature.__getitem__>, '__repr__': <function TimeSignature.__str__>, '__doc__': '\n\n Represents a `time signature <https://en.wikipedia.org/wiki/Time_signature>`_.\n\n ', '__str__': <function TimeSignature.__str__>, '__dict__': <attribute '__dict__' of 'TimeSignature' objects>, '__init__': <function TimeSignature.__init__>, '__module__': 'chaudio.util', '__weakref__': <attribute '__weakref__' of 'TimeSignature' objects>})¶
-
__module__
= 'chaudio.util'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
chaudio.util.
glissando_freq
(sfreq, efreq, t, discrete=False)[source]¶ 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