Planner API
The planner API enables efficient batch processing by reusing FFT plans across multiple signals.
Creating Plans
- class spectrograms.SpectrogramPlanner
Bases:
objectSpectrogram 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:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.LinearMagnitudePlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.LinearDbPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
Mel Plans
- class spectrograms.MelPowerPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.MelMagnitudePlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.MelDbPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
ERB Plans
- class spectrograms.ErbPowerPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.ErbMagnitudePlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.ErbDbPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
LogHz Plans
- class spectrograms.LogHzPowerPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.LogHzMagnitudePlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.LogHzDbPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
CQT Plans
- class spectrograms.CqtPowerPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.CqtMagnitudePlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
- class spectrograms.CqtDbPlan
Bases:
objectPlan 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 (
.datafollows the plan’sdtype)
- 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").
2D FFT Planner
For efficient batch processing of 2D FFT operations on images.
- class spectrograms.Fft2dPlanner
Bases:
objectCreate 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.