Planner API

The planner API enables efficient batch processing by reusing FFT plans across multiple signals.

Creating Plans

class spectrograms.SpectrogramPlanner

Bases: object

Spectrogram planner for creating reusable computation plans.

Creating a plan is more expensive than a single computation, but plans can be reused for multiple signals with the same parameters, providing significant performance benefits for batch processing.

cqt_db_plan(params: SpectrogramParams, cqt_params: CqtParams, db_params: LogParams, dtype: str = 'float64') CqtDbPlan

Create a plan for computing CQT decibel spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

cqt_paramsCqtParams

Constant-Q Transform parameters

db_paramsLogParams

Decibel conversion parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

CqtDbPlan

Plan for computing CQT decibel spectrograms

cqt_magnitude_plan(params: SpectrogramParams, cqt_params: CqtParams, dtype: str = 'float64') CqtMagnitudePlan

Create a plan for computing CQT magnitude spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

cqt_paramsCqtParams

Constant-Q Transform parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

CqtMagnitudePlan

Plan for computing CQT magnitude spectrograms

cqt_power_plan(params: SpectrogramParams, cqt_params: CqtParams, dtype: str = 'float64') CqtPowerPlan

Create a plan for computing CQT power spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

cqt_paramsCqtParams

Constant-Q Transform parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

CqtPowerPlan

Plan for computing CQT power spectrograms

erb_db_plan(params: SpectrogramParams, erb_params: ErbParams, db_params: LogParams, dtype: str = 'float64') ErbDbPlan

Create a plan for computing ERB decibel spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

erb_paramsErbParams

ERB-scale filterbank parameters

db_paramsLogParams

Decibel conversion parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

ErbDbPlan

Plan for computing ERB decibel spectrograms

erb_magnitude_plan(params: SpectrogramParams, erb_params: ErbParams, dtype: str = 'float64') ErbMagnitudePlan

Create a plan for computing ERB magnitude spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

erb_paramsErbParams

ERB-scale filterbank parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

ErbMagnitudePlan

Plan for computing ERB magnitude spectrograms

erb_power_plan(params: SpectrogramParams, erb_params: ErbParams, dtype: str = 'float64') ErbPowerPlan

Create a plan for computing ERB power spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

erb_paramsErbParams

ERB-scale filterbank parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

ErbPowerPlan

Plan for computing ERB power spectrograms

linear_db_plan(params: SpectrogramParams, db_params: LogParams, dtype: str = 'float64') LinearDbPlan

Create a plan for computing linear decibel spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

db_paramsLogParams

Decibel conversion parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

LinearDbPlan

Plan for computing linear decibel spectrograms

linear_magnitude_plan(params: SpectrogramParams, dtype: str = 'float64') LinearMagnitudePlan

Create a plan for computing linear magnitude spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

LinearMagnitudePlan

Plan for computing linear magnitude spectrograms

linear_power_plan(params: SpectrogramParams, dtype: str = 'float64') LinearPowerPlan

Create a plan for computing linear power spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

LinearPowerPlan

Plan for computing linear power spectrograms

loghz_db_plan(params: SpectrogramParams, loghz_params: LogHzParams, db_params: LogParams, dtype: str = 'float64') LogHzDbPlan

Create a plan for computing logarithmic Hz decibel spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

loghz_paramsLogHzParams

Logarithmic Hz scale parameters

db_paramsLogParams

Decibel conversion parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

LogHzDbPlan

Plan for computing logarithmic Hz decibel spectrograms

loghz_magnitude_plan(params: SpectrogramParams, loghz_params: LogHzParams, dtype: str = 'float64') LogHzMagnitudePlan

Create a plan for computing logarithmic Hz magnitude spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

loghz_paramsLogHzParams

Logarithmic Hz scale parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

LogHzMagnitudePlan

Plan for computing logarithmic Hz magnitude spectrograms

loghz_power_plan(params: SpectrogramParams, loghz_params: LogHzParams, dtype: str = 'float64') LogHzPowerPlan

Create a plan for computing logarithmic Hz power spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

loghz_paramsLogHzParams

Logarithmic Hz scale parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

LogHzPowerPlan

Plan for computing logarithmic Hz power spectrograms

mel_db_plan(params: SpectrogramParams, mel_params: MelParams, db_params: LogParams, dtype: str = 'float64') MelDbPlan

Create a plan for computing mel decibel spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

mel_paramsMelParams

Mel-scale filterbank parameters

