pyquist.plot

Matplotlib helpers for visualizing Audio — waveform, magnitude spectrum, and spectrogram.

Plot helpers for Audio (waveform, magnitude spectrum, spectrogram).

These work the same in a notebook and a regular script. Pass output_file=<path> to save the figure to disk in addition to (or instead of) displaying it interactively.

pyquist.plot.plot(audio, *, offset=None, duration=None, figsize=(10, 3), ax=None, output_file=None)[source]

Plots the waveform of an Audio.

Channels are overlaid on a single axis. The x-axis is time in seconds if audio.sample_rate is set, otherwise sample index. The y-axis is symmetric about zero.

Parameters:

  • audio (Audio) – The audio to plot.

  • offset (Optional[float]) – Start time in seconds. Defaults to 0.0 (beginning of audio). Requires audio.sample_rate to be set.

  • duration (Optional[float]) – Length to plot in seconds. Defaults to the rest of the audio. Requires audio.sample_rate to be set.

  • figsize (Tuple[float, float]) – Figure size passed to plt.subplots (ignored if ax is given).

  • ax (Optional[Axes]) – An existing axis to draw into. If None, a new figure is created.

  • output_file (Optional[str]) – If given, the figure is saved to this path via Figure.savefig. Extension determines format (.png, .pdf, .svg, …).

Return type:

Axes

Returns:

The matplotlib Axes the waveform was drawn on.

pyquist.plot.plot_freq(audio, *, offset=None, duration=None, n_fft=None, log_frequency=True, log_amplitude=True, dynamic_range_db=80.0, figsize=(10, 3), ax=None, output_file=None)[source]

Plots the magnitude spectrum of an Audio via a single FFT.

Multi-channel audio is first mixed to mono. By default n_fft is the smallest power of two >= num_samples (zero-padding shorter signals), capped at NFFT_MAX. When the cap kicks in, a warning is issued and the FFT is taken over only the first NFFT_MAX samples.

Parameters:

  • audio (Audio) – The audio to analyze. Must have a sample_rate.

  • offset (Optional[float]) – Start time in seconds. Defaults to 0.0 (beginning of audio).

  • duration (Optional[float]) – Length to analyze in seconds. Defaults to the rest of the audio.

  • n_fft (Optional[int]) – FFT size. None (default) picks the smallest power of two >= num_samples (capped at NFFT_MAX). When set explicitly, shorter signals are zero-padded and longer signals are truncated to the first n_fft samples (no warning).

  • log_frequency (bool) – If True (default), the x-axis uses a log scale.

  • log_amplitude (bool) – If True (default), magnitudes are converted to dB.

  • dynamic_range_db (float) – Magnitudes below -dynamic_range_db dB are floored for numerical stability. Only used when log_amplitude=True.

  • figsize (Tuple[float, float]) – Figure size (ignored if ax is given).

  • ax (Optional[Axes]) – An existing axis to draw into. If None, a new figure is created.

  • output_file (Optional[str]) – If given, the figure is saved to this path.

Return type:

Axes

Returns:

The matplotlib Axes the spectrum was drawn on.

pyquist.plot.plot_spec(audio, *, offset=None, duration=None, n_fft=2048, hop_length=512, log_frequency=True, log_amplitude=True, dynamic_range_db=80.0, figsize=(10, 4), ax=None, output_file=None)[source]

Plots a magnitude spectrogram of an Audio.

Multi-channel audio is first mixed to mono. A Hann-windowed STFT with n_fft window size and hop_length frame advance is computed; magnitudes are optionally converted to dB and plotted on a log-frequency axis (both defaults).

Parameters:

  • audio (Audio) – The audio to analyze. Must have a sample_rate.

  • offset (Optional[float]) – Start time in seconds. Defaults to 0.0 (beginning of audio).

  • duration (Optional[float]) – Length to analyze in seconds. Defaults to the rest of the audio.

  • n_fft (int) – STFT window size in samples. Defaults to 2048 (~46 ms at 44.1 kHz).

  • hop_length (int) – Frame advance in samples. Defaults to 512 (75% overlap).

  • log_frequency (bool) – If True (default), the y-axis uses a log scale.

  • log_amplitude (bool) – If True (default), magnitudes are converted to dB (via pyquist.helper.amplitude_to_db()).

  • dynamic_range_db (float) – Magnitudes below -dynamic_range_db dB are floored for numerical stability. Only used when log_amplitude=True.

  • figsize (Tuple[float, float]) – Figure size (ignored if ax is given).

  • ax (Optional[Axes]) – An existing axis to draw into. If None, a new figure is created.

  • output_file (Optional[str]) – If given, the figure is saved to this path.

Return type:

Axes

Returns:

The matplotlib Axes the spectrogram was drawn on.