Results

Spectrogram

class spectrograms.Spectrogram

Bases: object

Spectrogram computation result.

Contains the spectrogram data as a NumPy array along with frequency and time axes and the parameters used to create it.

T

Get the transpose of the spectrogram data.

Returns

numpy.typing.NDArray[numpy.float64]: Transposed 2D NumPy array with shape (n_frames, n_bins)

astype(dtype)

data

Get the spectrogram data as a NumPy array.

Returns

numpy.typing.NDArray[numpy.float64]: 2D NumPy array with shape (n_bins, n_frames)

db_range()

Get the decibel range if applicable.

Returns

tuple[float, float] or None: Tuple of (min_db, max_db) for decibel-scaled spectrograms, None otherwise

duration()

Get the total duration.

Returns

float: Duration in seconds

frequencies

Get the frequency axis values.

Returns

list[float]: List of frequency values (Hz or scale-specific units)

frequency_range()

Get the frequency range.

Returns

tuple[float, float]: Tuple of (f_min, f_max) in Hz or scale-specific units

n_bins

Get the number of frequency bins.

Returns

int: Number of frequency bins

n_frames

Get the number of time frames.

Returns

int: Number of time frames

params

Get the computation parameters.

Returns

SpectrogramParams: The SpectrogramParams used to compute this spectrogram

shape

Get the shape of the spectrogram.

Returns

tuple[int, int]: Tuple of (n_bins, n_frames)

times

Get the time axis values.

Returns

list[float]: List of time values in seconds

DLPack Protocol

All spectrogram objects (Spectrogram, Chromagram, Fft2dResult) implement the DLPack protocol for tensor exchange with deep learning frameworks.

Spectrogram.__dlpack__(*, stream=None, max_version=None, dl_device=None, copy=None)

Export the spectrogram data as a DLPack capsule for tensor exchange.

This method implements the DLPack protocol, enabling efficient data sharing with deep learning frameworks like PyTorch, JAX, and TensorFlow without copying data.

Parameters:

stream (Optional[int]) – Must be None for CPU tensors (reserved for future GPU support)
max_version (Optional[tuple[int, int]]) – Maximum DLPack version supported by the consumer
dl_device (Optional[tuple[int, int]]) – Target device (device_type, device_id). Must be (1, 0) for CPU
copy (Optional[bool]) – If True, create a copy of the data. If None or False, returns a view

Returns:

A DLPack capsule containing the tensor data

Raises:

BufferError – If parameters are invalid for CPU tensors

Example:

import spectrograms as sg
import torch

spec = sg.compute_mel_power_spectrogram(samples, params, mel_params)

# Convert to PyTorch tensor ()
tensor = torch.from_dlpack(spec)

# With explicit copy
tensor_copy = torch.from_dlpack(spec.__dlpack__(copy=True))

Spectrogram.__dlpack_device__()

Return the device type and device ID for DLPack protocol.

Returns:: Tuple of (device_type, device_id). Always (1, 0) for CPU device
Return type:: tuple[int, int]

Device Type Constants:

1 (kDLCPU): CPU device
2 (kDLCUDA): CUDA GPU
10 (kDLROCm): ROCm GPU

Example:

spec = sg.compute_mel_power_spectrogram(samples, params, mel_params)
device_type, device_id = spec.__dlpack_device__()
print(f"Device: type={device_type}, id={device_id}")  # Device: type=1, id=0

See Machine Learning Integration for complete usage examples with PyTorch and JAX.