chaudio.instruments

Instruments (chaudio.instruments)

Support for instrument plugins that can play notes, MIDI data, and other formats

Classes

ADSREnvelope([A, D, S, R])	This is an ADSR envelope.
Instrument(**kwargs)	Base class to extend if you have an instrument
LFO([waveform, hz, tweak, amp, dc_shift, …])
MultiOscillator(osc, **kwargs)	Similar to LMMS’s triple oscillator (which itself was based on minimoog synth), but with a variable number
MultiSampler([sampler_dict])
Oscillator([waveform, amp, amp_env, …])	Represents a basic oscillator, which is the base class for most synths
Sampler(**kwargs)

class chaudio.instruments.Instrument(**kwargs)

Base class to extend if you have an instrument

__init__(**kwargs)

Initializes an Instrument (which is a base class that should not be used, please use chaudio.instruments.Oscillator or another class!)

Parameters:**kwargs ((key word arguments)) – The generic instrument arguments Returns:A generic instrument object Return type:chaudio.instruments.Instrument

raw_note(**kwargs)

Returns raw note source (i.e. without plugins added)

MOST PEOPLE SHOULD NOT NEED THIS FUNCTION!

Please use the chaudio.instruments.Instrument.note() function for external needs, as this method is used internally there, and then plugins are applied.

This method is not implemented in this base (i.e. chaudio.instruments.Instrument) class, but should be implemented by any actual instrument.

Parameters:**kwargs ((key word arguments)) – The generic instrument arguments Returns:A source representing the raw note of the instrument (without plugins). Return type:chaudio.source.Stereo

note(**kwargs)

Returns raw note source with all plugins applied

The freq argument is specified as the actual note being played. So, to play an A, use instrument.note(freq="A", ...)

Parameters:**kwargs ((key word arguments)) – The generic instrument arguments (use freq for the note value) Returns:A source representing instrument playing a note Return type:chaudio.source.Stereo

add_plugin(plugin)

Adds a processing plugin

Parameters:plugin (chaudio.plugins.Basic) – Plugin object that extends Basic

remove_plugin(plugin)

Removes a plugin, by the plugin object, or the index

Parameters:plugin (chaudio.plugins.Basic or int) – Plugin object that extends Basic, or index

copy()

Returns a copy of the object

Returns:A copy of the object. Keeps the same type, however Return type:chaudio.instruments.Instrument (or whatever class the object is)

merged_kwargs(specific_kwargs, exclude=[])

Returns the merged kwargs (i.e. the input replaces values not specified as defaults.) and then remove exclude vals.

Parameters:

• specific_kwargs (dict) – What was passed to the specific function (like chaudio.instruments.Instrument.note()) that needs to override the initialiezd kwargs.
• exclude (list, tuple) – Which arguments to remove (i.e. exclude) from the result

Returns:

The merged results, with anything from specific_kwargs taking precedence over the defaults, then remove all from exclude

Return type:

dict

__getitem__(key)

Returns the configuration/kwargs value at a specified key

Parameters:key (obj) – Whatever key the value was stored as (typically str) Returns:The value stored as a kwarg Return type:obj

__setitem__(key, val)

Sets the configuration/kwargs value at a specified key to a provided value

Parameters:

• key (obj) – Whatever key the value was stored as (typically str)
• val (obj) – What value to set at key

__weakref__

list of weak references to the object (if defined)

class chaudio.instruments.ADSREnvelope(A=0, D=0, S=1, R=0)

This is an ADSR envelope.

For a good explanation, see ADSR Envelope one wikiaudio.

__init__(A=0, D=0, S=1, R=0)

Initializes the envelope with common parameters.

Parameters:

• A (float) – ‘attack’ value, in seconds. Essentially the envelope is ramping up until A seconds
• D (float) – ‘decay’ value, in seconds. The envelope will scale gently to S between time A and A + D seconds.
• S (float) – ‘sustain’ value, as an amplitude between 0.0 and 1.0. This is the value that the envelope holds between A + D and t - R seconds (where t is the length of the segment that is being enveloped).
• R (float) – ‘release’, value in seconds. This is the time (from the end of the time values being enveloped) that the ADSR envelope starts fading out.

calc_val(t, **kwargs)

Returns the envelope values for a time sample array.

This returns the values (which are all 0.0 to 1.0) of the envelope, applied over the times given in t. The result has the same length as t, so that you can apply operations to t and others. See the examples below. This is used in chaudio.instruments.Oscillator.

Parameters:

• t (np.ndarray) – The value of time samples. These are generated (typically) using the chaudio.util.times() method.
• kwargs ((key word args)) – These can override A, D, S, or R for a specific call to this function without forever replacing the defaults.

Returns:

A result with the same length as t (so you can do operations with them).

