{"record":{"id":"de38048bf78594f1","repo":"huggingface/transformers","slug":"frame-length-frame-length-may-not-be-larger-th","errorCode":null,"errorMessage":"frame_length ({frame_length}) may not be larger than fft_length ({fft_length})","messagePattern":"frame_length \\((.+?)\\) may not be larger than fft_length \\((.+?)\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":933,"sourceCode":"            peak value and the smallest value will never be more than 80 dB. Must be greater than zero.\n        remove_dc_offset (`bool`, *optional*):\n            Subtract mean from waveform on each frame, applied before pre-emphasis. This should be set to `true` in\n            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        )","sourceCodeStart":915,"sourceCodeEnd":951,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L915-L951","documentation":"Thrown by `spectrogram` when `frame_length > fft_length` (fft_length defaults to frame_length when None). The STFT pads each frame to fft_length before the FFT; a frame longer than the FFT buffer would truncate data, so the invariant frame_length <= fft_length is enforced up front.","triggerScenarios":"Calling `spectrogram(waveform, window, frame_length=512, hop_length=..., fft_length=400)`. Also hit when a feature extractor computes fft_length independently (e.g. as the next power of two of a smaller value) while frame_length stays large.","commonSituations":"Configs where n_fft was lowered but frame_length not updated; porting from toolkits where fft_length is inferred differently; manually tuning hop/frame/fft parameters of a Whisper-style feature extractor.","solutions":["Set fft_length >= frame_length (commonly fft_length == frame_length or the next power of two)","If fft_length was meant to be derived, use `next_power_of_two(frame_length)` from the same module","Re-check the processor config so frame_length and fft_length agree"],"exampleFix":"// before\nspec = spectrogram(waveform, window, frame_length=512, hop_length=128, fft_length=400)  # ValueError\n\n// after\nspec = spectrogram(waveform, window, frame_length=400, hop_length=128, fft_length=512)","handlingStrategy":"validation","validationCode":"fft_length = fft_length or frame_length\nassert frame_length <= fft_length, f\"frame_length ({frame_length}) must be <= fft_length ({fft_length})\"\nspec = spectrogram(waveform, window, frame_length, hop_length, fft_length=fft_length)","typeGuard":"def frame_fits_fft(frame_length: int, fft_length) -> bool:\n    return fft_length is None or frame_length <= fft_length","tryCatchPattern":"try:\n    spec = spectrogram(waveform, window, frame_length, hop_length, fft_length=fft_length)\nexcept ValueError as e:\n    if \"may not be larger than fft_length\" in str(e):\n        spec = spectrogram(waveform, window, frame_length, hop_length, fft_length=frame_length)\n    else:\n        raise","preventionTips":["Leave fft_length=None so it defaults to frame_length","When specifying both, derive fft from frame (e.g. next power of two), never smaller","Keep n_fft-style config keys in sync with frame_length"],"tags":["audio","stft","argument-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}