db_paramsLogParams

Decibel conversion parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

MelDbPlan

Plan for computing mel decibel spectrograms

mel_magnitude_plan(params: SpectrogramParams, mel_params: MelParams, dtype: str = 'float64') MelMagnitudePlan

Create a plan for computing mel magnitude spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

mel_paramsMelParams

Mel-scale filterbank parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

MelMagnitudePlan

Plan for computing mel magnitude spectrograms

mel_power_plan(params: SpectrogramParams, mel_params: MelParams, dtype: str = 'float64') MelPowerPlan

Create a plan for computing mel power spectrograms.

Parameters

paramsSpectrogramParams

Spectrogram parameters

mel_paramsMelParams

Mel-scale filterbank parameters

dtypestr, optional

Output precision, "float32" or "float64" (default).

Returns

MelPowerPlan

Plan for computing mel power spectrograms

Plan Classes

Linear Plans

class spectrograms.LinearPowerPlan

Bases: object

Plan for computing linear power spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.LinearMagnitudePlan

Bases: object

Plan for computing linear magnitude spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.LinearDbPlan

Bases: object

Plan for computing linear decibel spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

Mel Plans

class spectrograms.MelPowerPlan

Bases: object

Plan for computing mel power spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.MelMagnitudePlan

Bases: object

Plan for computing mel magnitude spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.MelDbPlan

Bases: object

Plan for computing mel decibel spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

ERB Plans

class spectrograms.ErbPowerPlan

Bases: object

Plan for computing ERB power spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.ErbMagnitudePlan

Bases: object

Plan for computing ERB magnitude spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.ErbDbPlan

Bases: object

Plan for computing ERB decibel spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

LogHz Plans

class spectrograms.LogHzPowerPlan

Bases: object

Plan for computing logarithmic Hz power spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.LogHzMagnitudePlan

Bases: object

Plan for computing logarithmic Hz magnitude spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.LogHzDbPlan

Bases: object

Plan for computing logarithmic Hz decibel spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

CQT Plans

class spectrograms.CqtPowerPlan

Bases: object

Plan for computing CQT power spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.CqtMagnitudePlan

Bases: object

Plan for computing CQT magnitude spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

class spectrograms.CqtDbPlan

Bases: object

Plan for computing CQT decibel spectrograms.

compute(samples: numpy.typing.NDArray) Spectrogram

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

Returns

Spectrogram

Computed spectrogram result (.data follows the plan’s dtype)

compute_frame(samples: numpy.typing.NDArray, frame_idx: int) numpy.typing.NDArray

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray

Audio samples as a 1D array (coerced to the plan’s precision)

frame_idxint

Frame index to compute

Returns

numpy.typing.NDArray

1D array containing the frame data (in the plan’s precision)

dtype

The NumPy dtype the plan computes in ("float32" / "float64").

output_shape(signal_length: int) tuple[int, int]

Get the output shape for a given signal length.

Parameters

signal_lengthint

Length of the input signal

Returns

tuple[int, int]

Tuple of (n_bins, n_frames)

2D FFT Planner

For efficient batch processing of 2D FFT operations on images.

class spectrograms.Fft2dPlanner

Bases: object

Create a planner once and reuse it for multiple images of the same size to avoid repeated FFT plan computation overhead.

Example

import spectrograms as sg
import numpy as np

# Create planner
planner = sg.Fft2dPlanner()

# Process multiple images
images = [np.random.randn(256, 256) for _ in range(10)]
spectra = [planner.fft2d(img) for img in images]

# All methods reuse the cached plan
power_spectra = [planner.power_spectrum_2d(img) for img in images]
dtype

The working precision of this planner (“float32” or “float64”).

fft2d()

Compute 2D FFT using cached plans.

Parameters

datanumpy.typing.NDArray[numpy.float64]

Input 2D array with shape (nrows, ncols)

Returns

numpy.typing.NDArray[numpy.complex128]

Complex 2D array with shape (nrows, ncols/2 + 1), complex128 or complex64

ifft2d()

Compute inverse 2D FFT using cached plans.

Parameters

spectrumnumpy.typing.NDArray[numpy.complex128]

Complex frequency array

output_ncolsint

Number of columns in output

Returns

numpy.typing.NDArray[numpy.float64]

Real 2D array, float64 or float32

magnitude_spectrum_2d()

Compute 2D magnitude spectrum using cached plans.

power_spectrum_2d()

Compute 2D power spectrum using cached plans.