Return type:

np.ndarray

Examples

>>> t = chaudio.util.times(4)
>>> wave = chaudio.waves.triangle(t, hz=220)
>>> env = chaudio.instruments.ADSREnvelope(A=.4, D=1.0, S=.4, R=.8)
>>> y = wave * env.calc_val(t)
>>> # y now contains the wave with the envelope value
>>> chaudio.play(y)

__weakref__

list of weak references to the object (if defined)

class chaudio.instruments.Oscillator(waveform=<function sin>, amp=1.0, amp_env=<chaudio.instruments.ADSREnvelope object>, amp_lfo=<chaudio.instruments.LFO object>, samplerate=None, phase_shift=0, freq_shift=0, freq_lfo=<chaudio.instruments.LFO object>, tweak=None, tweak_lfo=<chaudio.instruments.LFO object>, pan=0, **kwargs)

Represents a basic oscillator, which is the base class for most synths

__init__(waveform=<function sin>, amp=1.0, amp_env=<chaudio.instruments.ADSREnvelope object>, amp_lfo=<chaudio.instruments.LFO object>, samplerate=None, phase_shift=0, freq_shift=0, freq_lfo=<chaudio.instruments.LFO object>, tweak=None, tweak_lfo=<chaudio.instruments.LFO object>, pan=0, **kwargs)

Initializes an oscillator, given waveform and a host of other parameters

Keep in all parameters can be overriden in individual calls to the chaudio.instruments.Oscillator.note() function. So, to override the phase_shift for a single note, run like ``osc.note(“A4”, phase_shift=2) to temporarily override the initialized parameter.

To change the values you initialized with, set like so: osc["phase_shift"] = 2

Parameters that accept a tuple and dict (such as phase_shift) mean that it can accept left and right values that differ. So, the left channel has a different phase offset than the right side. If you give a tuple for these values, v[0] is for the left and v[1] is for the right. If given a dict, v["left"] is for the left and v["right"] is for the right. And remember, all parameters accept a single value as a float/int/None, in which the left and right values are both taken as v.

Parameters:

• waveform (func) – What internal waveform to generate sounds based on. See module chaudio.waves for a list of defaults included with chaudio, as well as their function.
• amp (float, int) – the amplitude of the waveform. This is useful when combining multiple oscillators (see chaudio.instruments.MultiOscillator for example on this).
• samplerate (int, None) – What is the samplerate that should be used
• phase_shift (float, tuple, dict) – The offset in the wavefunction. A phase shift of 0 means use the default waveform function. A phase shift of .5 means begin halfway through the first oscillation.
• freq_shift (float, tuple, dict) – The offset, in cents, that the oscillator transposes given notes to. Essentially, if given freq to play, the returned source containing data is the note freq transposed freq_shift cents.
• tweak (float, None, tuple, dict) – The tweak value to apply on the waveform.
• pan (float, None) – A panning (Left/Right) value to change the offset in the stereo space. -1.0 representing all the way left, +1.0 representing all the way right.

Returns:

The instrument object

Return type:

chaudio.instruments.Oscillator

raw_note(**kwargs)

Returns the result of the instrument performing a note for specified parameters

Basic usage is osc.note(freq="A4", amp=.5, ...) and that overrides the amp value set on creation.

You can permanently update these values with osc["amp"] = .5 to update the default used if nothing is passed into the note function.

Parameters:

• freq (int, float, str, np.ndarray) – This can be a frequency directly, or a string of a note name (see chaudio.util.note() for what is suppoerted). Additionally, it can be an array of frequencies at time values. Note that this should contain data with the sameplerate as the oscillator. You can check the oscillator sample rate with: osc["samplerate"]. As a consequence, it also needs to be the same shape as the time parameter t generated array
• kwargs ((key word args)) – These are all values that can override the default values (which all are documented in the chaudio.instruments.Oscillator.__init__() method).

Returns:

The source representing the oscillator playing the note

Return type:

chaudio.source.Stereo

class chaudio.instruments.MultiOscillator(osc, **kwargs)

Similar to LMMS’s triple oscillator (which itself was based on minimoog synth), but with a variable number

__init__(osc, **kwargs)

Returns an instrument multiplexor with oscillators

Parameters:

• osc (list, tuple, None) – The group of oscillators. These are all the oscillators that are played each time you ask for a note. You can change oscillators after construction using the chaudio.instruments.MultiOscillator.add_osc() and chaudio.instruments.MultiOscillator.remove_osc() methods.
• kwargs ((key word args)) – These are all values that can override the default values (which all are documented in the chaudio.instruments.Oscillator.__init__() method).

Returns:

The multioscillator representing the oscillators playing the note

Return type:

chaudio.instruments.MultiOscillator