sgl-project/sglang · error · ValueError

Expected decoded audio with 1, 2, or 3 dims, got shape={tupl

Error message

Expected decoded audio with 1, 2, or 3 dims, got shape={tuple(waveform.shape)}

What it means

After the 3-D and 1-D cases, the waveform must end up 2-D [C, T] (channels-first) or be transposable to it; anything with ndim not in {1,2,3} (e.g. 0-D scalar, 4-D+) is rejected because mel-spectrogram computation needs a [C, T] layout.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/joy_echo/memory.py:557

        if waveform.shape[0] != 1:
            raise ValueError(
                f"Expected batch size 1 for decoded audio, got shape={tuple(waveform.shape)}"
            )
        waveform = waveform[0]
    if waveform.ndim == 1:
        waveform = waveform.unsqueeze(0)
    elif (
        waveform.ndim == 2
        and waveform.shape[0] not in {1, 2}
        and waveform.shape[1]
        in {
            1,
            2,
        }
    ):
        waveform = waveform.transpose(0, 1)
    elif waveform.ndim != 2:
        raise ValueError(
            f"Expected decoded audio with 1, 2, or 3 dims, got shape={tuple(waveform.shape)}"
        )

    if waveform.shape[0] == 1:
        waveform = waveform.repeat(2, 1)
    elif waveform.shape[0] > 2:
        waveform = waveform[:2]
    return waveform.contiguous()


class PairedAudioVideoMemoryBank:
    def __init__(self, max_size: int, num_fix_frames: int = 0) -> None:
        self.max_size = int(max_size)
        self.num_fix_frames = max(0, int(num_fix_frames))
        self.memory: list[MemoryEntry] = []

    @staticmethod
    def _prepare_audio_latent(

View on GitHub (pinned to 0132848349)

Solutions

Squeeze to a single waveform: pass waveform.view(-1) for 1-D PCM or [C,T] for multi-channel
If you have framed audio [B,C,F,T], flatten frames back to time: waveform.reshape(C, -1) after selecting the item
Log waveform.ndim and shape before calling to identify the offending upstream stage

Example fix

# before
save_memory_slot(..., audio_waveform=framed)  # framed is [1, 1, F, T]
# after
wave = framed[0, 0].reshape(framed.shape[-2], -1)  # [C, T]
save_memory_slot(..., audio_waveform=wave)

Defensive patterns

Strategy: validation

Validate before calling

if waveform.ndim not in (1, 2, 3):
    raise ValueError(f"unsupported audio rank {waveform.ndim}: pass 1-D PCM or [C,T]/[B,T,C]")

Type guard

def is_supported_waveform(t: torch.Tensor) -> bool:
    return 1 <= t.ndim <= 3

Prevention

Flatten framed/windowed audio back to [C,T] before passing
Add a shape-print debug hook at the audio boundary of your pipeline

When it happens

Trigger: Calling normalize_audio_waveform_for_media with a 0-D tensor, a 4-D batched-window tensor, or a numpy array coerced to an unexpected rank via torch.as_tensor on nested data.

Common situations: Passing already-windowed/framed audio of shape [B, C, F, T]; passing nested lists or a scalar; double-wrapping a waveform (e.g. stacking already-2-D tensors).

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/4eed2c7bccdd47c5. Report an issue: GitHub.