mudler/LocalAI · error · ValueError

request needs {segments} avatar segments, but max_segments i

Error message

request needs {segments} avatar segments, but max_segments is {max_segments}; trim the audio or raise the model's max_segments option

What it means

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.

Source

Thrown at backend/python/longcat-video/backend.py:789

            all_frames.extend(current_video[conditioning_frames:])

        self._save_avatar_video(all_frames, request.audio, request.dst, avatar_fps)

    def _avatar_segments(self, request, params, audio_duration):
        if "num_segments" in params:
            segments = require_int(
                params["num_segments"],
                "num_segments",
                minimum=1,
            )
        elif request.num_frames > 0:
            segments = avatar_segments_for_frames(request.num_frames)
        else:
            segments = avatar_segments_for_duration(audio_duration)

        max_segments = self.options["max_segments"]
        if segments > max_segments:
            raise ValueError(
                f"request needs {segments} avatar segments, but max_segments is {max_segments}; "
                "trim the audio or raise the model's max_segments option"
            )
        return segments

    def _resolution(self, params):
        resolution = str(params.get("resolution", self.options["resolution"])).lower()
        if resolution not in {"480p", "720p"}:
            raise ValueError("resolution must be 480p or 720p")
        return resolution

    def _frames_to_pil(self, frames):
        images = []
        for frame in frames:
            array = self.np.asarray(frame)
            if self.np.issubdtype(array.dtype, self.np.floating):
                array = self.np.clip(array, 0.0, 1.0) * 255
            images.append(self.Image.fromarray(array.astype(self.np.uint8)))

View on GitHub (pinned to 44413a9d06)

Solutions

1. Trim/split the audio so the needed segments fit within the current max_segments
2. Or raise the option at LoadModel time: options: max_segments: 16 (accepts the longer runtime and memory use)
3. For very long audio, chunk it client-side into multiple requests and stitch the outputs

Example fix

# before
options:
  max_segments: 8  # default, audio is 60s

# after
options:
  max_segments: 20

SEGMENT_FRAMES, COND_FRAMES, AVATAR_FPS = 93, 13, 25

def segments_needed(audio_seconds: float = 0.0, num_frames: int = 0) -> int:
    if num_frames > 0:
        return max(1, math.ceil((num_frames - SEGMENT_FRAMES) / (SEGMENT_FRAMES - COND_FRAMES)) + 1)
    return max(1, math.ceil((audio_seconds * AVATAR_FPS - SEGMENT_FRAMES) / (SEGMENT_FRAMES - COND_FRAMES)) + 1)

def max_audio_seconds(max_segments: int = 8) -> float:
    return max_segments * (SEGMENT_FRAMES - COND_FRAMES) / AVATAR_FPS

try:
    stub.GenerateVideo(req)
except grpc.RpcError as e:
    details = e.details() or ""
    if "max_segments" in details:
        opts["options"]["max_segments"] = 32  # reload with a higher cap, then retry
        stub.LoadModel(opts)
        stub.GenerateVideo(req)
    else:
        raise

When it happens

Trigger: 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.

Common situations: Trying to dub a 60-second clip with default options; raising num_frames for a long animation without adjusting max_segments.

Related errors

• resolution must be 480p or 720p
• base_model must point to a LongCat-Video checkpoint
• audio is required for LongCat-Video-Avatar-1.5
• audio contains no samples
• {name} must be true or false

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/b24d8f6ed457ab33. Report an issue: GitHub.