Analysis and utilities
What the modules that measure audio or do arithmetic on it take and return. The guides cover the two analysers: Meter levels and Speech features.
audiometer
Generated from audiometer.pyi; the file reads on its own.
Band levels for a spectrum meter.
Meter splits audio into log-spaced frequency bands and reports each band’s
level, plus the peak and the RMS, as one byte each in half-dB steps: 0 is
-100 dB or quieter and 200 is a full-scale sine. Feed it audio from Python, or
attach an audiopump.Tap and it reads whatever the pump is playing or
recording, in C.
- audiometer.MAX_BANDS
- Type:
The most bands a meter can have
- class audiometer.Meter(bands=32, *, low_hz=None, high_hz=None)[source]
Bases:
objectA spectrum meter.
- Parameters:
bands – How many bands, 0 to
MAX_BANDS. 0 turns the meter off.low_hz – The bottom of the lowest band in Hz. The default is 35.
high_hz – The top of the highest band in Hz, above
low_hz. The default is 20000.
- Raises:
ValueError –
bandsis out of range, or the band edges are not 0 <low_hz<high_hz.MemoryError – The meter does not fit.
- configure(bands, *, low_hz=None, high_hz=None)[source]
Change the bands, as for the constructor.
low_hzandhigh_hzgo back to 35 and 20000 when left out.- Raises:
ValueError – As for the constructor.
- feed(buffer, sample_rate, channel_count=2, /)[source]
Run audio through the meter.
- Parameters:
buffer – Interleaved signed 16-bit samples, a whole number of frames.
sample_rate – The audio’s rate in Hz, 1000 to 384000.
channel_count – Channels in the buffer, 1 to 8.
- Raises:
ValueError – The rate or channel count is out of range, the buffer is not a whole number of frames, the meter was deinitialised, or it is attached to a source (
detachit first).
- attach(tap, sample_rate, /)[source]
Read an
audiopump.Tapin C, from where it is now.The tap is drained each time
levelsruns, on the reader’s thread, so the pump pays nothing. The tap’s channel count is taken from the tap; give the rate it runs at.- Parameters:
tap – An
audiopump.Tap.sample_rate – The tap’s rate in Hz, 1000 to 384000.
- Raises:
TypeError –
tapis not anaudiopump.Tap.ValueError – The rate is out of range.
- levels(buffer=None, /)[source]
Take the latest reading.
- Parameters:
buffer – Optional. Where to write the band levels, so nothing is allocated. It is filled with as many bands as fit.
- Returns:
(seq, levels, peak, rms).seqcounts analyses, at 60 a second of audio, so a reader can tell fresh levels from a stopped stream.levelsisbuffer, or a newbytesholding one byte a band, lowest band first.peakandrmsare bytes on the same scale.
- stats()[source]
Counters.
- Returns:
A dict with
enabled,bands,analyses(done so far),feed_us(microseconds spent feeding),analysis_us(microseconds spent analysing),max_analysis_us(the longest single analysis),elapsed_us,lapped(times an attached tap overwrote audio before it was read) andsource("tap", or None when nothing is attached).
- deinit()[source]
Free the meter. Later calls other than
deinitraiseValueError.
audiofeatures
Generated from audiofeatures.pyi; the file reads on its own.
Speech features for a wake word model.
Frontend turns audio into what a microWakeWord model listens to: every
10 ms, a slice of 40 values, one per mel band from 125 Hz to 7.5 kHz. It is
TensorFlow Lite Micro’s audio microfrontend with the settings those models
were trained on. Feed it audio from Python, or attach an audiopump.Tap and
it reads the audio in C. Each slice also carries a voice activity flag.
Audio at any rate from 16 kHz to 384 kHz is accepted; other rates are resampled to 16 kHz first, and stereo or wider audio is mixed to mono.
- audiofeatures.FEATURE_SIZE
- Type:
Values in one slice
- audiofeatures.SAMPLE_RATE
Audio at this rate is not resampled.
- Type:
The frontend’s own rate in Hz
- audiofeatures.STEP_MS
- Type:
Audio that makes one slice, in milliseconds
- class audiofeatures.Frontend(*, slices=100)[source]
Bases:
objectThe feature extractor, with a queue of finished slices.
Slices wait in the queue until
readintotakes them. When it is full, the oldest are dropped and counted instats.- Parameters:
slices – How many slices the queue holds, 8 to 100000. The default is one second of audio.
- Raises:
ValueError –
slicesis out of range.MemoryError – The queue does not fit.
- feed(buffer, sample_rate, channel_count=1, /)[source]
Run audio through the frontend.
- Parameters:
buffer – Interleaved signed 16-bit samples, a whole number of frames.
sample_rate – The audio’s rate in Hz, 16000 to 384000.
channel_count – Channels in the buffer, 1 to 8.
- Returns:
How many finished slices are waiting.
- Raises:
ValueError – The rate or channel count is out of range, the buffer is not a whole number of frames, the frontend was deinitialised, or it is attached to a source (
detachit first).MemoryError – The resampler does not fit.
- attach(tap, sample_rate, /)[source]
Read an
audiopump.Tapin C, from where it is now.The tap is drained each time
readintoruns, on the reader’s thread. The tap’s channel count is taken from the tap; give the rate it runs at.- Parameters:
tap – An
audiopump.Tap.sample_rate – The tap’s rate in Hz, 16000 to 384000.
- Raises:
TypeError –
tapis not anaudiopump.Tap.ValueError – The rate is out of range.
- readinto(buffer, voice=None, /)[source]
Take finished slices as the int8 values a model takes.
- Parameters:
buffer – Where to write them. It holds one slice per
FEATURE_SIZEbytes.voice – Optional. One byte a slice is written here: 1 when the slice holds speech, 0 for silence or steady noise. It limits how many slices are taken if it is shorter than
bufferallows.
- Returns:
How many whole slices were written.
- readinto_raw(buffer, voice=None, /)[source]
Take finished slices as the frontend’s own unsigned 16-bit values, about 0 to 670.
- Parameters:
buffer – Where to write them. It holds one slice per
2 * FEATURE_SIZEbytes.voice – As for
readinto.
- Returns:
How many whole slices were written.
- reset()[source]
Forget all audio and slices, as if just made. An attached tap is read from where it is now.
- stats()[source]
Counters.
- Returns:
A dict with
slices(made so far),dropped(lost to a full queue),waiting,capacity,rate(the input rate in Hz),resampling(whether that rate needs it),lapped(times an attached tap overwrote audio before it was read) andsource("tap", or None when nothing is attached).
- deinit()[source]
Free the queue. Later calls other than
deinitraiseValueError.
- audiofeatures.quantize(value, /)[source]
The int8 a model takes for one raw frontend value.
This is
(value * 256 + 333) // 666 - 128, which is whatreadintoapplies to every value.- Parameters:
value – A raw value, 0 to 65535.
- Raises:
ValueError –
valueis out of range.
audiomath
Generated from audiomath.pyi; the file reads on its own.
Arithmetic on audio streams.
Multiply multiplies one stream by another, which is ring and amplitude
modulation. SubOctave divides a stream down in frequency, as an analog
octave divider does. remix_s16 changes between mono and stereo, and
cast_into turns a block of floats into the 16-bit buffer a RawSample
plays, without allocating.
Both nodes are audio samples, so they play wherever a RawSample does and
take any audio sample as their source.
- class audiomath.Multiply(source=None, modulator=None, mix=None, sample_rate=48000, channel_count=2)[source]
Bases:
objectMultiplies a stream by a modulator, sample by sample.
The output is the source blended toward the source times the modulator:
mix1.0 is the full product and 0.0 is the source untouched. With no modulator, or after the modulator has run dry, the source passes through unchanged rather than going silent. With no source, the node outputs silence and never reports itself finished.The source and the modulator must have this node’s channel count. Output is 16-bit signed.
- Parameters:
source – The stream to modulate, or None to set it later with
play.modulator – The stream to multiply by, or None to set it later with
modulate. A short looping table such as a sine in aRawSampleis the usual choice.mix – Wet amount from 0.0 to 1.0, clamped. The default is 1.0.
sample_rate – Frames per second.
channel_count – 1 or 2.
- Raises:
ValueError –
channel_countis not 1 or 2, or a stream’s channel count differs from it.
- property sample_rate
Frames per second.
- property bits_per_sample
Size of one sample in bits: always 16.
- property channel_count
Number of channels: 1 or 2.
- play(source, /)[source]
Replace the stream being modulated.
- Raises:
ValueError – The stream’s channel count differs from this node’s.
- modulate(modulator, /)[source]
Replace the stream that multiplies the source.
- Raises:
ValueError – The stream’s channel count differs from this node’s.
- set(*, mix=Ellipsis)[source]
Change an option while the node plays.
A move of
mixon a playing node walks to the new value in a straight line over 20 ms instead of stepping, so it doesn’t click. Before the first pull, or after a reset, it lands at once.- Parameters:
mix – Wet amount from 0.0 to 1.0, clamped.
- Raises:
TypeError – An option other than
mixwas given.
- deinit()[source]
Release the node and let go of its source and modulator. Every later use raises
ValueError.
- class audiomath.SubOctave(source=None, order=None, mix=None, threshold=None, hold_ms=None, sample_rate=48000, channel_count=2)[source]
Bases:
objectAn analog-style octave divider.
A Schmitt trigger watches the source for rising edges and two flip-flops halve the count, so the output is a square wave one or two octaves below the input’s pitch, blended with the dry signal by
mix. It works best on a single note: filter a chord to its fundamental first.- Parameters:
source – The stream to divide, or None to set it later with
play. Its channel count must match this node’s.order – 1 for one octave down, 2 for two. Any value of 2 or more means 2.
mix – How much of the divided signal replaces the dry signal, 0.0 to 1.0, clamped. The default is 1.0.
threshold – How far from zero the comparator’s two thresholds sit, as a fraction of full scale, 0.0 to 1.0, clamped. Signal between them leaves the comparator where it is. 0.0 is a bare zero-crossing detector.
hold_ms – Milliseconds after an accepted edge during which another is ignored, to keep noise from counting twice. Negative values mean 0.
sample_rate – Frames per second, 1 or more.
channel_count – 1 or 2.
- Raises:
ValueError –
channel_countis not 1 or 2,sample_rateis below 1, or the source’s channel count differs.
- property sample_rate
Frames per second.
- property bits_per_sample
Size of one sample in bits: always 16.
- property channel_count
Number of channels: 1 or 2.
- play(source, /)[source]
Replace the stream being divided.
- Raises:
ValueError – The stream’s channel count differs from this node’s.
- set(*, order=Ellipsis, mix=Ellipsis, threshold=Ellipsis, hold_ms=Ellipsis)[source]
Change options while the node plays. The count keeps running, so a change never flips the output’s polarity.
- Parameters:
order – As for the constructor.
mix – As for the constructor.
threshold – As for the constructor.
hold_ms – As for the constructor.
- Raises:
TypeError – An unknown option was given.
- deinit()[source]
Release the node and let go of its source. Every later use raises
ValueError.
- audiomath.remix_s16(source, src_channels, dst_channels, dest=None, /)[source]
Convert interleaved 16-bit audio between mono and stereo.
- Parameters:
source – Signed 16-bit samples, a whole number of frames.
src_channels – The source’s channel count, 1 or 2.
dst_channels – The channel count wanted, 1 or 2.
dest – A buffer to write into, at least as long as the result. Leave it out to get a new
bytearray.
- Returns:
dest, or the newbytearraywhendestwas left out.- Raises:
ValueError – A channel count is not 1 or 2,
sourceis not a whole number of frames, ordestis too small.
- audiomath.cast_into(dst, src, scale=32767.0)[source]
Convert a block of floats into 16-bit samples without allocating.
Each value is multiplied by
scale, rounded half away from zero and saturated to the 16-bit range.- Parameters:
dst – Where to write: a buffer of signed 16-bit samples, as many as
srchas floats.src – A buffer of 32-bit or 64-bit floats, such as an
array.arrayof type'f'or'd'.scale – What a value of 1.0 becomes.
- Raises:
TypeError –
dstis not a 16-bit buffer orsrcis not floats.ValueError –
dstandsrchold a different number of samples.