API reference

Every name below is re-exported from the top level: music.note(...) works regardless of which submodule defines it.

Synthesis

Notes

Each returns a numpy array of PCM samples. note is the plain wavetable lookup, as MASS specifies it; the rest layer vibrato, pitch transitions, frequency modulation and movement onto it.

note	Synthesize a basic musical note.
note_with_phase	Synthesize a basic musical note with a phase.
note_with_vibrato	Synthesize a musical note with a vibrato.
note_with_two_vibratos	A note with a vibrato that also has a secondary oscillatory pattern.
note_with_glissando	A note with a pitch transition: a glissando.
note_with_glissando_vibrato	A note with a pitch transition (a glissando) and a vibrato.
note_with_two_vibratos_glissando	A note with a glissando and a vibrato that also has a secondary oscillatory pattern.
note_with_vibratos_glissandos	A note with an arbitrary sequence of pitch transition and a meta-vibrato.
note_with_vibrato_seq_localization	A sound with arbitrary meta-vibratos, transitions of frequency and localization.
note_with_fm	Synthesize a musical note with FM synthesis.
note_with_doppler	A simple note with a transition of localization and resulting Doppler effect.
trill	Makes a trill.

Band-limited rendering

bandlimited_note renders a fixed pitch without the partials above the Nyquist frequency that note folds back into the band, and render_oversampled renders any generator at a multiple of the rate and filters it, for the folding a table cannot prevent. Band-limited synthesis describes both, with the oscillators for a pitch that moves.

bandlimited_note	Render a static-pitch periodic note with prefiltered harmonics.
render_oversampled	Render at a higher sampling rate, low-pass, then downsample.

Sensory stimulation

Stimuli for sensory-stimulation work, each rendering one technique catalogued in SSTIM, the Sensory Stimulation Vocabulary. Every docstring names the SSTIM term it implements and states whether the modulation is physically present in the signal or constructed by the listener.

binaural_beats	Synthesize a binaural beat: sstim-v:techBinauralBeats.
monaural_beats	Synthesize a monaural beat: sstim-v:techMonauralBeats.
isochronic_tones	Synthesize an isochronic tone train: sstim-v:techIsochronicTones.
amplitude_modulation	Sinusoidally modulate a carrier: sstim-v:techAmplitudeModulation.
frequency_modulation	Sweep a carrier's pitch: sstim-v:techFrequencyModulation.
modulated_noise	Modulate a band of noise: sstim-v:techBroadbandNoise.
spatial_motion	Orbit a source around the listener: sstim-v:techSpatialAuditory.

A protocol is a sequence of those rather than one of them. StimulationSession holds that sequence and renders it as one sound, joining the phases with crossfades centred on their boundaries so that the session lasts exactly the sum of the durations it was given.

StimulationSession	A sequence of stimuli rendered as one sound.
StimulusPhase	One phase of a session: a stimulus, for a while, ramped into.

Envelopes and noise

am	Synthesize an AM envelope or apply it to a sound.
tremolo	Synthesize a tremolo envelope or apply it to a sound.
tremolos	An envelope with multiple tremolos.
noise	Return a colored or user-refined noise.
gaussian_noise	Synth gaussian noise
silence	Generate a silence of specified length.

Filters

Amplitude

adsr	Synthesize an ADSR envelope.
adsr_stereo	A shorthand to make an ADSR envelope for a stereo sound.
adsr_vibrato	Creates a note with a vibrato and an ADSR envelope.
fade	A fade in or out.
cross_fade	Cross fade two sounds over duration milliseconds.
loud	An envelope for a linear or exponential transition of amplitude.
louds	An envelope with linear or exponential transitions of amplitude.

Spectral and spatial

fir	Apply a FIR filter to a sonic_array.
iir	Apply an IIR filter to a signal.
reverb	Apply an artificial reverberation or return the impulse response.
localize	Make a mono sound stereo and localize it by a very naive method.
localize2	Make a mono sound stereo and localize it by experimental methods.
localize_linear	Localize a sound along a straight path between two angles.
localize_hrtf	Place a mono sound with a measured pair of impulse responses.
stretches	Makes a sequence of squeezes of the fragment in x.

