"""MiniMax H3 temporal-grid helpers.""" from __future__ import annotations from dataclasses import dataclass from fractions import Fraction from .constants import AUDIO_LATENT_FPS, FPS, FRAME_PER_TOKEN _AUDIO_TICKS_PER_FRAME = Fraction(int(AUDIO_LATENT_FPS), int(FPS)) @dataclass(frozen=True, slots=True) class ExtensionShape: context_frames: int requested_new_frames: int total_frames: int net_new_frames: int video_latent_t: int audio_latent_t: int @property def actual_extend_seconds(self) -> float: return self.net_new_frames / FPS @dataclass(frozen=True, slots=True) class AVContextWindow: source_frame_count: int context_frames: int video_start_slot: int video_stop_slot: int audio_start_tick: int audio_stop_tick: int audio_grid_offset: float @property def audio_steps(self) -> int: return self.audio_stop_tick - self.audio_start_tick def is_valid_frame_count(frame_count: int) -> bool: return frame_count >= 5 and frame_count % 17 == 5 def align_frame_count_up(frame_count: int) -> int: n = max(5, int(frame_count)) remainder = (n - 5) % 17 return n if remainder == 0 else n + (17 - remainder) def align_frame_count_nearest(frame_count: int, *, minimum: int = 5) -> int: target = max(int(frame_count), int(minimum), 5) min_valid = align_frame_count_up(minimum) k_floor = max(0, (target - 5) // 17) low = max(5 + 17 * k_floor, min_valid) high = max(low + 17, min_valid) return low if abs(target - low) < abs(high - target) else high def video_latent_t(frame_count: int) -> int: if not is_valid_frame_count(frame_count): raise ValueError(f"H3 frame count must satisfy 17k+5; got {frame_count}") return 2 if frame_count <= 5 else ((frame_count - 5) // 17) * 5 + 2 def pixel_frames_for_latent_t(latent_t: int) -> int: if int(latent_t) < 1: raise ValueError("video latent T must be positive") return sum(FRAME_PER_TOKEN[index % 5] for index in range(int(latent_t))) def latent_slot_offsets(latent_t: int) -> tuple[int, ...]: if int(latent_t) < 1: raise ValueError("video latent T must be positive") out: list[int] = [] cursor = 0 for index in range(int(latent_t)): out.append(cursor) cursor += FRAME_PER_TOKEN[index % 5] return tuple(out) def context_slots(context_frames: int) -> int: target = int(context_frames) for slots in range(1, 256): frames = pixel_frames_for_latent_t(slots) if frames == target: return slots if frames > target: break raise ValueError( f"context_frames={context_frames} is not representable; use 5, 22, or 39" ) def audio_latent_t(frame_count: int) -> int: return int(round(Fraction(int(frame_count)) * _AUDIO_TICKS_PER_FRAME)) def audio_grid_offset(frame_count: int, actual_audio_t: int) -> float: """Signed audio-grid end offset in 40 Hz latent steps. Native H3 uses ``round(duration * 40)``. Depending on the valid 17k+5 frame count, the audio grid can end up to half a latent step before or after the exact video end. Keeping the sign is required for sample-accurate continuation placement. """ value = Fraction(int(actual_audio_t)) - Fraction(int(frame_count)) * _AUDIO_TICKS_PER_FRAME value = float(value) return 0.0 if abs(value) < 1e-9 else value # Backward-compatible public name used by state schema v1. def audio_overhang(frame_count: int, actual_audio_t: int) -> float: return audio_grid_offset(frame_count, actual_audio_t) def audio_latent_t_from_grid_offset(frame_count: int, grid_offset: float) -> int: """Recover the actual source audio-grid end without guessing its phase.""" exact_end = float(Fraction(int(frame_count)) * _AUDIO_TICKS_PER_FRAME) candidate = int(round(exact_end + float(grid_offset))) recovered = audio_grid_offset(int(frame_count), candidate) if abs(recovered - float(grid_offset)) > 1e-6: raise ValueError( "source audio-grid phase cannot be recovered from frame count and signed offset" ) return candidate def make_av_context_window( source_frame_count: int, actual_audio_t: int, context_frames: int, ) -> AVContextWindow: """Resolve a raw AV tail on the native 5-step video and 40/24 audio grids.""" source_frames = int(source_frame_count) context = int(context_frames) if not is_valid_frame_count(source_frames): raise ValueError( f"source_frame_count={source_frames} is not on the native H3 17k+5 grid" ) if context not in (5, 22, 39) or context > source_frames: raise ValueError(f"unsupported {context}-frame context for {source_frames} source frames") source_video_t = video_latent_t(source_frames) context_video_t = context_slots(context) video_start = source_video_t - context_video_t if video_start < 0 or video_start % len(FRAME_PER_TOKEN): raise ValueError( "video context tail does not begin at a uniquely recoverable H3 latent-cycle phase" ) audio_stop = int(actual_audio_t) grid_offset = audio_grid_offset(source_frames, audio_stop) if not (-0.500001 <= grid_offset <= 0.500001): raise ValueError(f"source audio-grid offset {grid_offset:.6f} is outside [-0.5,0.5]") audio_steps = audio_latent_t(context) audio_start = audio_stop - audio_steps if audio_start < 0: raise ValueError("source audio latent is too short for the requested context") return AVContextWindow( source_frame_count=source_frames, context_frames=context, video_start_slot=video_start, video_stop_slot=source_video_t, audio_start_tick=audio_start, audio_stop_tick=audio_stop, audio_grid_offset=grid_offset, ) def make_extension_shape(context_frames: int, extend_seconds: float) -> ExtensionShape: context_frames = int(context_frames) context_slots(context_frames) requested_new = max(1, int(round(float(extend_seconds) * FPS))) total = align_frame_count_nearest( context_frames + requested_new, minimum=context_frames + 1 ) net = total - context_frames if net < 1: raise RuntimeError("computed continuation contains no new frames") return ExtensionShape( context_frames=context_frames, requested_new_frames=requested_new, total_frames=total, net_new_frames=net, video_latent_t=video_latent_t(total), audio_latent_t=audio_latent_t(total), ) def largest_context_capacity(frame_count: int) -> int: """Largest supported continuation profile contained in ``frame_count``.""" available = int(frame_count) for capacity in (39, 22, 5): if available >= capacity: return capacity raise ValueError( f"at least 5 retained frames are required for a continuation state; got {available}" ) def run_temporal_self_test() -> None: expected = { 5: (2, (0, 1)), 22: (7, (0, 1, 5, 9, 13, 17, 18)), 39: (12, (0, 1, 5, 9, 13, 17, 18, 22, 26, 30, 34, 35)), } for frames, (slots, offsets) in expected.items(): assert context_slots(frames) == slots assert latent_slot_offsets(slots) == offsets assert pixel_frames_for_latent_t(slots) == frames shape = make_extension_shape(22, 5.0) assert (shape.total_frames, shape.net_new_frames) == (141, 119) assert (shape.video_latent_t, shape.audio_latent_t) == (42, 235) window = make_av_context_window(141, 235, 22) assert (window.video_start_slot, window.video_stop_slot) == (35, 42) assert (window.audio_start_tick, window.audio_stop_tick) == (198, 235)