422 lines
16 KiB
Python
422 lines
16 KiB
Python
"""Pure visible-timeline resolution for Experimental temporal refinement."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import hashlib
|
|
import json
|
|
import math
|
|
from collections.abc import Mapping, Sequence
|
|
from dataclasses import dataclass
|
|
from types import MappingProxyType
|
|
from typing import Any
|
|
|
|
from ..temporal import audio_latent_t, latent_slot_offsets, pixel_frames_for_latent_t
|
|
|
|
|
|
MAGIC = "H3_CONTINUUM_REFINE_WINDOW"
|
|
SCHEMA_VERSION = 1
|
|
MODE_TIME_WINDOW = "time_window"
|
|
|
|
|
|
class RefineWindowError(ValueError):
|
|
"""Raised before preparation when a visible time window is invalid."""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class GroupTemporalWindow:
|
|
"""One physical group's immutable temporal mask ranges."""
|
|
|
|
group_index: int
|
|
logical_chunks: tuple[int, ...]
|
|
terminal_merged: bool
|
|
visible_frame_ranges: tuple[tuple[int, int], ...]
|
|
physical_frame_ranges: tuple[tuple[int, int], ...]
|
|
video_slot_ranges: tuple[tuple[int, int], ...]
|
|
audio_tick_ranges: tuple[tuple[int, int], ...]
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class RefineWindow:
|
|
"""One versioned visible-output window with no Tensor or runtime object."""
|
|
|
|
selected_group_indices: tuple[int, ...]
|
|
groups: tuple[GroupTemporalWindow, ...]
|
|
contract: Mapping[str, Any]
|
|
|
|
def group(self, group_index: int) -> GroupTemporalWindow | None:
|
|
for group in self.groups:
|
|
if group.group_index == int(group_index):
|
|
return group
|
|
return None
|
|
|
|
|
|
def _identity(payload: Mapping[str, Any]) -> str:
|
|
encoded = json.dumps(
|
|
dict(payload),
|
|
sort_keys=True,
|
|
separators=(",", ":"),
|
|
).encode("utf-8")
|
|
return hashlib.sha256(encoded).hexdigest()
|
|
|
|
|
|
def _merge_ranges(values: Sequence[tuple[int, int]]) -> tuple[tuple[int, int], ...]:
|
|
ordered = sorted(
|
|
(int(start), int(stop))
|
|
for start, stop in values
|
|
if int(stop) > int(start)
|
|
)
|
|
merged: list[list[int]] = []
|
|
for start, stop in ordered:
|
|
if merged and start <= merged[-1][1]:
|
|
merged[-1][1] = max(merged[-1][1], stop)
|
|
else:
|
|
merged.append([start, stop])
|
|
return tuple((start, stop) for start, stop in merged)
|
|
|
|
|
|
def _indices_to_ranges(indices: Sequence[int]) -> tuple[tuple[int, int], ...]:
|
|
ordered = sorted(set(int(value) for value in indices))
|
|
if not ordered:
|
|
return ()
|
|
ranges: list[tuple[int, int]] = []
|
|
start = previous = ordered[0]
|
|
for value in ordered[1:]:
|
|
if value == previous + 1:
|
|
previous = value
|
|
continue
|
|
ranges.append((start, previous + 1))
|
|
start = previous = value
|
|
ranges.append((start, previous + 1))
|
|
return tuple(ranges)
|
|
|
|
|
|
def _overlaps(
|
|
start: int,
|
|
stop: int,
|
|
ranges: Sequence[tuple[int, int]],
|
|
) -> bool:
|
|
return any(start < range_stop and stop > range_start for range_start, range_stop in ranges)
|
|
|
|
|
|
def _contract_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]:
|
|
if not isinstance(assembly_plan, Mapping):
|
|
raise RefineWindowError("assembly_plan must be a mapping")
|
|
contract = assembly_plan.get("second_pass_contract")
|
|
if not isinstance(contract, Mapping) or contract.get("version") != 1:
|
|
raise RefineWindowError("assembly_plan has no Second Pass contract version 1")
|
|
groups = contract.get("physical_groups")
|
|
if (
|
|
not isinstance(groups, Sequence)
|
|
or isinstance(groups, (str, bytes))
|
|
or not groups
|
|
or not all(isinstance(group, Mapping) for group in groups)
|
|
):
|
|
raise RefineWindowError("assembly_plan has no physical groups")
|
|
return list(groups)
|
|
|
|
|
|
def _logical_chunks(group: Mapping[str, Any], group_index: int) -> tuple[int, ...]:
|
|
values = group.get("logical_chunks")
|
|
if (
|
|
not isinstance(values, Sequence)
|
|
or isinstance(values, (str, bytes))
|
|
or not values
|
|
or any(type(value) is not int or value <= 0 for value in values)
|
|
):
|
|
raise RefineWindowError(
|
|
f"physical group {group_index + 1} has invalid logical chunk identity"
|
|
)
|
|
chunks = tuple(int(value) for value in values)
|
|
if tuple(sorted(chunks)) != chunks or len(set(chunks)) != len(chunks):
|
|
raise RefineWindowError(
|
|
f"physical group {group_index + 1} logical chunks are not ordered and unique"
|
|
)
|
|
return chunks
|
|
|
|
|
|
def _visible_units(
|
|
assembly_plan: Mapping[str, Any],
|
|
groups: Sequence[Mapping[str, Any]],
|
|
) -> tuple[list[dict[str, int]], int]:
|
|
decode_groups = assembly_plan.get("decode_groups")
|
|
if isinstance(decode_groups, Sequence) and not isinstance(
|
|
decode_groups, (str, bytes)
|
|
):
|
|
if len(decode_groups) != len(groups) or not all(
|
|
isinstance(group, Mapping) for group in decode_groups
|
|
):
|
|
raise RefineWindowError(
|
|
"assembly_plan decode groups differ from Second Pass physical groups"
|
|
)
|
|
source_units: Sequence[Mapping[str, Any]] = decode_groups
|
|
else:
|
|
source_units = groups
|
|
|
|
cursor = 0
|
|
units: list[dict[str, int]] = []
|
|
for group_index, (group, source) in enumerate(zip(groups, source_units, strict=True)):
|
|
physical_frames = int(group.get("physical_frames", 0))
|
|
trim_frames = int(group.get("trim_prefix_frames", -1))
|
|
source_latent_t = int(group.get("source_latent_t", 0))
|
|
audio_shape = group.get("source_audio_shape")
|
|
if physical_frames <= 0 or trim_frames < 0 or trim_frames >= physical_frames:
|
|
raise RefineWindowError(
|
|
f"physical group {group_index + 1} frame geometry is invalid"
|
|
)
|
|
if source_latent_t <= 0 or pixel_frames_for_latent_t(source_latent_t) != physical_frames:
|
|
raise RefineWindowError(
|
|
f"physical group {group_index + 1} Video latent T differs from its frame grid"
|
|
)
|
|
if (
|
|
not isinstance(audio_shape, Sequence)
|
|
or isinstance(audio_shape, (str, bytes))
|
|
or len(audio_shape) != 4
|
|
or int(audio_shape[-1]) != audio_latent_t(physical_frames)
|
|
):
|
|
raise RefineWindowError(
|
|
f"physical group {group_index + 1} Audio latent T differs from its frame grid"
|
|
)
|
|
net_frames = physical_frames - trim_frames
|
|
source_total = int(source.get("total_frames", physical_frames))
|
|
source_trim = int(source.get("trim_frames", trim_frames))
|
|
source_net = int(source.get("net_frames", source_total - source_trim))
|
|
source_start = int(source.get("frame_start", cursor))
|
|
source_stop = int(source.get("frame_stop", source_start + source_net))
|
|
if (
|
|
source_total != physical_frames
|
|
or source_trim != trim_frames
|
|
or source_net != net_frames
|
|
or source_start != cursor
|
|
or source_stop != cursor + net_frames
|
|
):
|
|
raise RefineWindowError(
|
|
f"physical group {group_index + 1} visible range is inconsistent"
|
|
)
|
|
units.append(
|
|
{
|
|
"group_index": group_index,
|
|
"visible_start": source_start,
|
|
"visible_stop": source_stop,
|
|
"physical_frames": physical_frames,
|
|
"trim_frames": trim_frames,
|
|
"video_t": source_latent_t,
|
|
"audio_t": int(audio_shape[-1]),
|
|
}
|
|
)
|
|
cursor = source_stop
|
|
return units, cursor
|
|
|
|
|
|
def _output_to_natural_ranges(
|
|
output_start: int,
|
|
output_stop: int,
|
|
*,
|
|
natural_frames: int,
|
|
target_frames: int,
|
|
preserve_final_frame: bool,
|
|
) -> tuple[tuple[int, int], ...]:
|
|
mappings: list[tuple[int, int, int, bool]] = []
|
|
if target_frames >= natural_frames:
|
|
mappings.append((0, natural_frames, 0, False))
|
|
if target_frames > natural_frames:
|
|
mappings.append((natural_frames, target_frames, natural_frames - 1, True))
|
|
elif preserve_final_frame and target_frames >= 2:
|
|
mappings.extend(
|
|
(
|
|
(0, target_frames - 1, 0, False),
|
|
(target_frames - 1, target_frames, natural_frames - 1, True),
|
|
)
|
|
)
|
|
else:
|
|
mappings.append((0, target_frames, 0, False))
|
|
|
|
natural_ranges: list[tuple[int, int]] = []
|
|
for destination_start, destination_stop, source_start, repeated in mappings:
|
|
overlap_start = max(output_start, destination_start)
|
|
overlap_stop = min(output_stop, destination_stop)
|
|
if overlap_stop <= overlap_start:
|
|
continue
|
|
if repeated:
|
|
natural_ranges.append((source_start, source_start + 1))
|
|
else:
|
|
mapped_start = source_start + overlap_start - destination_start
|
|
mapped_stop = source_start + overlap_stop - destination_start
|
|
natural_ranges.append((mapped_start, mapped_stop))
|
|
return _merge_ranges(natural_ranges)
|
|
|
|
|
|
def _group_window(
|
|
group: Mapping[str, Any],
|
|
unit: Mapping[str, int],
|
|
natural_ranges: Sequence[tuple[int, int]],
|
|
) -> GroupTemporalWindow | None:
|
|
visible_start = int(unit["visible_start"])
|
|
visible_stop = int(unit["visible_stop"])
|
|
visible_ranges = _merge_ranges(
|
|
(
|
|
max(start, visible_start),
|
|
min(stop, visible_stop),
|
|
)
|
|
for start, stop in natural_ranges
|
|
if start < visible_stop and stop > visible_start
|
|
)
|
|
if not visible_ranges:
|
|
return None
|
|
|
|
trim_frames = int(unit["trim_frames"])
|
|
physical_ranges = _merge_ranges(
|
|
(
|
|
trim_frames + start - visible_start,
|
|
trim_frames + stop - visible_start,
|
|
)
|
|
for start, stop in visible_ranges
|
|
)
|
|
video_t = int(unit["video_t"])
|
|
offsets = latent_slot_offsets(video_t)
|
|
selected_slots = []
|
|
for slot, slot_start in enumerate(offsets):
|
|
slot_stop = offsets[slot + 1] if slot + 1 < video_t else int(unit["physical_frames"])
|
|
if _overlaps(slot_start, slot_stop, physical_ranges):
|
|
selected_slots.append(slot)
|
|
video_ranges = _indices_to_ranges(selected_slots)
|
|
if video_ranges and offsets[video_ranges[0][0]] < trim_frames:
|
|
raise RefineWindowError(
|
|
f"physical group {int(unit['group_index']) + 1} Video grid would expose "
|
|
"the protected continuation prefix"
|
|
)
|
|
|
|
audio_ranges = _merge_ranges(
|
|
(
|
|
max(0, min(int(unit["audio_t"]), audio_latent_t(start))),
|
|
max(0, min(int(unit["audio_t"]), audio_latent_t(stop))),
|
|
)
|
|
for start, stop in physical_ranges
|
|
)
|
|
protected_audio_stop = audio_latent_t(trim_frames)
|
|
if audio_ranges and audio_ranges[0][0] < protected_audio_stop:
|
|
raise RefineWindowError(
|
|
f"physical group {int(unit['group_index']) + 1} Audio grid would expose "
|
|
"the protected continuation prefix"
|
|
)
|
|
if not video_ranges or not audio_ranges:
|
|
raise RefineWindowError(
|
|
f"physical group {int(unit['group_index']) + 1} window resolves to an empty AV grid"
|
|
)
|
|
return GroupTemporalWindow(
|
|
group_index=int(unit["group_index"]),
|
|
logical_chunks=_logical_chunks(group, int(unit["group_index"])),
|
|
terminal_merged=bool(group.get("terminal_merged", False)),
|
|
visible_frame_ranges=visible_ranges,
|
|
physical_frame_ranges=physical_ranges,
|
|
video_slot_ranges=video_ranges,
|
|
audio_tick_ranges=audio_ranges,
|
|
)
|
|
|
|
|
|
def resolve_refine_window(
|
|
start_sec: float,
|
|
end_sec: float,
|
|
assembly_plan: Mapping[str, Any],
|
|
) -> RefineWindow:
|
|
"""Resolve final visible output time to protected physical AV ranges.
|
|
|
|
The requested interval is half-open. Fractions select every output frame
|
|
interval they overlap. Continuation trim prefixes are never selected.
|
|
"""
|
|
|
|
try:
|
|
requested_start = float(start_sec)
|
|
requested_end = float(end_sec)
|
|
except (TypeError, ValueError) as exc:
|
|
raise RefineWindowError("refine window seconds must be numeric") from exc
|
|
if not math.isfinite(requested_start) or not math.isfinite(requested_end):
|
|
raise RefineWindowError("refine window seconds must be finite")
|
|
if requested_start >= requested_end:
|
|
raise RefineWindowError("refine window start must be less than end")
|
|
|
|
groups = _contract_groups(assembly_plan)
|
|
units, natural_frames = _visible_units(assembly_plan, groups)
|
|
fps = int(assembly_plan.get("fps", 0))
|
|
target_frames = int(assembly_plan.get("target_frames", 0))
|
|
if fps <= 0 or target_frames <= 0 or natural_frames <= 0:
|
|
raise RefineWindowError("assembly_plan visible timeline is invalid")
|
|
|
|
clamped_start = min(max(requested_start, 0.0), target_frames / fps)
|
|
clamped_end = min(max(requested_end, 0.0), target_frames / fps)
|
|
output_start = max(0, min(target_frames, math.floor(clamped_start * fps + 1e-9)))
|
|
output_stop = max(0, min(target_frames, math.ceil(clamped_end * fps - 1e-9)))
|
|
if output_stop <= output_start:
|
|
raise RefineWindowError("refine window does not overlap the visible output")
|
|
|
|
natural_ranges = _output_to_natural_ranges(
|
|
output_start,
|
|
output_stop,
|
|
natural_frames=natural_frames,
|
|
target_frames=target_frames,
|
|
preserve_final_frame=bool(assembly_plan.get("preserve_final_frame", False)),
|
|
)
|
|
if not natural_ranges:
|
|
raise RefineWindowError("refine window has no natural timeline source")
|
|
|
|
resolved_groups = tuple(
|
|
group_window
|
|
for group, unit in zip(groups, units, strict=True)
|
|
if (
|
|
group_window := _group_window(
|
|
group,
|
|
unit,
|
|
natural_ranges,
|
|
)
|
|
)
|
|
is not None
|
|
)
|
|
if not resolved_groups:
|
|
raise RefineWindowError("refine window selects no physical group")
|
|
selected = tuple(group.group_index for group in resolved_groups)
|
|
group_contracts = [
|
|
{
|
|
"group_index": group.group_index,
|
|
"physical_group": group.group_index + 1,
|
|
"logical_chunks": list(group.logical_chunks),
|
|
"terminal_merged": group.terminal_merged,
|
|
"visible_frame_ranges": [list(value) for value in group.visible_frame_ranges],
|
|
"physical_frame_ranges": [list(value) for value in group.physical_frame_ranges],
|
|
"video_slot_ranges": [list(value) for value in group.video_slot_ranges],
|
|
"audio_tick_ranges": [list(value) for value in group.audio_tick_ranges],
|
|
}
|
|
for group in resolved_groups
|
|
]
|
|
contract: dict[str, Any] = {
|
|
"magic": MAGIC,
|
|
"schema_version": SCHEMA_VERSION,
|
|
"mode": MODE_TIME_WINDOW,
|
|
"timeline": "final_visible_output",
|
|
"interval": "half_open",
|
|
"requested_start_sec": requested_start,
|
|
"requested_end_sec": requested_end,
|
|
"effective_start_sec": output_start / fps,
|
|
"effective_end_sec": output_stop / fps,
|
|
"output_frame_range": [output_start, output_stop],
|
|
"target_frames": target_frames,
|
|
"natural_frames": natural_frames,
|
|
"natural_frame_ranges": [list(value) for value in natural_ranges],
|
|
"selected_physical_groups": [index + 1 for index in selected],
|
|
"groups": group_contracts,
|
|
"continuation_prefix_policy": "always_protected",
|
|
"outside_window_policy": "mask_zero_then_bit_exact_restore",
|
|
"physical_group_atomicity": "preserved",
|
|
"temporal_quantization": "intersecting_video_slots_and_audio_ticks",
|
|
}
|
|
contract["window_hash"] = _identity(contract)
|
|
return RefineWindow(
|
|
selected_group_indices=selected,
|
|
groups=resolved_groups,
|
|
contract=MappingProxyType(contract),
|
|
)
|
|
|
|
|
|
def serializable_window_contract(window: RefineWindow) -> dict[str, Any]:
|
|
if not isinstance(window, RefineWindow):
|
|
raise RefineWindowError("refine_window must be a RefineWindow")
|
|
return json.loads(json.dumps(dict(window.contract)))
|