Head-related transfer functions

localize_hrtf applies a pair of impulse responses; these are where a measured pair comes from. The package ships none: setup_hrtf fetches the KEMAR measurements into the user’s cache, once, and hrir reads one direction out of them.

setup_hrtf	Fetch the KEMAR measurements into the cache, once.
hrir	The impulse responses measured nearest to one direction.
available_azimuths	The azimuths measured at one elevation, in this package's convention.
hrtf_dir	Where the measurements are, or would go.

Filter design

iir applies coefficients; these compute them, from the four designs the MASS article specifies. Cutoff, centre and bandwidth are fractions of the sample rate, which fraction_of converts a frequency in Hertz into.

low_pass	A one-pole low pass, from the article's equation eq:passa-baixas.
high_pass	A one-pole high pass, from the article's equation eq:passa-altas.
band_pass	A two-pole band pass, from the article's eq:passa-banda.
band_reject	A two-pole notch, from the article's eq:rejeita-banda.
fraction_of	A frequency in Hertz, as the fraction of the sample rate a design wants.

Input and output

read_audio	Read an audio file and return an array of its values.
read_wav	The name read_audio() had before it read anything but WAV.
write_audio	Write a sound to a file, mono or stereo, WAV or FLAC.
write_wav_mono	Writes a mono WAV file for a numpy array.
write_wav_stereo	Write a stereo WAV files for a numpy array.
play_audio	Play a sonic vector using the sounddevice library.
normalize_mono	Normalize a mono sonic vector.
normalize_stereo	Normalize a stereo sonic vector.

Sequencing

Sequencer

Schedules notes and renders them as audio.

Musical structures

Permutations, algebraic groups and change-ringing peals.

InterestingPermutations	Get permutations of n elements in meaningful sequences.
transpose_permutation	Shifts a permutation up or down by step positions.
dist	Computes the cyclic distance between the two elements of a permutation.
GenericPeal	A collection of named peals that can be acted on a domain.
Peals	Uses permutations to make peals and represents peals as permutations.
PlainChanges	Presents plain changes as swaps and acts in domains to make peals.
print_peal	Prints a peal with colored numbers.

Music theory

Scales, chords and the harmonic series, counted in semitones from a tonic or root of zero – which is what pitch_to_freq takes, so any of these becomes frequencies and then sound in two steps.

scale	The semitones of a named scale, counted from tonic.
mode_by_rotation	A diatonic mode, built by rotating the steps as eq:relacaoDia does.
harmonic_series	The first partials harmonics, in semitones above the fundamental.
chord	The semitones of a named chord, counted from root.
add_seventh	One more third on top of a triad.
invert	Move one note of a chord by whole octaves.
interval	The number of semitones in an interval, from its traditional name.
interval_names	Every traditional name for an interval of this many semitones.
interval_between	The interval in semitones between two frequencies, rounded.
consonance	How the article classifies an interval.

The tables these read from are exported too: SCALES, MODES, MINOR_SCALES and DIATONIC_STEPS for the scales, CHORDS, TRIADS and SEVENTHS for the chords, and HARMONIC_SERIES_AS_PRINTED for the article’s own table of partials, and SIMPLE_INTERVALS and CONSONANCE for the intervals.

Bonds

Relations tying a note’s vibrato and tremolo to its frequency, so that a piece decides once how its notes behave rather than note by note.

Bonds	A set of relations tying a note's characteristics to its frequency.
proportional	A bond that rises with the frequency: factor * f + offset.
inversely_proportional	A bond that falls with the frequency: numerator / f + offset.
stepped	A bond that changes in steps rather than continuously.

Utilities

Conversions

