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) → CqtDbPlan

–

Create a plan for computing CQT decibel spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
cqt_paramsCqtParams: Constant-Q Transform parameters
db_paramsLogParams: Decibel conversion parameters

Returns

CqtDbPlan: Plan for computing CQT decibel spectrograms

cqt_magnitude_plan(params: SpectrogramParams, cqt_params: CqtParams) → CqtMagnitudePlan

–

Create a plan for computing CQT magnitude spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
cqt_paramsCqtParams: Constant-Q Transform parameters

Returns

CqtMagnitudePlan: Plan for computing CQT magnitude spectrograms

cqt_power_plan(params: SpectrogramParams, cqt_params: CqtParams) → CqtPowerPlan

–

Create a plan for computing CQT power spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
cqt_paramsCqtParams: Constant-Q Transform parameters

Returns

CqtPowerPlan: Plan for computing CQT power spectrograms

erb_db_plan(params: SpectrogramParams, erb_params: ErbParams, db_params: LogParams) → ErbDbPlan

–

Create a plan for computing ERB decibel spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
erb_paramsErbParams: ERB-scale filterbank parameters
db_paramsLogParams: Decibel conversion parameters

Returns

ErbDbPlan: Plan for computing ERB decibel spectrograms

erb_magnitude_plan(params: SpectrogramParams, erb_params: ErbParams) → ErbMagnitudePlan

–

Create a plan for computing ERB magnitude spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
erb_paramsErbParams: ERB-scale filterbank parameters

Returns

ErbMagnitudePlan: Plan for computing ERB magnitude spectrograms

erb_power_plan(params: SpectrogramParams, erb_params: ErbParams) → ErbPowerPlan

–

Create a plan for computing ERB power spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
erb_paramsErbParams: ERB-scale filterbank parameters

Returns

ErbPowerPlan: Plan for computing ERB power spectrograms

linear_db_plan(params: SpectrogramParams, db_params: LogParams) → LinearDbPlan

–

Create a plan for computing linear decibel spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
db_paramsLogParams: Decibel conversion parameters

Returns

LinearDbPlan: Plan for computing linear decibel spectrograms

linear_magnitude_plan(params: SpectrogramParams) → LinearMagnitudePlan

–

Create a plan for computing linear magnitude spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters

Returns

LinearMagnitudePlan: Plan for computing linear magnitude spectrograms

linear_power_plan(params: SpectrogramParams) → LinearPowerPlan

–

Create a plan for computing linear power spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters

Returns

LinearPowerPlan: Plan for computing linear power spectrograms

loghz_db_plan(params: SpectrogramParams, loghz_params: LogHzParams, db_params: LogParams) → 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

Returns

LogHzDbPlan: Plan for computing logarithmic Hz decibel spectrograms

loghz_magnitude_plan(params: SpectrogramParams, loghz_params: LogHzParams) → LogHzMagnitudePlan

–

Create a plan for computing logarithmic Hz magnitude spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
loghz_paramsLogHzParams: Logarithmic Hz scale parameters

Returns

LogHzMagnitudePlan: Plan for computing logarithmic Hz magnitude spectrograms

loghz_power_plan(params: SpectrogramParams, loghz_params: LogHzParams) → LogHzPowerPlan

–

Create a plan for computing logarithmic Hz power spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
loghz_paramsLogHzParams: Logarithmic Hz scale parameters

Returns

LogHzPowerPlan: Plan for computing logarithmic Hz power spectrograms

mel_db_plan(params: SpectrogramParams, mel_params: MelParams, db_params: LogParams) → MelDbPlan

–

Create a plan for computing mel decibel spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
mel_paramsMelParams: Mel-scale filterbank parameters
db_paramsLogParams: Decibel conversion parameters

Returns

MelDbPlan: Plan for computing mel decibel spectrograms

mel_magnitude_plan(params: SpectrogramParams, mel_params: MelParams) → MelMagnitudePlan

–

Create a plan for computing mel magnitude spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
mel_paramsMelParams: Mel-scale filterbank parameters

Returns

MelMagnitudePlan: Plan for computing mel magnitude spectrograms

mel_power_plan(params: SpectrogramParams, mel_params: MelParams) → MelPowerPlan

–

Create a plan for computing mel power spectrograms.

Parameters

paramsSpectrogramParams: Spectrogram parameters
mel_paramsMelParams: Mel-scale filterbank parameters

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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[numpy.float64]) → Spectrogram

–

Compute a spectrogram from audio samples.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array

Returns

Spectrogram: Computed spectrogram result

compute_frame(samples: numpy.typing.NDArray[numpy.float64], frame_idx: int) → numpy.typing.NDArray[numpy.float64]

–

Compute a single frame of the spectrogram.

Parameters

samplesnumpy.typing.NDArray[numpy.float64]: Audio samples as a 1D array
frame_idxint: Frame index to compute

Returns

numpy.typing.NDArray[numpy.float64]: 1D array containing the frame data

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

2D FFT planner for efficient batch processing.

Caches FFT plans internally to avoid repeated setup overhead when processing multiple arrays with the same dimensions.

Examples

>>> import spectrograms as sg
>>> import numpy as np
>>> planner = sg.Fft2dPlanner()
>>> for _ in range(10):
...     image = np.random.randn(128, 128)
...     spectrum = planner.fft2d(image)

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]

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.complex64]: Complex 2D array with shape (nrows, ncols/2 + 1)

ifft2d()

Compute inverse 2D FFT using cached plans.

Parameters

spectrumnumpy.typing.NDArray[numpy.complex64]: Complex frequency array
output_ncolsint: Number of columns in output

Returns

numpy.typing.NDArray[numpy.float64]: Real 2D array

magnitude_spectrum_2d(): Compute 2D magnitude spectrum using cached plans.

power_spectrum_2d(): Compute 2D power spectrum using cached plans.