{"record":{"id":"ace1924374bd816b","repo":"unslothai/unsloth","slug":"that-reference-audio-decoded-to-no-samples","errorCode":null,"errorMessage":"That reference audio decoded to no samples.","messagePattern":"That reference audio decoded to no samples\\.","errorType":"validation","errorClass":"ValueError","httpStatus":400,"severity":"error","filePath":"studio/backend/core/inference/video_minimax_h3.py","lineNumber":447,"sourceCode":"    with av.open(io.BytesIO(blob)) as container:\n        if container.streams.audio:\n            waveform, sample_rate = _decode_audio_stream(container, np)\n    return frames, waveform, sample_rate\n\n\ndef decode_h3_reference_audio(blob: bytes) -> tuple[Any, int]:\n    \"\"\"Decode one uploaded audio file to a float32 ``(samples, channels)`` waveform + its rate.\"\"\"\n    import io\n\n    import av\n    import numpy as np\n\n    with av.open(io.BytesIO(blob)) as container:\n        if not container.streams.audio:\n            raise ValueError(\"That reference file carries no audio track.\")\n        waveform, sample_rate = _decode_audio_stream(container, np)\n    if waveform is None:\n        raise ValueError(\"That reference audio decoded to no samples.\")\n    return waveform, sample_rate\n\n\ndef _decode_audio_stream(container: Any, np: Any) -> tuple[Optional[Any], Optional[int]]:\n    \"\"\"The container's first audio stream as float32 ``(samples, channels)`` at its own rate.\n\n    Bounded while decoding, for the reason the video path above is: the encoded size says almost\n    nothing about the decoded size. A 32 MiB request-limit MP3 is over half an hour of audio, which\n    expands to ~1.9 GB of float32 here and doubles again in ``np.concatenate``, and three\n    references are accepted per request. H3's reference window is\n    ``H3_REF_VIDEO_MAX_SECONDS`` anyway, so anything past it is unusable rather than merely large:\n    refuse it with the same message the video guard uses instead of decoding it first.\"\"\"\n    import av\n\n    stream = container.streams.audio[0]\n    sample_rate = int(stream.codec_context.sample_rate or 48_000)\n    # One resampler pass gives interleaved float32 whatever the source layout/format was.\n    resampler = av.AudioResampler(format = \"flt\", layout = stream.layout.name, rate = sample_rate)","sourceCodeStart":429,"sourceCodeEnd":465,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video_minimax_h3.py#L429-L465","documentation":"After _decode_audio_stream returns, decode_h3_reference_audio raises ValueError when the decoded waveform is None — the audio track existed (streams.audio was non-empty) but decoding produced no samples. _decode_audio_stream returns (None, None) when its chunk list is empty, which happens with headers-only audio streams or fully unparseable payloads.","triggerScenarios":"An audio stream with zero decodable packets (interrupted write, truncated upload); codec the PyAV build cannot decode so every packet fails; container with an audio track header but no data.","commonSituations":"Truncated uploads from dropped connections; re-muxed files with dead audio tracks; exotic codecs in user uploads.","solutions":["Re-export the audio to a standard format: ffmpeg -i in.m4a -c:a libmp3lame ref.mp3 (fails loudly if truly dead).","Verify decodability first: ffmpeg -v error -i ref.mp3 -f null -.","Re-upload from the original source file rather than a partial transfer."],"exampleFix":"# before: truncated upload -> ValueError('decoded to no samples')\n\n# after: validate before upload\nimport subprocess\nok = subprocess.run([\"ffmpeg\", \"-v\", \"error\", \"-i\", \"ref.mp3\", \"-f\", \"null\", \"-\"]).returncode == 0\nif not ok:\n    raise ValueError(\"audio file is not decodable; re-export it\")","handlingStrategy":"validation","validationCode":"import av, io\n\ndef audio_yields_samples(blob: bytes) -> bool:\n    with av.open(io.BytesIO(blob)) as c:\n        if not c.streams.audio:\n            return False\n        return next(iter(c.decode(audio=0)), None) is not None","typeGuard":null,"tryCatchPattern":"try:\n    wf, sr = decode_h3_reference_audio(blob)\nexcept ValueError as e:\n    if str(e) == \"That reference audio decoded to no samples.\":\n        return HTTPException(400, \"audio track is empty; re-export the file\") from e\n    raise","preventionTips":["Decode one audio frame as a sanity probe on upload.","Re-export through ffmpeg to rewrite a clean container for suspect files.","Distinguish this (track exists, no samples) from error 517 (no track) in user messaging."],"tags":["audio","minimax-h3","upload","corrupt-file","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}