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: object

A 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 – bands is 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_hz and high_hz go 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 (detach it first).

attach(tap, sample_rate, /)[source]

Read an audiopump.Tap in C, from where it is now.

The tap is drained each time levels runs, 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:
detach()[source]

Stop reading the attached tap, if there is one.

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). seq counts analyses, at 60 a second of audio, so a reader can tell fresh levels from a stopped stream. levels is buffer, or a new bytes holding one byte a band, lowest band first. peak and rms are 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) and source ("tap", or None when nothing is attached).

deinit()[source]

Free the meter. Later calls other than deinit raise ValueError.

audiometer.db_byte(power, /)[source]

The byte a power reads as on the meter’s scale.

Parameters:

power – Signal power, where 1.0 is a full-scale sine.

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
  1. 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: object

The feature extractor, with a queue of finished slices.

Slices wait in the queue until readinto takes them. When it is full, the oldest are dropped and counted in stats.

Parameters:

slices – How many slices the queue holds, 8 to 100000. The default is one second of audio.

Raises:
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 (detach it first).

  • MemoryError – The resampler does not fit.

attach(tap, sample_rate, /)[source]

Read an audiopump.Tap in C, from where it is now.

The tap is drained each time readinto runs, 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:
detach()[source]

Stop reading the attached tap, if there is one.

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_SIZE bytes.

  • 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 buffer allows.

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_SIZE bytes.

  • voice – As for readinto.

Returns:

How many whole slices were written.

speaking()[source]

Whether the newest slice holds speech.

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) and source ("tap", or None when nothing is attached).

deinit()[source]

Free the queue. Later calls other than deinit raise ValueError.

audiofeatures.quantize(value, /)[source]

The int8 a model takes for one raw frontend value.

This is (value * 256 + 333) // 666 - 128, which is what readinto applies to every value.

Parameters:

value – A raw value, 0 to 65535.

Raises:

ValueError – value is 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: object

Multiplies a stream by a modulator, sample by sample.

The output is the source blended toward the source times the modulator: mix 1.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 a RawSample is 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_count is 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 mix on 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 mix was 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: object

An 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_count is not 1 or 2, sample_rate is 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.

clear()[source]

Reset the comparator and the dividers to where a new node starts.

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 new bytearray when dest was left out.

Raises:

ValueError – A channel count is not 1 or 2, source is not a whole number of frames, or dest is 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 src has floats.

  • src – A buffer of 32-bit or 64-bit floats, such as an array.array of type 'f' or 'd'.

  • scale – What a value of 1.0 becomes.

Raises:
  • TypeError – dst is not a 16-bit buffer or src is not floats.

  • ValueError – dst and src hold a different number of samples.