{"record":{"id":"7535bf6344049a97","repo":"sgl-project/sglang","slug":"reference-audio-sample-rate-must-be-positive","errorCode":null,"errorMessage":"reference audio sample rate must be positive","messagePattern":"reference audio sample rate must be positive","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py","lineNumber":236,"sourceCode":"    stereo. Video-bearing references first extract 44.1 kHz stereo PCM. The\n    audio VAE boundary then performs the single 32 kHz resample below. ffmpeg\n    writes bounded interleaved float PCM directly to stdout, avoiding a\n    temporary lossless file plus a second decode.\n    \"\"\"\n\n    import numpy as np\n\n    if max_duration_seconds is not None:\n        max_duration_seconds = float(max_duration_seconds)\n        if not math.isfinite(max_duration_seconds) or max_duration_seconds <= 0:\n            raise ValueError(\"reference audio duration bound must be positive\")\n    start_time_seconds = float(start_time_seconds)\n    if not math.isfinite(start_time_seconds) or start_time_seconds < 0:\n        raise ValueError(\"reference audio start time must be non-negative\")\n\n    if material_chain == \"audio\":\n        if source_sample_rate is None or int(source_sample_rate) <= 0:\n            raise ValueError(\"reference audio sample rate must be positive\")\n        source_rate = int(source_sample_rate)\n    elif material_chain in {\n        \"video.reference_preserve\",\n        \"video_audio.reference_preserve\",\n    }:\n        source_rate = 44100\n    else:\n        raise ValueError(\n            f\"unsupported MiniMax H3 audio material chain {material_chain!r}\"\n        )\n\n    command = [\n        \"ffmpeg\",\n        \"-v\",\n        \"error\",\n    ]\n    if start_time_seconds > 0:\n        command += [\"-ss\", f\"{start_time_seconds:.9g}\"]","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/reference_encoding.py#L218-L254","documentation":"For pure-audio materials, _load_waveform requires an explicit positive source sample rate (there is no default for the 'audio' chain). The rate is needed to decide whether resampling to MINIMAX_H3_AUDIO_SAMPLE_RATE is required.","triggerScenarios":"Calling minimax_h3_encode_reference_audio_rows with material_chain='audio' and source_sample_rate=None, 0, or negative; video chains default to 44100 and do not hit this.","commonSituations":"Building audio materials without probing the file's sample rate, or a probe step that failed silently and left the field None.","solutions":["Probe the file (e.g. with torchaudio.info or ffprobe) and set source_sample_rate before encoding","Default to a sane value like 44100 or 48000 only if you know the corpus","Fix the material-builder code path that omits the rate for audio chains"],"exampleFix":"// before\nmaterial.source_sample_rate = None  # audio chain -> ValueError\n\n// after\ninfo = torchaudio.info(path)\nmaterial.source_sample_rate = info.sample_rate","handlingStrategy":"type-guard","validationCode":"def has_audio_rate(material) -> bool:\n    return material.material_chain != \"audio\" or (\n        material.source_sample_rate is not None and int(material.source_sample_rate) > 0\n    )","typeGuard":"def valid_audio_material(m) -> bool:\n    return m.material_chain != \"audio\" or (m.source_sample_rate or 0) > 0","tryCatchPattern":null,"preventionTips":["Probe sample rate with torchaudio.info when building audio materials","Treat a failed probe as a material-build failure, not a silent None"],"tags":["minimax-h3","audio","sample-rate"],"backgroundTag":"missing-sample-rate","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}