huggingface/transformers · error · ValueError

Invalid input type. Must be a single audio or a list of audi

Error message

Invalid input type. Must be a single audio or a list of audio

What it means

Thrown by `make_list_of_audio` in transformers' audio_utils when the `audio` argument is neither a single valid audio object (numpy array, torch tensor, or list/tuple of floats) nor a non-empty list/tuple whose every element is valid audio. The function normalizes user input into a list of audio before preprocessing, so any other type is rejected early. Valid audio is defined by `is_valid_audio`: np.ndarray, torch.Tensor, or a list/tuple whose first element is a float.

Source

Thrown at src/transformers/audio_utils.py:421

    audio: list[AudioInput] | AudioInput,
) -> AudioInput:
    """
    Ensure that the output is a list of audio.
    Args:
        audio (`Union[list[AudioInput], AudioInput]`):
            The input audio.
    Returns:
        list: A list of audio.
    """
    # If it's a list of audios, it's already in the right format
    if isinstance(audio, (list, tuple)) and is_valid_list_of_audio(audio):
        return audio

    # If it's a single audio, convert it to a list of
    if is_valid_audio(audio):
        return [audio]

    raise ValueError("Invalid input type. Must be a single audio or a list of audio")


def make_list_of_audio_chat_template(
    audio: list[AudioInput] | AudioInput | str | list[str],
) -> AudioInput:
    """
    Ensure that the output is a list of audio. Unlike `make_list_of_audio`, this function also accepts a URL string or
    local path, as accepted by chat templates.

    Args:
        audio (`Union[list[AudioInput], AudioInput]`):
            The input audio. Can be a URL string, local path, numpy/torch array,  or a list of these.
    Returns:
        list: A list of audio.
    """

    # Handle string inputs
    if isinstance(audio, str):

View on GitHub (pinned to a597f97485)

Solutions

1. Pass a numpy array, torch tensor, or a list of floats (raw samples) instead of a path/URL string
2. If you have a file path or URL, load it first (e.g. with librosa.load or soundfile.read) and pass the resulting array
3. If you are building chat-template style input with paths/URLs, use `make_list_of_audio_chat_template` which accepts strings
4. Ensure the list is non-empty and every element is itself a valid audio array (no mixed types)
5. Wrap the call in try/except ValueError if audio comes from untrusted user input

Example fix

// before
audio = "sample.wav"
audios = make_list_of_audio(audio)  # ValueError

// after
import soundfile as sf
audio, sr = sf.read("sample.wav")
audios = make_list_of_audio(audio)  # -> [np.ndarray]

import numpy as np
import torch

def is_valid_audio(a):
    return isinstance(a, (np.ndarray, torch.Tensor)) or (isinstance(a, (list, tuple)) and len(a) > 0 and isinstance(a[0], float))

def valid_audio_or_list(audio):
    if is_valid_audio(audio):
        return [audio]
    if isinstance(audio, (list, tuple)) and audio and all(is_valid_audio(a) for a in audio):
        return list(audio)
    raise TypeError("Pass a numpy/torch array or a non-empty list of them (not a path/URL string)")

def is_audio_input_ok(audio) -> bool:
    import numpy as np, torch
    ok = lambda a: isinstance(a, (np.ndarray, torch.Tensor)) or (isinstance(a, (list, tuple)) and a and isinstance(a[0], float))
    return ok(audio) or (isinstance(audio, (list, tuple)) and bool(audio) and all(ok(a) for a in audio))

try:
    audios = make_list_of_audio(audio)
except ValueError as e:
    if "Invalid input type" in str(e):
        raise TypeError(f"audio must be np.ndarray/torch.Tensor or a list of them, got {type(audio)!r}") from e
    raise

When it happens

Trigger: Calling `make_list_of_audio(...)` (directly, or indirectly through an audio processor/preprocessor that accepts audio input) with: a plain Python string URL/path, a dict, None, an empty list, a list mixing strings and arrays, a list of lists of ints, or a PIL/soundfile object.

Common situations: Passing a URL or file path string to a processor feature extractor that expects raw arrays (the chat-template variant `make_list_of_audio_chat_template` accepts strings, this one does not); building chat messages with nested audio; accidentally passing a batched 2-D array of lists; migrating code that previously used strings.

Related errors

• only a single or a list of entries is supported but got type
• mel_scale should be one of "htk", "slaney" or "kaldi".
• norm must be one of None or "slaney"
• Require num_frequency_bins: {num_frequency_bins} >= 2
• Require min_frequency: {min_frequency} <= max_frequency: {ma

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