{"record":{"id":"277aab0c573a3b46","repo":"huggingface/transformers","slug":"length-of-the-window-window-length-must-equal","errorCode":null,"errorMessage":"Length of the window ({window_length}) must equal frame_length ({frame_length})","messagePattern":"Length of the window \\((.+?)\\) must equal frame_length \\((.+?)\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":936,"sourceCode":"            order to get the same results as `torchaudio.compliance.kaldi.fbank` when computing mel filters.\n        dtype (`np.dtype`, *optional*, defaults to `np.float32`):\n            Data type of the spectrogram tensor. If `power` is None, this argument is ignored and the dtype will be\n            `np.complex64`.\n\n    Returns:\n        `nd.array` containing a spectrogram of shape `(num_frequency_bins, length)` for a regular spectrogram or shape\n        `(num_mel_filters, length)` for a mel spectrogram.\n    \"\"\"\n    window_length = len(window)\n\n    if fft_length is None:\n        fft_length = frame_length\n\n    if frame_length > fft_length:\n        raise ValueError(f\"frame_length ({frame_length}) may not be larger than fft_length ({fft_length})\")\n\n    if window_length != frame_length:\n        raise ValueError(f\"Length of the window ({window_length}) must equal frame_length ({frame_length})\")\n\n    if hop_length <= 0:\n        raise ValueError(\"hop_length must be greater than zero\")\n\n    if waveform.ndim != 1:\n        raise ValueError(f\"Input waveform must have only one dimension, shape is {waveform.shape}\")\n\n    if np.iscomplexobj(waveform):\n        raise ValueError(\"Complex-valued input waveforms are not currently supported\")\n\n    if power is None and mel_filters is not None:\n        raise ValueError(\n            \"You have provided `mel_filters` but `power` is `None`. Mel spectrogram computation is not yet supported for complex-valued spectrogram.\"\n            \"Specify `power` to fix this issue.\"\n        )\n\n    # center pad the waveform\n    if center:","sourceCodeStart":918,"sourceCodeEnd":954,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L918-L954","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Regenerate the window at the same length: `window_function(frame_length, name=..., periodic=...)`","Or build it as np.hanning(frame_length) / np.ones(frame_length) to match exactly","If the processor caches a window, invalidate the cache after changing frame_length"],"exampleFix":"// before\nwindow = np.hanning(256)\nspec = spectrogram(waveform, window, frame_length=400, hop_length=160)  # ValueError\n\n// after\nwindow = window_function(400, name=\"hann\")\nspec = spectrogram(waveform, window, frame_length=400, hop_length=160)","handlingStrategy":"validation","validationCode":"if len(window) != frame_length:\n    raise ValueError(f\"len(window)={len(window)} != frame_length={frame_length}; regenerate the window\")\nspec = spectrogram(waveform, window, frame_length, hop_length)","typeGuard":"def window_matches_frame(window: np.ndarray, frame_length: int) -> bool:\n    return len(window) == frame_length","tryCatchPattern":"try:\n    spec = spectrogram(waveform, window, frame_length, hop_length)\nexcept ValueError as e:\n    if \"must equal frame_length\" in str(e):\n        from transformers.audio_utils import window_function\n        window = window_function(frame_length, name=\"hann\")\n        spec = spectrogram(waveform, window, frame_length, hop_length)\n    else:\n        raise","preventionTips":["Always create windows with window_function(frame_length, ...) at the point of use","Invalidate cached windows when frame_length changes","Never reuse a window across extractors with different frame sizes"],"tags":["audio","stft","argument-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}