{"record":{"id":"8b9a468e5da79fab","repo":"huggingface/transformers","slug":"input-waveform-must-have-only-one-dimension-shape","errorCode":null,"errorMessage":"Input waveform must have only one dimension, shape is {waveform.shape}","messagePattern":"Input waveform must have only one dimension, shape is (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":942,"sourceCode":"        `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:\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)","sourceCodeStart":924,"sourceCodeEnd":960,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L924-L960","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Squeeze to 1-D first: waveform = np.asarray(waveform).squeeze() or waveform = waveform.mean(axis=...) for stereo","For batches, use `spectrogram_batch(waveform_list, ...)` instead of `spectrogram`","Index the individual sample: spectrogram(waveform[i], ...) when iterating a batch"],"exampleFix":"// before\nspecs = spectrogram(batch_waveforms, window, 400, 160)  # ValueError: shape is (4, 16000)\n\n// after\nspecs = spectrogram_batch(list(batch_waveforms), window, 400, 160)  # or loop: spectrogram(batch_waveforms[i], ...)","handlingStrategy":"type-guard","validationCode":"waveform = np.asarray(waveform)\nif waveform.ndim != 1:\n    if waveform.ndim == 2 and 1 in waveform.shape:\n        waveform = waveform.reshape(-1)\n    else:\n        raise ValueError(f\"Expected 1-D mono waveform, got shape {waveform.shape}\")\nspec = spectrogram(waveform, window, frame_length, hop_length)","typeGuard":"def is_mono_1d(waveform) -> bool:\n    import numpy as np\n    return np.asarray(waveform).ndim == 1","tryCatchPattern":"try:\n    spec = spectrogram(waveform, window, frame_length, hop_length)\nexcept ValueError as e:\n    if \"must have only one dimension\" in str(e):\n        w = np.asarray(waveform)\n        spec = spectrogram(w.reshape(-1) if w.ndim == 2 and 1 in w.shape else w.mean(axis=-1), window, frame_length, hop_length)\n    else:\n        raise","preventionTips":["Squeeze batch/channel dims right after loading audio","Average stereo channels to mono before feature extraction","Use spectrogram_batch for lists of waveforms"],"tags":["audio","stft","shape-error"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}