creative-render-engine 0.7.0__py3-none-any.whl

creative_render_engine/compiler.py

@@ -0,0 +1,1428 @@
+from __future__ import annotations
+
+import math
+import re
+from pathlib import Path
+from typing import Any, cast
+
+from moviepy import VideoFileClip
+from PIL import Image, ImageOps
+from pydantic import TypeAdapter, ValidationError
+from textblockrenderer import (
+    FontSpec,
+    LayoutEngine,
+    RenderConstraint,
+    RenderStyle,
+    SplitConfig,
+    TextMeasurer,
+    build_overlapping_timeline,
+    get_wpm_for_language,
+    measure_text_image,
+    split_html_to_colored_blocks,
+)
+from textblockrenderer import (
+    TrackMode as RendererTrackMode,
+)
+
+from .errors import AssetError, CompileError, ContractError
+from .hashing import file_sha256, stable_sha256
+from .plans import (
+    GraphicTextMeasurement,
+    GraphicTextRenderPlan,
+    GraphicTextRenderPlanBody,
+    PureImageRenderPlan,
+    PureImageRenderPlanBody,
+    RenderPlan,
+    ResolvedAsset,
+    ResolvedAudioSpec,
+    ResolvedFirstFrameSpec,
+    ResolvedFontStyle,
+    ResolvedMaskStyle,
+    ResolvedTextStyle,
+    ScrollBackgroundPlan,
+    ScrollLongTextPlan,
+    ScrollRenderPlan,
+    ScrollRenderPlanBody,
+    ScrollTextPlan,
+    TimelineBlockPlan,
+    TimelineBlockTimingPlan,
+    TimelineFramePlan,
+    TimelineRenderPlan,
+    TimelineRenderPlanBody,
+    TimelineWordPlan,
+)
+from .schemas import (
+    AssetMediaType,
+    AudioSpec,
+    BackgroundLayer,
+    FirstFrameSpec,
+    FontAsset,
+    FontSizeScale,
+    GraphicTextRenderTask,
+    LocalAsset,
+    Point,
+    PureImageRenderTask,
+    RenderTask,
+    ScrollRenderTask,
+    ScrollTextLayer,
+    Size,
+    TextStyle,
+    TimelineRenderTask,
+    TimelineSubtitleBlock,
+    TimelineSubtitleConfig,
+    TimelineSubtitleFrame,
+    TimelineSubtitleFrameItem,
+    TimelineTemplate,
+    WpmSubtitleGenerationOptions,
+)
+
+_FONT_SIZE_SCALE_ADAPTER: TypeAdapter[float] = TypeAdapter(FontSizeScale)
+_RENDER_TASK_ADAPTER: TypeAdapter[RenderTask] = TypeAdapter(RenderTask)
+
+_IMAGE_EXTENSIONS = {".bmp", ".gif", ".jpeg", ".jpg", ".png", ".tif", ".tiff", ".webp"}
+_VIDEO_EXTENSIONS = {".avi", ".m4v", ".mkv", ".mov", ".mp4", ".webm", ".wmv"}
+_AUDIO_EXTENSIONS = {".aac", ".flac", ".m4a", ".mp3", ".ogg", ".wav", ".wma"}
+_FONT_EXTENSIONS = {".otf", ".ttc", ".ttf", ".woff", ".woff2"}
+
+
+def validate_render_task(value: RenderTask | dict[str, Any]) -> RenderTask:
+    if isinstance(
+        value,
+        (
+            PureImageRenderTask,
+            GraphicTextRenderTask,
+            ScrollRenderTask,
+            TimelineRenderTask,
+        ),
+    ):
+        return value
+    try:
+        return _RENDER_TASK_ADAPTER.validate_python(value)
+    except ValidationError as exc:
+        raise ContractError(
+            "render task validation failed",
+            code="invalid_render_task",
+            details={"errors": exc.errors(include_url=False)},
+        ) from exc
+
+
+def compile_task(value: RenderTask | dict[str, Any]) -> RenderPlan:
+    task = validate_render_task(value)
+    if isinstance(task, PureImageRenderTask):
+        return _compile_pure_image(task)
+    if isinstance(task, GraphicTextRenderTask):
+        return _compile_graphic_text(task)
+    if isinstance(task, ScrollRenderTask):
+        return _compile_scroll(task)
+    return _compile_timeline(task)
+
+
+def measure_graphic_text_task(
+    value: GraphicTextRenderTask | dict[str, Any],
+) -> GraphicTextMeasurement:
+    task = validate_render_task(value)
+    if not isinstance(task, GraphicTextRenderTask):
+        raise ContractError(
+            "graphic-text measurement requires a graphic_text task",
+            code="invalid_graphic_text_task",
+            field_path="kind",
+        )
+    _, measurement = _resolve_graphic_text(task)
+    return measurement
+
+
+def _compile_pure_image(task: PureImageRenderTask) -> PureImageRenderPlan:
+    layer = task.template.layer
+    binding = task.bindings.image
+    if binding.slot != layer.slot:
+        raise CompileError(
+            f"pure-image binding slot {binding.slot!r} does not match template slot {layer.slot!r}",
+            code="slot_mismatch",
+            field_path="bindings.image.slot",
+        )
+    image = _resolve_pure_image_asset(binding.asset, "bindings.image.asset")
+    body = PureImageRenderPlanBody(
+        canvas=task.template.canvas,
+        layer=layer,
+        image=image,
+        output=task.output,
+        asset_ids=(image.id,),
+    )
+    plan_hash = stable_sha256(
+        {
+            "schema_version": task.schema_version,
+            "kind": task.kind,
+            "template_id": task.template.template_id,
+            "template_revision": task.template.revision,
+            "body": _portable_plan_payload(body.model_dump(mode="json")),
+        }
+    )
+    return PureImageRenderPlan(
+        template_id=task.template.template_id,
+        template_revision=task.template.revision,
+        plan_hash=plan_hash,
+        body=body,
+    )
+
+
+def _compile_graphic_text(task: GraphicTextRenderTask) -> GraphicTextRenderPlan:
+    style, measurement = _resolve_graphic_text(task)
+    if not measurement.fits:
+        raise CompileError(
+            f"graphic-text content exceeds its box by {measurement.overflow_character_count} characters",
+            code="graphic_text_overflow",
+            field_path="bindings.text.html",
+            details=measurement.model_dump(mode="json"),
+        )
+    image = _resolve_pure_image_asset(
+        task.bindings.image.asset,
+        "bindings.image.asset",
+    )
+    text_layer = task.template.text_layer
+    body = GraphicTextRenderPlanBody(
+        canvas=task.template.canvas,
+        background_color=task.template.background_color,
+        image_layer=task.template.image_layer,
+        image=image,
+        text=ScrollTextPlan(
+            id=text_layer.id,
+            z_index=text_layer.z_index,
+            box=text_layer.box,
+            opacity=text_layer.opacity,
+            html=task.bindings.text.html,
+            language=task.bindings.text.language,
+            style=style,
+        ),
+        measurement=measurement,
+        output=task.output,
+        asset_ids=(image.id, style.font.font.id),
+    )
+    plan_hash = stable_sha256(
+        {
+            "schema_version": task.schema_version,
+            "kind": task.kind,
+            "template_id": task.template.template_id,
+            "template_revision": task.template.revision,
+            "body": _portable_plan_payload(body.model_dump(mode="json")),
+        }
+    )
+    return GraphicTextRenderPlan(
+        template_id=task.template.template_id,
+        template_revision=task.template.revision,
+        plan_hash=plan_hash,
+        body=body,
+    )
+
+
+def _resolve_graphic_text(
+    task: GraphicTextRenderTask,
+) -> tuple[ResolvedTextStyle, GraphicTextMeasurement]:
+    image_layer = task.template.image_layer
+    text_layer = task.template.text_layer
+    if task.bindings.image.slot != image_layer.slot:
+        raise CompileError(
+            "graphic-text image binding slot does not match the template",
+            code="slot_mismatch",
+            field_path="bindings.image.slot",
+        )
+    if task.bindings.text.slot != text_layer.slot:
+        raise CompileError(
+            "graphic-text text binding slot does not match the template",
+            code="slot_mismatch",
+            field_path="bindings.text.slot",
+        )
+    style = _resolve_text_style(
+        text_layer.style,
+        "template.text_layer.style",
+        font_size_scale=task.bindings.text.font_size_scale,
+        font_size_scale_field_path="bindings.text.font_size_scale",
+    )
+    font_spec, constraint, split_config, renderer_style = _renderer_models(
+        style,
+        language=task.bindings.text.language,
+        max_width=text_layer.box.size.width,
+        max_height=text_layer.box.size.height,
+        preferred_height=text_layer.box.size.height,
+    )
+    block = measure_text_image(
+        html_text=task.bindings.text.html,
+        font_spec=font_spec,
+        constraint=constraint,
+        adjust="WIDTH",
+        vertical_align=style.vertical_alignment.value,
+        split_config=split_config,
+        style=renderer_style,
+        base_font_size=18,
+    )
+    fit_line_count = _fit_line_count(
+        tuple(block.line_heights),
+        line_spacing=style.font.line_spacing,
+        max_height=text_layer.box.size.height - style.padding.y * 2,
+    )
+    overflow_character_count = sum(
+        _renderer_line_character_count(line) for line in block.lines[fit_line_count:]
+    )
+    image_height = int(block.image_height or block.height)
+    remaining_height_px = text_layer.box.size.height - image_height
+    measurement = GraphicTextMeasurement(
+        plain_text=block.plain_text,
+        image_width=int(block.image_width or block.width),
+        image_height=image_height,
+        line_count=len(block.lines),
+        fit_line_count=fit_line_count,
+        overflow_character_count=overflow_character_count,
+        remaining_height_px=remaining_height_px,
+        fill_ratio=round(image_height / text_layer.box.size.height, 6),
+        fits=image_height <= text_layer.box.size.height,
+    )
+    return style, measurement
+
+
+def _fit_line_count(
+    line_heights: tuple[int, ...],
+    *,
+    line_spacing: int,
+    max_height: int,
+) -> int:
+    used = 0
+    for index, line_height in enumerate(line_heights):
+        candidate = used + (line_spacing if index else 0) + line_height
+        if candidate > max_height:
+            return index
+        used = candidate
+    return len(line_heights)
+
+
+def _renderer_line_character_count(line: list[Any]) -> int:
+    return sum(
+        len(str(word.word)) + (1 if bool(getattr(word, "leading_space", False)) else 0)
+        for word in line
+    )
+
+
+_SCROLL_BUSINESS_MINIMUM_DURATION_S = 60.0
+
+
+def _compile_scroll(task: ScrollRenderTask) -> ScrollRenderPlan:
+    background_bindings = {
+        binding.slot: binding for binding in task.bindings.backgrounds
+    }
+    text_bindings = {binding.slot: binding for binding in task.bindings.texts}
+    template_slots = {layer.slot for layer in task.template.layers}
+    provided_slots = set(background_bindings) | set(text_bindings)
+    unknown_slots = sorted(provided_slots - template_slots)
+    if unknown_slots:
+        raise CompileError(
+            f"bindings reference unknown slots: {unknown_slots}",
+            code="unknown_slots",
+            field_path="bindings",
+        )
+
+    resolved_layers: list[
+        ScrollBackgroundPlan | ScrollTextPlan | ScrollLongTextPlan
+    ] = []
+    asset_map: dict[str, ResolvedAsset] = {}
+    for layer in sorted(task.template.layers, key=lambda item: item.z_index):
+        if isinstance(layer, BackgroundLayer):
+            background_binding = background_bindings.get(layer.slot)
+            if background_binding is None:
+                if layer.required:
+                    raise CompileError(
+                        f"missing required background binding for slot {layer.slot}",
+                        code="missing_binding",
+                        field_path=f"bindings.backgrounds.{layer.slot}",
+                    )
+                continue
+            asset = _resolve_local_asset(
+                background_binding.asset,
+                f"bindings.backgrounds.{layer.slot}.asset",
+            )
+            asset_map[asset.id] = asset
+            resolved_layers.append(
+                ScrollBackgroundPlan(
+                    id=layer.id,
+                    z_index=layer.z_index,
+                    box=layer.box,
+                    opacity=layer.opacity,
+                    crop=layer.crop,
+                    asset=asset,
+                )
+            )
+            continue
+
+        text_binding = text_bindings.get(layer.slot)
+        if text_binding is None:
+            if layer.required:
+                raise CompileError(
+                    f"missing required text binding for slot {layer.slot}",
+                    code="missing_binding",
+                    field_path=f"bindings.texts.{layer.slot}",
+                )
+            continue
+        style = _resolve_text_style(
+            layer.style,
+            f"template.layers.{layer.id}.style",
+            font_size_scale=text_binding.font_size_scale,
+            font_size_scale_field_path=f"bindings.texts.{layer.slot}.font_size_scale",
+        )
+        asset_map[style.font.font.id] = style.font.font
+        if isinstance(layer, ScrollTextLayer):
+            estimated_size = _measure_long_text(
+                text_binding.html,
+                text_binding.language,
+                layer.viewport.size.width,
+                style,
+            )
+            start_y = layer.viewport.size.height - layer.start_offset_y_px
+            end_y = -estimated_size.height
+            scroll_distance = float(start_y - end_y)
+            if scroll_distance <= 0:
+                raise CompileError(
+                    "scroll start position must precede the fully-hidden end position",
+                    code="invalid_scroll_distance",
+                    field_path=f"template.layers.{layer.id}.start_offset_y_px",
+                )
+            scroll_duration = scroll_distance / layer.scroll_speed_px_s
+            resolved_layers.append(
+                ScrollLongTextPlan(
+                    id=layer.id,
+                    z_index=layer.z_index,
+                    viewport=layer.viewport,
+                    opacity=layer.opacity,
+                    html=text_binding.html,
+                    language=text_binding.language,
+                    style=style,
+                    fade_length_px=layer.fade_length_px,
+                    scroll_speed_px_s=layer.scroll_speed_px_s,
+                    start_offset_y_px=layer.start_offset_y_px,
+                    start_y_px=start_y,
+                    end_y_px=end_y,
+                    begin_hold_s=layer.begin_hold_s,
+                    end_hold_s=layer.end_hold_s,
+                    estimated_image_size=estimated_size,
+                    scroll_distance_px=scroll_distance,
+                    scroll_duration_s=scroll_duration,
+                )
+            )
+        else:
+            resolved_layers.append(
+                ScrollTextPlan(
+                    id=layer.id,
+                    z_index=layer.z_index,
+                    box=layer.box,
+                    opacity=layer.opacity,
+                    html=text_binding.html,
+                    language=text_binding.language,
+                    style=style,
+                )
+            )
+
+    audio = _resolve_audio(task.audio, "audio")
+    if audio.asset is not None:
+        asset_map[audio.asset.id] = audio.asset
+    first_frame = _resolve_first_frame(task.first_frame, "first_frame")
+    if first_frame.asset is not None:
+        asset_map[first_frame.asset.id] = first_frame.asset
+
+    scroll_layer = next(
+        (layer for layer in resolved_layers if isinstance(layer, ScrollLongTextPlan)),
+        None,
+    )
+    computed_duration = (
+        scroll_layer.begin_hold_s
+        + scroll_layer.scroll_duration_s
+        + scroll_layer.end_hold_s
+        if scroll_layer is not None
+        else 0.0
+    )
+    if scroll_layer is not None:
+        duration = max(computed_duration, _SCROLL_BUSINESS_MINIMUM_DURATION_S)
+    else:
+        duration = task.output.minimum_duration_s
+        if duration <= 0:
+            raise CompileError(
+                "scroll task duration must be positive",
+                code="invalid_duration",
+                field_path="output.minimum_duration_s",
+            )
+
+    body = ScrollRenderPlanBody(
+        canvas=task.template.canvas,
+        layers=tuple(resolved_layers),
+        audio=audio,
+        first_frame=first_frame,
+        output=task.output,
+        duration_s=round(duration, 6),
+        asset_ids=tuple(sorted(asset_map)),
+    )
+    hash_body = _portable_plan_payload(body.model_dump(mode="json"))
+    plan_hash = stable_sha256(
+        {
+            "schema_version": task.schema_version,
+            "kind": task.kind,
+            "template_id": task.template.template_id,
+            "template_revision": task.template.revision,
+            "body": hash_body,
+        }
+    )
+    return ScrollRenderPlan(
+        template_id=task.template.template_id,
+        template_revision=task.template.revision,
+        plan_hash=plan_hash,
+        body=body,
+    )
+
+
+def generate_timeline_subtitles(
+    *,
+    template: TimelineTemplate | dict[str, Any],
+    html: str,
+    language: str,
+    font_size_scale: float = 1.0,
+    options: WpmSubtitleGenerationOptions | dict[str, Any] | None = None,
+) -> TimelineSubtitleConfig:
+    try:
+        resolved_template = (
+            template
+            if isinstance(template, TimelineTemplate)
+            else TimelineTemplate.model_validate(template)
+        )
+        resolved_font_size_scale = _FONT_SIZE_SCALE_ADAPTER.validate_python(
+            font_size_scale
+        )
+        resolved_options = (
+            options
+            if isinstance(options, WpmSubtitleGenerationOptions)
+            else WpmSubtitleGenerationOptions.model_validate(options or {})
+        )
+    except ValidationError as exc:
+        raise ContractError(
+            "timeline generation input validation failed",
+            code="invalid_timeline_generation_input",
+            details={"errors": exc.errors(include_url=False)},
+        ) from exc
+    normalized_language = language.strip().upper()
+    if not 2 <= len(normalized_language) <= 16:
+        raise ContractError(
+            "language must contain between 2 and 16 characters",
+            code="invalid_timeline_generation_input",
+            field_path="language",
+        )
+    if not re.sub(r"<[^>]+>|\s|&nbsp;", "", html, flags=re.IGNORECASE):
+        raise ContractError(
+            "html must contain visible text",
+            code="invalid_timeline_generation_input",
+            field_path="html",
+        )
+
+    style = _resolve_text_style(
+        resolved_template.subtitle.style,
+        "template.subtitle.style",
+        font_size_scale=resolved_font_size_scale,
+        font_size_scale_field_path="font_size_scale",
+    )
+    font_spec, constraint, _, renderer_style = _renderer_models(
+        style,
+        language=normalized_language,
+        max_width=resolved_template.subtitle.box.size.width,
+        max_height=resolved_template.canvas.height,
+        preferred_height=resolved_template.subtitle.box.size.height,
+        min_words_per_block=resolved_options.min_words_per_block,
+    )
+    wpm = resolved_options.wpm or get_wpm_for_language(normalized_language)
+    try:
+        renderer_frames = build_overlapping_timeline(
+            html_text=html,
+            font_spec=font_spec,
+            constraint=constraint,
+            split_config=SplitConfig(
+                min_words_per_block=resolved_options.min_words_per_block,
+                language=normalized_language,
+            ),
+            wpm=wpm,
+            style=renderer_style,
+            base_font_size=resolved_template.subtitle.base_font_size,
+            spacing=resolved_template.subtitle.layout.spacing_px,
+            max_blocks_per_frame=resolved_options.max_blocks_per_frame,
+            track_mode=RendererTrackMode(resolved_options.track_mode.value),
+        )
+    except Exception as exc:
+        raise CompileError(
+            "failed to generate timeline subtitles",
+            code="timeline_generation_failed",
+            field_path="html",
+        ) from exc
+    if not renderer_frames:
+        raise CompileError(
+            "timeline generation produced no subtitle blocks",
+            code="empty_timeline",
+            field_path="html",
+        )
+
+    block_ids: dict[int, str] = {}
+    blocks: list[TimelineSubtitleBlock] = []
+    frames: list[TimelineSubtitleFrame] = []
+    for frame_index, renderer_frame in enumerate(renderer_frames):
+        items: list[TimelineSubtitleFrameItem] = []
+        for slot_index, timing in enumerate(renderer_frame.block_timings):
+            block_key = id(timing.block)
+            block_id = block_ids.get(block_key)
+            if block_id is None:
+                block_id = f"block-{len(block_ids) + 1:04d}"
+                block_ids[block_key] = block_id
+                blocks.append(
+                    TimelineSubtitleBlock(
+                        block_id=block_id, html=timing.block.html_text
+                    )
+                )
+            items.append(
+                TimelineSubtitleFrameItem(
+                    block_id=block_id,
+                    slot_index=slot_index,
+                    start_time_s=round(float(timing.start_time), 6),
+                    end_time_s=round(float(timing.end_time), 6),
+                )
+            )
+        frames.append(
+            TimelineSubtitleFrame(
+                frame_id=f"frame-{frame_index + 1:04d}",
+                items=tuple(items),
+            )
+        )
+    return TimelineSubtitleConfig(
+        language=normalized_language,
+        font_size_scale=resolved_font_size_scale,
+        blocks=tuple(blocks),
+        frames=tuple(frames),
+    )
+
+
+def _compile_timeline(task: TimelineRenderTask) -> TimelineRenderPlan:
+    if task.bindings.subtitles.schema_version == "2.0":
+        return _compile_composed_timeline(task)
+
+    background = _resolve_local_asset(task.bindings.background, "bindings.background")
+    subtitle_template = task.template.subtitle
+    subtitle_config = task.bindings.subtitles
+    style = _resolve_text_style(
+        subtitle_template.style,
+        "template.subtitle.style",
+        font_size_scale=subtitle_config.font_size_scale,
+        font_size_scale_field_path="bindings.subtitles.font_size_scale",
+    )
+    audio = _resolve_audio(task.audio, "audio")
+    font_spec, constraint, split_config, renderer_style = _renderer_models(
+        style,
+        language=subtitle_config.language,
+        max_width=subtitle_template.box.size.width,
+        max_height=task.template.canvas.height,
+        preferred_height=subtitle_template.box.size.height,
+    )
+    measurer = TextMeasurer(font_spec=font_spec, stroke_size=style.font.stroke_size)
+    layout_engine = LayoutEngine(constraint, renderer_style, measurer)
+    effective_constraint = layout_engine.compute_effective_constraint()
+
+    blocks: list[TimelineBlockPlan] = []
+    block_plan_by_id: dict[str, TimelineBlockPlan] = {}
+    for block_index, configured_block in enumerate(subtitle_config.blocks):
+        field_path = f"bindings.subtitles.blocks.{block_index}.html"
+        try:
+            renderer_blocks = split_html_to_colored_blocks(
+                configured_block.html,
+                measurer,
+                effective_constraint,
+                split_config,
+                base_font_size=subtitle_template.base_font_size,
+            )
+        except Exception as exc:
+            raise CompileError(
+                "subtitle block cannot fit within the canvas",
+                code="subtitle_layout_overflow",
+                field_path=field_path,
+                details={"block_id": configured_block.block_id},
+            ) from exc
+        if len(renderer_blocks) != 1:
+            raise CompileError(
+                "subtitle block must remain one final renderable block",
+                code="subtitle_layout_overflow",
+                field_path=field_path,
+                details={
+                    "block_id": configured_block.block_id,
+                    "rendered_block_count": len(renderer_blocks),
+                },
+            )
+        renderer_block = renderer_blocks[0]
+        text_layout = layout_engine.compute_text_layout(
+            renderer_block,
+            align=renderer_style.alignment,
+        )
+        width = int(text_layout.image_width)
+        height = int(text_layout.image_height)
+        renderer_block.image_width = width
+        renderer_block.image_height = height
+        if width <= 0 or height <= 0:
+            raise CompileError(
+                "timeline block has invalid dimensions",
+                code="invalid_block_dimensions",
+                field_path=field_path,
+                details={
+                    "block_id": configured_block.block_id,
+                    "width": width,
+                    "height": height,
+                },
+            )
+        if width > task.template.canvas.width or height > task.template.canvas.height:
+            raise CompileError(
+                "subtitle block cannot fit within the canvas",
+                code="subtitle_layout_overflow",
+                field_path=field_path,
+                details={
+                    "block_id": configured_block.block_id,
+                    "required": {"width": width, "height": height},
+                    "available": task.template.canvas.model_dump(mode="json"),
+                },
+            )
+        words = tuple(
+            TimelineWordPlan(
+                word=word.word,
+                color=word.color,
+                font_size=word.font_size,
+                force_newline=word.force_newline,
+                leading_space=word.leading_space,
+                glue_to_previous=word.glue_to_previous,
+            )
+            for word in renderer_block.colored_words
+        )
+        block_plan = TimelineBlockPlan(
+            block_id=configured_block.block_id,
+            plain_text=renderer_block.plain_text,
+            colored_words=words,
+            renderer_block=renderer_block.model_dump(mode="json"),
+            size=Size(width=width, height=height),
+        )
+        blocks.append(block_plan)
+        block_plan_by_id[configured_block.block_id] = block_plan
+
+    plan_frames: list[TimelineFramePlan] = []
+    spacing_px = subtitle_template.layout.spacing_px
+    for frame_index, configured_frame in enumerate(subtitle_config.frames):
+        ordered_items = sorted(configured_frame.items, key=lambda item: item.slot_index)
+        frame_blocks = [block_plan_by_id[item.block_id] for item in ordered_items]
+        total_height = sum(block.size.height for block in frame_blocks)
+        if len(frame_blocks) > 1:
+            total_height += spacing_px * (len(frame_blocks) - 1)
+        if total_height > task.template.canvas.height:
+            raise CompileError(
+                "subtitle frame cannot fit within the canvas",
+                code="subtitle_layout_overflow",
+                field_path=f"bindings.subtitles.frames.{frame_index}",
+                details={
+                    "frame_id": configured_frame.frame_id,
+                    "required": {"height": total_height},
+                    "available": {"height": task.template.canvas.height},
+                },
+            )
+        current_y = (
+            subtitle_template.box.position.y
+            + (subtitle_template.box.size.height - total_height) // 2
+        )
+        current_y = min(max(current_y, 0), task.template.canvas.height - total_height)
+        frame_timings: list[TimelineBlockTimingPlan] = []
+        for item, block in zip(ordered_items, frame_blocks, strict=True):
+            block_x = (task.template.canvas.width - block.size.width) // 2
+            frame_timings.append(
+                TimelineBlockTimingPlan(
+                    block_id=item.block_id,
+                    position=Point(x=block_x, y=current_y),
+                    start_time_s=round(item.start_time_s, 6),
+                    end_time_s=round(item.end_time_s, 6),
+                )
+            )
+            current_y += block.size.height + spacing_px
+        plan_frames.append(
+            TimelineFramePlan(
+                frame_id=configured_frame.frame_id,
+                frame_index=frame_index,
+                start_time_s=round(min(item.start_time_s for item in ordered_items), 6),
+                end_time_s=round(max(item.end_time_s for item in ordered_items), 6),
+                timings=tuple(frame_timings),
+            )
+        )
+
+    duration = max(
+        item.end_time_s for frame in subtitle_config.frames for item in frame.items
+    )
+    if duration <= 0:
+        raise CompileError(
+            "timeline duration must be positive", code="invalid_duration"
+        )
+    asset_map = {background.id: background, style.font.font.id: style.font.font}
+    if audio.asset is not None:
+        asset_map[audio.asset.id] = audio.asset
+    body = TimelineRenderPlanBody(
+        canvas=task.template.canvas,
+        subtitle_box=subtitle_template.box,
+        style=style,
+        language=subtitle_config.language,
+        spacing_px=spacing_px,
+        base_font_size=subtitle_template.base_font_size,
+        background=background,
+        audio=audio,
+        output=task.output,
+        duration_s=round(duration, 6),
+        blocks=tuple(blocks),
+        frames=tuple(plan_frames),
+        asset_ids=tuple(sorted(asset_map)),
+    )
+    hash_body = _portable_plan_payload(body.model_dump(mode="json"))
+    plan_hash = stable_sha256(
+        {
+            "schema_version": task.schema_version,
+            "kind": task.kind,
+            "template_id": task.template.template_id,
+            "template_revision": task.template.revision,
+            "body": hash_body,
+        }
+    )
+    return TimelineRenderPlan(
+        template_id=task.template.template_id,
+        template_revision=task.template.revision,
+        plan_hash=plan_hash,
+        body=body,
+    )
+
+
+def _compile_composed_timeline(task: TimelineRenderTask) -> TimelineRenderPlan:
+    """Compile the v2 per-frame subtitle composition without changing v1 behavior."""
+    background = _resolve_local_asset(task.bindings.background, "bindings.background")
+    subtitle_template = task.template.subtitle
+    subtitle_config = task.bindings.subtitles
+    style = _resolve_text_style(
+        subtitle_template.style,
+        "template.subtitle.style",
+        font_size_scale=subtitle_config.font_size_scale,
+        font_size_scale_field_path="bindings.subtitles.font_size_scale",
+    )
+    audio = _resolve_audio(task.audio, "audio")
+    box = subtitle_template.box
+    safe_x = max(box.position.x, 0)
+    safe_y = max(box.position.y, 0)
+    safe_right = min(box.position.x + box.size.width, task.template.canvas.width)
+    safe_bottom = min(box.position.y + box.size.height, task.template.canvas.height)
+    safe_width = safe_right - safe_x
+    safe_height = safe_bottom - safe_y
+    if safe_width <= 0 or safe_height <= 0:
+        raise CompileError(
+            "subtitle box has no usable canvas area",
+            code="subtitle_layout_overflow",
+            field_path="template.subtitle.box",
+            details={
+                "language": subtitle_config.language,
+                "required": {"width": 1, "height": 1},
+                "available": {"width": safe_width, "height": safe_height},
+            },
+        )
+    max_blocks_per_frame = subtitle_template.max_blocks_per_frame
+    if max_blocks_per_frame is None:
+        raise CompileError(
+            "composed timeline requires a frozen max_blocks_per_frame",
+            code="invalid_timeline_composition",
+            field_path="template.subtitle.max_blocks_per_frame",
+        )
+
+    spacing_px = subtitle_template.layout.spacing_px
+    configured_blocks = {block.block_id: block for block in subtitle_config.blocks}
+    block_plans: list[TimelineBlockPlan] = []
+
+    def measure_block(
+        *,
+        frame_id: str,
+        block_id: str,
+        max_width: int,
+        max_height: int,
+    ) -> TimelineBlockPlan:
+        if max_width <= 0 or max_height <= 0:
+            raise CompileError(
+                "subtitle layout region must have positive dimensions",
+                code="subtitle_layout_overflow",
+                field_path=f"bindings.subtitles.blocks.{block_id}.html",
+                details={
+                    "language": subtitle_config.language,
+                    "frame_id": frame_id,
+                    "block_ids": [block_id],
+                    "required": {"width": 1, "height": 1},
+                    "available": {"width": max_width, "height": max_height},
+                },
+            )
+        configured_block = configured_blocks[block_id]
+        font_spec, constraint, split_config, renderer_style = _renderer_models(
+            style,
+            language=subtitle_config.language,
+            max_width=max_width,
+            max_height=max_height,
+            preferred_height=max_height,
+        )
+        measurer = TextMeasurer(font_spec=font_spec, stroke_size=style.font.stroke_size)
+        layout_engine = LayoutEngine(constraint, renderer_style, measurer)
+        effective_constraint = layout_engine.compute_effective_constraint()
+        try:
+            renderer_blocks = split_html_to_colored_blocks(
+                configured_block.html,
+                measurer,
+                effective_constraint,
+                split_config,
+                base_font_size=subtitle_template.base_font_size,
+            )
+        except Exception as exc:
+            raise CompileError(
+                "subtitle block cannot fit within its layout region",
+                code="subtitle_layout_overflow",
+                field_path=f"bindings.subtitles.blocks.{block_id}.html",
+                details={
+                    "language": subtitle_config.language,
+                    "frame_id": frame_id,
+                    "block_ids": [block_id],
+                    "available": {"width": max_width, "height": max_height},
+                },
+            ) from exc
+        if len(renderer_blocks) != 1:
+            measured = [
+                layout_engine.compute_text_layout(block, align=renderer_style.alignment)
+                for block in renderer_blocks
+            ]
+            raise CompileError(
+                "subtitle block must remain one renderable block",
+                code="subtitle_layout_overflow",
+                field_path=f"bindings.subtitles.blocks.{block_id}.html",
+                details={
+                    "language": subtitle_config.language,
+                    "frame_id": frame_id,
+                    "block_ids": [block_id],
+                    "required": {
+                        "width": max((layout.image_width for layout in measured), default=0),
+                        "height": sum(layout.image_height for layout in measured),
+                    },
+                    "available": {"width": max_width, "height": max_height},
+                    "rendered_block_count": len(renderer_blocks),
+                },
+            )
+        renderer_block = renderer_blocks[0]
+        text_layout = layout_engine.compute_text_layout(
+            renderer_block,
+            align=renderer_style.alignment,
+        )
+        width = int(text_layout.image_width)
+        height = int(text_layout.image_height)
+        if width <= 0 or height <= 0 or width > max_width or height > max_height:
+            raise CompileError(
+                "subtitle block cannot fit within its layout region",
+                code="subtitle_layout_overflow",
+                field_path=f"bindings.subtitles.blocks.{block_id}.html",
+                details={
+                    "language": subtitle_config.language,
+                    "frame_id": frame_id,
+                    "block_ids": [block_id],
+                    "required": {"width": width, "height": height},
+                    "available": {"width": max_width, "height": max_height},
+                },
+            )
+        words = tuple(
+            TimelineWordPlan(
+                word=word.word,
+                color=word.color,
+                font_size=word.font_size,
+                force_newline=word.force_newline,
+                leading_space=word.leading_space,
+                glue_to_previous=word.glue_to_previous,
+            )
+            for word in renderer_block.colored_words
+        )
+        return TimelineBlockPlan(
+            block_id=block_id,
+            plain_text=renderer_block.plain_text,
+            colored_words=words,
+            renderer_block=renderer_block.model_dump(mode="json"),
+            size=Size(width=width, height=height),
+        )
+
+    plan_frames: list[TimelineFramePlan] = []
+    previous_end = 0.0
+    for frame_index, configured_frame in enumerate(subtitle_config.frames):
+        items = sorted(configured_frame.items, key=lambda item: item.slot_index)
+        frame_path = f"bindings.subtitles.frames.{frame_index}"
+        layout = configured_frame.layout
+        reveal = configured_frame.reveal
+        if layout is None or reveal is None:  # Schema v2 has already rejected this.
+            raise CompileError(
+                "subtitle frame requires layout and reveal",
+                code="invalid_timeline_composition",
+                field_path=frame_path,
+            )
+        starts = [item.start_time_s for item in items]
+        ends = [item.end_time_s for item in items]
+        if len(set(ends)) != 1:
+            raise CompileError(
+                "subtitle frame items must share an end time",
+                code="invalid_timeline_composition",
+                field_path=frame_path,
+            )
+        if reveal.value == "together" and len(set(starts)) != 1:
+            raise CompileError(
+                "together frame items must share a start time",
+                code="invalid_timeline_composition",
+                field_path=frame_path,
+            )
+        if reveal.value == "progressive" and any(
+            starts[index] <= starts[index - 1] for index in range(1, len(starts))
+        ):
+            raise CompileError(
+                "progressive frame items must start strictly in slot order",
+                code="invalid_timeline_composition",
+                field_path=frame_path,
+            )
+        frame_start = min(starts)
+        frame_end = max(ends)
+        if frame_start != previous_end:
+            raise CompileError(
+                "subtitle frames must start at zero and remain continuous",
+                code="invalid_timeline_composition",
+                field_path=frame_path,
+            )
+        previous_end = frame_end
+        if len(items) > max_blocks_per_frame:
+            raise CompileError(
+                "subtitle frame exceeds the frozen template block limit",
+                code="invalid_timeline_composition",
+                field_path=frame_path,
+                details={
+                    "language": subtitle_config.language,
+                    "frame_id": configured_frame.frame_id,
+                    "block_ids": [item.block_id for item in items],
+                    "required": {"block_count": len(items)},
+                    "available": {"block_count": max_blocks_per_frame},
+                },
+            )
+
+        if layout.value == "stack":
+            frame_blocks = [
+                measure_block(
+                    frame_id=configured_frame.frame_id,
+                    block_id=item.block_id,
+                    max_width=safe_width,
+                    max_height=safe_height,
+                )
+                for item in items
+            ]
+            total_height = sum(block.size.height for block in frame_blocks)
+            total_height += spacing_px * (len(frame_blocks) - 1)
+            if total_height > safe_height:
+                raise CompileError(
+                    "stack subtitle frame cannot fit within subtitle box",
+                    code="subtitle_layout_overflow",
+                    field_path=frame_path,
+                    details={
+                        "language": subtitle_config.language,
+                        "frame_id": configured_frame.frame_id,
+                        "block_ids": [item.block_id for item in items],
+                        "required": {
+                            "width": max(block.size.width for block in frame_blocks),
+                            "height": total_height,
+                        },
+                        "available": {"width": safe_width, "height": safe_height},
+                    },
+                )
+            positions = [
+                Point(
+                    x=safe_x + (safe_width - block.size.width) // 2,
+                    y=safe_y
+                    + (safe_height - total_height) // 2
+                    + sum(
+                        previous.size.height + spacing_px
+                        for previous in frame_blocks[:block_index]
+                    ),
+                )
+                for block_index, block in enumerate(frame_blocks)
+            ]
+        else:  # columns
+            left_width = (safe_width - spacing_px) // 2
+            right_width = safe_width - spacing_px - left_width
+            frame_blocks = [
+                measure_block(
+                    frame_id=configured_frame.frame_id,
+                    block_id=items[0].block_id,
+                    max_width=left_width,
+                    max_height=safe_height,
+                ),
+                measure_block(
+                    frame_id=configured_frame.frame_id,
+                    block_id=items[1].block_id,
+                    max_width=right_width,
+                    max_height=safe_height,
+                ),
+            ]
+            top = safe_y + (safe_height - max(block.size.height for block in frame_blocks)) // 2
+            positions = [
+                Point(x=safe_x + (left_width - frame_blocks[0].size.width) // 2, y=top),
+                Point(
+                    x=safe_x
+                    + left_width
+                    + spacing_px
+                    + (right_width - frame_blocks[1].size.width) // 2,
+                    y=top,
+                ),
+            ]
+        frame_timings: list[TimelineBlockTimingPlan] = []
+        for item, block, position in zip(items, frame_blocks, positions, strict=True):
+            block_plans.append(block)
+            frame_timings.append(
+                TimelineBlockTimingPlan(
+                    block_id=item.block_id,
+                    position=position,
+                    start_time_s=round(item.start_time_s, 6),
+                    end_time_s=round(item.end_time_s, 6),
+                )
+            )
+        plan_frames.append(
+            TimelineFramePlan(
+                frame_id=configured_frame.frame_id,
+                frame_index=frame_index,
+                start_time_s=round(frame_start, 6),
+                end_time_s=round(frame_end, 6),
+                timings=tuple(frame_timings),
+            )
+        )
+
+    duration = max(frame.end_time_s for frame in plan_frames)
+    asset_map = {background.id: background, style.font.font.id: style.font.font}
+    if audio.asset is not None:
+        asset_map[audio.asset.id] = audio.asset
+    body = TimelineRenderPlanBody(
+        canvas=task.template.canvas,
+        subtitle_box=subtitle_template.box,
+        style=style,
+        language=subtitle_config.language,
+        spacing_px=spacing_px,
+        base_font_size=subtitle_template.base_font_size,
+        background=background,
+        audio=audio,
+        output=task.output,
+        duration_s=round(duration, 6),
+        blocks=tuple(block_plans),
+        frames=tuple(plan_frames),
+        asset_ids=tuple(sorted(asset_map)),
+    )
+    hash_body = _portable_plan_payload(body.model_dump(mode="json"))
+    return TimelineRenderPlan(
+        template_id=task.template.template_id,
+        template_revision=task.template.revision,
+        plan_hash=stable_sha256(
+            {
+                "schema_version": task.schema_version,
+                "kind": "timeline_video",
+                "template_id": task.template.template_id,
+                "template_revision": task.template.revision,
+                "body": hash_body,
+            }
+        ),
+        body=body,
+    )
+
+
+def _resolve_audio(value: AudioSpec, field_path: str) -> ResolvedAudioSpec:
+    asset = (
+        _resolve_local_asset(value.asset, f"{field_path}.asset")
+        if value.asset is not None
+        else None
+    )
+    return ResolvedAudioSpec(
+        mode=value.mode,
+        asset=asset,
+        loop=value.loop,
+        fade_in_s=value.fade_in_s,
+        fade_out_s=value.fade_out_s,
+        volume=value.volume,
+    )
+
+
+def _resolve_first_frame(
+    value: FirstFrameSpec, field_path: str
+) -> ResolvedFirstFrameSpec:
+    asset = (
+        _resolve_local_asset(value.asset, f"{field_path}.asset")
+        if value.asset is not None
+        else None
+    )
+    return ResolvedFirstFrameSpec(mode=value.mode, asset=asset)
+
+
+def _resolve_text_style(
+    value: TextStyle,
+    field_path: str,
+    *,
+    font_size_scale: float = 1.0,
+    font_size_scale_field_path: str,
+) -> ResolvedTextStyle:
+    font = _resolve_font(value.font.font, f"{field_path}.font.font")
+    effective_font_size = _effective_font_size(
+        value.font.font_size,
+        font_size_scale,
+        font_size_scale_field_path,
+    )
+    return ResolvedTextStyle(
+        font=ResolvedFontStyle(
+            font=font,
+            font_size=effective_font_size,
+            line_spacing=value.font.line_spacing,
+            color=value.font.color,
+            alignment=value.font.alignment,
+            stroke_size=value.font.stroke_size,
+            stroke_color=value.font.stroke_color,
+        ),
+        mask=ResolvedMaskStyle(
+            mode=value.mask.mode,
+            color=value.mask.color,
+            offset=value.mask.offset,
+            corner_radius=value.mask.corner_radius,
+        ),
+        padding=value.padding,
+        adjust=value.adjust,
+        vertical_alignment=value.vertical_alignment,
+        min_words_per_block=value.min_words_per_block,
+    )
+
+
+def _effective_font_size(font_size: int, scale: float, field_path: str) -> int:
+    try:
+        normalized_scale = float(scale)
+    except (TypeError, ValueError) as exc:
+        raise ContractError(
+            "font_size_scale must be a finite positive number",
+            code="invalid_font_size_scale",
+            field_path=field_path,
+        ) from exc
+    if not math.isfinite(normalized_scale) or normalized_scale <= 0:
+        raise ContractError(
+            "font_size_scale must be a finite positive number",
+            code="invalid_font_size_scale",
+            field_path=field_path,
+        )
+    effective_font_size = math.floor(font_size * normalized_scale)
+    if effective_font_size < 1:
+        raise ContractError(
+            "font_size_scale produces a font size below 1px",
+            code="invalid_font_size_scale",
+            field_path=field_path,
+            details={
+                "font_size": font_size,
+                "font_size_scale": normalized_scale,
+            },
+        )
+    return effective_font_size
+
+
+def _resolve_font(value: FontAsset, field_path: str) -> ResolvedAsset:
+    local = LocalAsset(
+        id=value.id,
+        path=value.path,
+        media_type=AssetMediaType.FONT,
+        sha256=value.sha256,
+    )
+    return _resolve_local_asset(local, field_path)
+
+
+def _resolve_pure_image_asset(value: LocalAsset, field_path: str) -> ResolvedAsset:
+    resolved = _resolve_local_asset(value, field_path)
+    try:
+        with Image.open(resolved.path) as image:
+            if (
+                bool(getattr(image, "is_animated", False))
+                or int(getattr(image, "n_frames", 1)) > 1
+            ):
+                raise AssetError(
+                    "animated images are not supported for pure-image rendering",
+                    code="animated_image_not_supported",
+                    field_path=f"{field_path}.path",
+                )
+            oriented_value = ImageOps.exif_transpose(image)
+            if oriented_value is None:
+                raise ValueError("image orientation failed")
+            oriented = cast(Image.Image, oriented_value)
+            oriented.load()
+            size = Size(width=oriented.width, height=oriented.height)
+    except AssetError:
+        raise
+    except Exception as exc:
+        raise AssetError(
+            f"pure-image asset cannot be decoded: {resolved.path}",
+            code="asset_decode_failed",
+            field_path=f"{field_path}.path",
+        ) from exc
+    return resolved.model_copy(update={"size": size})
+
+
+def _resolve_local_asset(value: LocalAsset | None, field_path: str) -> ResolvedAsset:
+    if value is None:
+        raise AssetError(
+            "asset is required", code="missing_asset", field_path=field_path
+        )
+    path = value.path.expanduser().resolve()
+    if not path.is_file():
+        raise AssetError(
+            f"asset file does not exist: {path}",
+            code="asset_not_found",
+            field_path=f"{field_path}.path",
+        )
+    _validate_extension(path, value.media_type, field_path)
+    actual_sha256 = file_sha256(path)
+    if value.sha256 is not None and value.sha256 != actual_sha256:
+        raise AssetError(
+            "asset sha256 does not match file content",
+            code="asset_hash_mismatch",
+            field_path=f"{field_path}.sha256",
+        )
+    size: Size | None = None
+    duration: float | None = None
+    try:
+        if value.media_type == AssetMediaType.IMAGE:
+            with Image.open(path) as image:
+                image.verify()
+            with Image.open(path) as image:
+                size = Size(width=image.width, height=image.height)
+        elif value.media_type == AssetMediaType.VIDEO:
+            with VideoFileClip(str(path)) as clip:
+                size = Size(width=int(clip.w), height=int(clip.h))
+                duration = float(clip.duration)
+        elif value.media_type == AssetMediaType.FONT:
+            FontSpec(font_path=str(path), font_size=16)
+    except Exception as exc:
+        raise AssetError(
+            f"asset cannot be decoded as {value.media_type.value}: {path}",
+            code="asset_decode_failed",
+            field_path=f"{field_path}.path",
+        ) from exc
+    return ResolvedAsset(
+        id=value.id,
+        path=path,
+        media_type=value.media_type.value,
+        sha256=actual_sha256,
+        size=size,
+        duration_s=duration,
+    )
+
+
+def _portable_plan_payload(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            key: _portable_plan_payload(item)
+            for key, item in value.items()
+            if key != "path"
+        }
+    if isinstance(value, list):
+        return [_portable_plan_payload(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(_portable_plan_payload(item) for item in value)
+    return value
+
+
+def _validate_extension(
+    path: Path, media_type: AssetMediaType, field_path: str
+) -> None:
+    allowed = {
+        AssetMediaType.IMAGE: _IMAGE_EXTENSIONS,
+        AssetMediaType.VIDEO: _VIDEO_EXTENSIONS,
+        AssetMediaType.AUDIO: _AUDIO_EXTENSIONS,
+        AssetMediaType.FONT: _FONT_EXTENSIONS,
+    }[media_type]
+    if path.suffix.lower() not in allowed:
+        raise AssetError(
+            f"unsupported {media_type.value} extension: {path.suffix}",
+            code="unsupported_asset_extension",
+            field_path=f"{field_path}.path",
+        )
+
+
+def _measure_long_text(
+    html: str, language: str, max_width: int, style: ResolvedTextStyle
+):
+    font_spec, constraint, split_config, renderer_style = _renderer_models(
+        style,
+        language=language,
+        max_width=max_width,
+        max_height=0,
+        preferred_height=0,
+    )
+    measurer = TextMeasurer(font_spec=font_spec, stroke_size=style.font.stroke_size)
+    layout_engine = LayoutEngine(constraint, renderer_style, measurer)
+    effective_constraint = layout_engine.compute_effective_constraint()
+    try:
+        blocks = split_html_to_colored_blocks(
+            html,
+            measurer,
+            effective_constraint,
+            split_config,
+            base_font_size=18,
+        )
+        if not blocks:
+            raise CompileError(
+                "scrolling text produced no renderable block",
+                code="empty_scroll_text",
+            )
+        block = blocks[0]
+        layout = layout_engine.compute_text_layout(
+            block,
+            align=style.font.alignment.value,
+        )
+        return Size(
+            width=int(layout.image_width),
+            height=int(layout.image_height),
+        )
+    except CompileError:
+        raise
+    except Exception as exc:
+        raise CompileError(
+            "failed to measure scrolling text",
+            code="scroll_text_measure_failed",
+        ) from exc
+
+
+def _renderer_models(
+    style: ResolvedTextStyle,
+    *,
+    language: str,
+    max_width: int,
+    max_height: int,
+    preferred_height: int,
+    min_words_per_block: int | None = None,
+):
+    font_spec = FontSpec(
+        font_path=str(style.font.font.path),
+        font_size=style.font.font_size,
+        line_spacing=style.font.line_spacing,
+    )
+    constraint = RenderConstraint(
+        max_width=max_width,
+        max_height=max_height,
+        preferred_height=preferred_height,
+        min_width=0,
+    )
+    split_config = SplitConfig(
+        min_words_per_block=(
+            style.min_words_per_block
+            if min_words_per_block is None
+            else min_words_per_block
+        ),
+        language=language.upper(),
+    )
+    renderer_style = RenderStyle(
+        text_color=style.font.color,
+        bg_color=None,
+        alignment=style.font.alignment.value,
+        padding=(style.padding.x, style.padding.y),
+        mask_mode=style.mask.mode,
+        mask_color=style.mask.color,
+        mask_offset=(style.mask.offset.x, style.mask.offset.y),
+        corner_radius=style.mask.corner_radius,
+        stroke_size=style.font.stroke_size,
+        stroke_color=style.font.stroke_color,
+    )
+    return font_spec, constraint, split_config, renderer_style