{"record":{"id":"c61ec749b18cc05c","repo":"huggingface/transformers","slug":"complex-valued-input-waveforms-are-not-currently-s","errorCode":null,"errorMessage":"Complex-valued input waveforms are not currently supported","messagePattern":"Complex-valued input waveforms are not currently supported","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":945,"sourceCode":"    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:\n        padding = [(int(frame_length // 2), int(frame_length // 2))]\n        waveform = np.pad(waveform, padding, mode=pad_mode)\n\n    # promote to float64, since np.fft uses float64 internally\n    waveform = waveform.astype(np.float64)\n    window = window.astype(np.float64)\n\n    # split waveform into frames of frame_length size\n    num_frames = int(1 + np.floor((waveform.size - frame_length) / hop_length))","sourceCodeStart":927,"sourceCodeEnd":963,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L927-L963","documentation":"Thrown by `spectrogram` when the input waveform is complex-valued (np.iscomplexobj is true, including complex64/complex128). The implementation casts the waveform to float64 before windowing and FFT, and the downstream mel/log path assumes real inputs, so complex waveforms (e.g. from an inverse STFT or IQ data) are unsupported and rejected explicitly.","triggerScenarios":"Passing a complex array produced by np.fft.ifft/istft reconstruction, analytic-signal computations (hilbert transform), or RF/IQ data; also a real array stored with a complex dtype containing zero imaginary parts.","commonSituations":"Griffin-Lim style reconstruction pipelines feeding complex frames back into `spectrogram`; scipy.signal.hilbert output; data loaded with dtype=np.complex128 from MATLAB or HDF5 files.","solutions":["Take the real part before calling: spectrogram(waveform.real.astype(np.float64), ...)","If magnitude is what you need, use np.abs(waveform) instead","Check upstream processing that introduced a complex dtype and cast there"],"exampleFix":"// before\nspec = spectrogram(complex_waveform, window, 400, 160)  # ValueError\n\n// after\nspec = spectrogram(complex_waveform.real.astype(np.float64), window, 400, 160)","handlingStrategy":"type-guard","validationCode":"if np.iscomplexobj(waveform):\n    waveform = waveform.real.astype(np.float64)\nspec = spectrogram(waveform, window, frame_length, hop_length)","typeGuard":"def is_real_waveform(waveform) -> bool:\n    import numpy as np\n    return not np.iscomplexobj(waveform)","tryCatchPattern":"try:\n    spec = spectrogram(waveform, window, frame_length, hop_length)\nexcept ValueError as e:\n    if \"Complex-valued\" in str(e):\n        spec = spectrogram(np.asarray(waveform).real.astype(np.float64), window, frame_length, hop_length)\n    else:\n        raise","preventionTips":["Cast to float at the boundary: waveform.real.astype(np.float64)","Avoid feeding istft/hilbert outputs directly into spectrogram","Check dtypes when loading from HDF5/MAT files that store complex"],"tags":["audio","stft","dtype-error"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}