huggingface/transformers · error · ValueError

Length of the window ({window_length}) must equal frame_leng

Error message

Length of the window ({window_length}) must equal frame_length ({frame_length})

What it means

Thrown by `spectrogram` when `len(window) != frame_length`. The implementation frames the waveform into frame_length chunks and multiplies element-wise by the window, so the window must match the frame size exactly. Windows produced by `window_function(frame_length, ...)` satisfy this automatically; mismatched hand-built windows do not.

Source

Thrown at src/transformers/audio_utils.py:936

            order to get the same results as `torchaudio.compliance.kaldi.fbank` when computing mel filters.
        dtype (`np.dtype`, *optional*, defaults to `np.float32`):
            Data type of the spectrogram tensor. If `power` is None, this argument is ignored and the dtype will be
            `np.complex64`.

    Returns:
        `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:

View on GitHub (pinned to a597f97485)

Solutions

1. Regenerate the window at the same length: `window_function(frame_length, name=..., periodic=...)`
2. Or build it as np.hanning(frame_length) / np.ones(frame_length) to match exactly
3. If the processor caches a window, invalidate the cache after changing frame_length

Example fix

// before
window = np.hanning(256)
spec = spectrogram(waveform, window, frame_length=400, hop_length=160)  # ValueError

// after
window = window_function(400, name="hann")
spec = spectrogram(waveform, window, frame_length=400, hop_length=160)

if len(window) != frame_length:
    raise ValueError(f"len(window)={len(window)} != frame_length={frame_length}; regenerate the window")
spec = spectrogram(waveform, window, frame_length, hop_length)

def window_matches_frame(window: np.ndarray, frame_length: int) -> bool:
    return len(window) == frame_length

try:
    spec = spectrogram(waveform, window, frame_length, hop_length)
except ValueError as e:
    if "must equal frame_length" in str(e):
        from transformers.audio_utils import window_function
        window = window_function(frame_length, name="hann")
        spec = spectrogram(waveform, window, frame_length, hop_length)
    else:
        raise

When it happens

Trigger: Passing a window of a different length than frame_length, e.g. window=np.hanning(256) with frame_length=400; forgetting that `window_function(window_length, frame_length=L)` returns a zero-padded array of length L only when frame_length is given.

Common situations: Building the window manually with numpy/scipy instead of `window_function`; reusing one window across feature extractors with different n_fft/frame sizes; changing frame_length in a config without regenerating the cached window.

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
• hop_length must be greater than zero
• mel_scale should be one of "htk", "slaney" or "kaldi".

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