hz_to_midi	Converts a frequency in Hertz to a MIDI note number.
midi_to_hz	Converts a MIDI note number to the corresponding frequency in Hertz.
midi_to_hz_interval	Converts a MIDI interval to the corresponding frequency interval in
pitch_to_freq	Generates a list of frequencies based on a list of semitones and a starting frequency.
db_to_amp	Converts a difference in decibels to a difference in amplitude.
amp_to_db	Converts a difference in amplitude to a difference in decibels.
rhythm_to_durations	Returns durations from rhythmic patterns.

Combining sonic vectors

horizontal_stack	Creates a horizontal stack of arrays while preserving bidimensional
mix	Mixes two sonic vectors.
mix2	The name this had while it was the second mixer rather than the general one.
mix_many	Mix sonic vectors of arbitrary lengths.
mix_many_with_offsets	Mix any number of sonic vectors, each at its own offset.
mix_stereo	Mixes two stereo sonic vectors.
mix_with_offset	Mix two sonic vector by placing the beginning of the second one a specified number of seconds after the first one.
mix_with_offset_	The name this had before it was renamed for saying, in the name, how it differs from mix_with_offset.
convert_to_stereo	Converts a sound vector to stereo format.
resolve_stereo	Resolve stereo arguments for a function.
pan_transitions	Applies pan transitions to a sonic vector.
profile	Summarize a namespace of variables.

Wavetables

PrimaryTables	Provides primary tables for waveform lookup.
waveform_table	One period of a primary waveform, as a lookup table.

WAVEFORM_SINE, WAVEFORM_TRIANGULAR, WAVEFORM_SQUARE and WAVEFORM_SAWTOOTH are the lookup tables used by default throughout the package, and are the names that appear in the synthesis signatures above. They are re-exported from the top level like everything else, so music.note(waveform_table=music.WAVEFORM_SINE) works; music.WAVEFORMS names the shapes waveform_table() can build.

Singing

sing() sings a lyric to a melody, one syllable a note, with either of two backends that sing the same score at the same pitches for the same lengths, so that the two can be compared.

The default, backend="psola", is the package’s own singer. espeak-ng says each syllable, and Praat’s pitch-synchronous overlap-add, through praat-parselmouth, holds it at its note’s pitch and makes it the note’s length. A syllable said in less time than its note is said again, slower, down to 80 words a minute, and only the middle of its vowel is lengthened, so that its consonants keep the length they were said with. A long note is sung with a vibrato, 0.35 semitones each way at 5.5 Hz, setting in a quarter of a second into it, and the notes on the meter’s strong beats are sung up to 2.3 dB louder, as abc2midi accents them for eCantorix. It sings eCantorix’s effects, "tremolo", "melt" and "flite", with the package’s own tremolo, reverberation and resampling. It needs espeak-ng and pip install 'music[singing]', and sing() says which is missing.

backend="ecantorix" sings the same score with the external eCantorix engine, the default until the package had its own singer, kept as the reference. Run setup_engine() once to clone it; it also needs git, make, perl, espeak, abc2midi (the abcmidi package) and sox on the system, and the Perl modules MIDI, Math::FFT, URI::Escape and Digest::SHA. setup_engine() and sing() say which are missing.

The examples singing_backends.py and singing_effects.py sing the same songs, and the effects, with both. tools/compare_singing.py measures both backends’ pitch, length and render time against the score; tools/compare_singing_timing.py renders timings and syllable shapes for a level-matched listening review; and tools/score_singing_asr.py has Whisper, with pip install faster-whisper, count the words it hears in each.

sing	Sing a line of text to a melody.
setup_engine	Clone the eCantorix repository into the user's cache directory.
get_engine	Return the path to the local eCantorix engine.
make_test_song	Sing a short phrase with eCantorix, to check the engine works.

Legacy

Synthesizer classes kept for backwards compatibility, and as material for making more music.

Being	A configurable sequence walker that renders notes.
CanonicalSynth	Simple synthesizer for sound synthesis with vibrato, tremolo, and ADSR.
IteratorSynth	A synthesizer that iterates through arbitrary lists of variables.