huggingface/transformers · error · ValueError

Input waveform must have only one dimension, shape is {wavef

Error message

Input waveform must have only one dimension, shape is {waveform.shape}

What it means

Thrown by `spectrogram` when the input `waveform` does not have exactly one dimension. The function frames a single mono channel, so a 2-D batch of shape (batch, samples) or a (channels, samples) stereo array is rejected with the offending shape echoed in the message. For batched input the module provides `spectrogram_batch` instead.

Source

Thrown at src/transformers/audio_utils.py:942

        `nd.array` containing a spectrogram of shape `(num_frequency_bins, length)` for a regular spectrogram or shape
        `(num_mel_filters, length)` for a mel spectrogram.
    """
    window_length = len(window)

    if fft_length is None:
        fft_length = frame_length

    if frame_length > fft_length:
        raise ValueError(f"frame_length ({frame_length}) may not be larger than fft_length ({fft_length})")

    if window_length != frame_length:
        raise ValueError(f"Length of the window ({window_length}) must equal frame_length ({frame_length})")

    if hop_length <= 0:
        raise ValueError("hop_length must be greater than zero")

    if waveform.ndim != 1:
        raise ValueError(f"Input waveform must have only one dimension, shape is {waveform.shape}")

    if np.iscomplexobj(waveform):
        raise ValueError("Complex-valued input waveforms are not currently supported")

    if power is None and mel_filters is not None:
        raise ValueError(
            "You have provided `mel_filters` but `power` is `None`. Mel spectrogram computation is not yet supported for complex-valued spectrogram."
            "Specify `power` to fix this issue."
        )

    # center pad the waveform
    if center:
        padding = [(int(frame_length // 2), int(frame_length // 2))]
        waveform = np.pad(waveform, padding, mode=pad_mode)

    # promote to float64, since np.fft uses float64 internally
    waveform = waveform.astype(np.float64)
    window = window.astype(np.float64)

View on GitHub (pinned to a597f97485)

Solutions

1. Squeeze to 1-D first: waveform = np.asarray(waveform).squeeze() or waveform = waveform.mean(axis=...) for stereo
2. For batches, use `spectrogram_batch(waveform_list, ...)` instead of `spectrogram`
3. Index the individual sample: spectrogram(waveform[i], ...) when iterating a batch

Example fix

// before
specs = spectrogram(batch_waveforms, window, 400, 160)  # ValueError: shape is (4, 16000)

// after
specs = spectrogram_batch(list(batch_waveforms), window, 400, 160)  # or loop: spectrogram(batch_waveforms[i], ...)

waveform = np.asarray(waveform)
if waveform.ndim != 1:
    if waveform.ndim == 2 and 1 in waveform.shape:
        waveform = waveform.reshape(-1)
    else:
        raise ValueError(f"Expected 1-D mono waveform, got shape {waveform.shape}")
spec = spectrogram(waveform, window, frame_length, hop_length)

def is_mono_1d(waveform) -> bool:
    import numpy as np
    return np.asarray(waveform).ndim == 1

try:
    spec = spectrogram(waveform, window, frame_length, hop_length)
except ValueError as e:
    if "must have only one dimension" in str(e):
        w = np.asarray(waveform)
        spec = spectrogram(w.reshape(-1) if w.ndim == 2 and 1 in w.shape else w.mean(axis=-1), window, frame_length, hop_length)
    else:
        raise

When it happens

Trigger: Passing np.random.rand(4, 16000) (a batch) or a stereo file loaded as (2, N) to `spectrogram`; feeding processor output that keeps a batch dimension; forgetting to index waveform[i] when looping over a batch manually.

Common situations: Loading stereo audio with soundfile/librosa (shape (N, 2)) without converting to mono; feeding model-batched tensors into a single-audio path; datasets that yield (1, N) arrays.

Related errors

• Unknown window function '{name}'
• Length of the window ({window_length}) may not be larger tha
• frame_length ({frame_length}) may not be larger than fft_len
• Length of the window ({window_length}) must equal frame_leng
• hop_length must be greater than zero

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/8b9a468e5da79fab. Report an issue: GitHub.