{"record":{"id":"b24d8f6ed457ab33","repo":"mudler/LocalAI","slug":"request-needs-segments-avatar-segments-but-max","errorCode":null,"errorMessage":"request needs {segments} avatar segments, but max_segments is {max_segments}; trim the audio or raise the model's max_segments option","messagePattern":"request needs (.+?) avatar segments, but max_segments is (.+?); trim the audio or raise the model's max_segments option","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"backend/python/longcat-video/backend.py","lineNumber":789,"sourceCode":"            all_frames.extend(current_video[conditioning_frames:])\n\n        self._save_avatar_video(all_frames, request.audio, request.dst, avatar_fps)\n\n    def _avatar_segments(self, request, params, audio_duration):\n        if \"num_segments\" in params:\n            segments = require_int(\n                params[\"num_segments\"],\n                \"num_segments\",\n                minimum=1,\n            )\n        elif request.num_frames > 0:\n            segments = avatar_segments_for_frames(request.num_frames)\n        else:\n            segments = avatar_segments_for_duration(audio_duration)\n\n        max_segments = self.options[\"max_segments\"]\n        if segments > max_segments:\n            raise ValueError(\n                f\"request needs {segments} avatar segments, but max_segments is {max_segments}; \"\n                \"trim the audio or raise the model's max_segments option\"\n            )\n        return segments\n\n    def _resolution(self, params):\n        resolution = str(params.get(\"resolution\", self.options[\"resolution\"])).lower()\n        if resolution not in {\"480p\", \"720p\"}:\n            raise ValueError(\"resolution must be 480p or 720p\")\n        return resolution\n\n    def _frames_to_pil(self, frames):\n        images = []\n        for frame in frames:\n            array = self.np.asarray(frame)\n            if self.np.issubdtype(array.dtype, self.np.floating):\n                array = self.np.clip(array, 0.0, 1.0) * 255\n            images.append(self.Image.fromarray(array.astype(self.np.uint8)))","sourceCodeStart":771,"sourceCodeEnd":807,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/python/longcat-video/backend.py#L771-L807","documentation":"ValueError from _avatar_segments(): the number of avatar segments needed (from num_segments param, or derived from num_frames, or from audio duration) exceeds the model option max_segments (default 8). Each segment generates 93 frames at 25 fps with 13 conditioning frames of overlap, so long audio expands into many sequential diffusion runs; the cap bounds worst-case latency and VRAM-time, and the error tells you to trim audio or raise the cap.","triggerScenarios":"Requesting generation of audio longer than roughly max_segments*(93-13)/25 seconds (8 segments ≈ 25.6 s at default); passing num_frames larger than max_segments*80 frames; explicit num_segments param above max_segments.","commonSituations":"Trying to dub a 60-second clip with default options; raising num_frames for a long animation without adjusting max_segments.","solutions":["Trim/split the audio so the needed segments fit within the current max_segments","Or raise the option at LoadModel time: options: max_segments: 16 (accepts the longer runtime and memory use)","For very long audio, chunk it client-side into multiple requests and stitch the outputs"],"exampleFix":"# before\noptions:\n  max_segments: 8  # default, audio is 60s\n\n# after\noptions:\n  max_segments: 20","handlingStrategy":"validation","validationCode":"SEGMENT_FRAMES, COND_FRAMES, AVATAR_FPS = 93, 13, 25\n\ndef segments_needed(audio_seconds: float = 0.0, num_frames: int = 0) -> int:\n    if num_frames > 0:\n        return max(1, math.ceil((num_frames - SEGMENT_FRAMES) / (SEGMENT_FRAMES - COND_FRAMES)) + 1)\n    return max(1, math.ceil((audio_seconds * AVATAR_FPS - SEGMENT_FRAMES) / (SEGMENT_FRAMES - COND_FRAMES)) + 1)\n\ndef max_audio_seconds(max_segments: int = 8) -> float:\n    return max_segments * (SEGMENT_FRAMES - COND_FRAMES) / AVATAR_FPS","typeGuard":null,"tryCatchPattern":"try:\n    stub.GenerateVideo(req)\nexcept grpc.RpcError as e:\n    details = e.details() or \"\"\n    if \"max_segments\" in details:\n        opts[\"options\"][\"max_segments\"] = 32  # reload with a higher cap, then retry\n        stub.LoadModel(opts)\n        stub.GenerateVideo(req)\n    else:\n        raise","preventionTips":["Compute expected segments from audio length before sending; trim or chunk audio accordingly","Set max_segments at load time to match your longest supported clip"],"tags":["python","longcat-video","configuration","audio","validation"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}