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

creative_render_engine/schemas.py

@@ -0,0 +1,763 @@
+from __future__ import annotations
+
+import re
+from enum import Enum
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import Annotated, Any, Literal, TypeAlias
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PositiveFloat,
+    PositiveInt,
+    StrictFloat,
+    StringConstraints,
+    field_validator,
+    model_serializer,
+    model_validator,
+)
+
+SCHEMA_VERSION = "2.0"
+
+Identifier = Annotated[
+    str,
+    StringConstraints(
+        strip_whitespace=True, min_length=1, pattern=r"^[A-Za-z0-9][A-Za-z0-9_.-]*$"
+    ),
+]
+Color = Annotated[str, StringConstraints(pattern=r"^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$")]
+FontSizeScale = Annotated[StrictFloat, Field(gt=0, allow_inf_nan=False)]
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class AssetMediaType(str, Enum):
+    IMAGE = "image"
+    VIDEO = "video"
+    AUDIO = "audio"
+    FONT = "font"
+
+
+class CropMode(str, Enum):
+    COVER = "cover"
+    CONTAIN = "contain"
+    STRETCH = "stretch"
+
+
+class HorizontalAlignment(str, Enum):
+    LEFT = "left"
+    CENTER = "center"
+    RIGHT = "right"
+
+
+class VerticalAlignment(str, Enum):
+    TOP = "top"
+    MIDDLE = "middle"
+    BOTTOM = "bottom"
+
+
+class TextAdjustMode(str, Enum):
+    WIDTH = "WIDTH"
+    HEIGHT_EXTEND = "HEIGHT_EXTEND"
+    ADAPT = "ADAPT"
+
+
+class TrackMode(str, Enum):
+    SEQUENTIAL = "SEQUENTIAL"
+    SYNCHRONIZED = "SYNCHRONIZED"
+
+
+class AudioMode(str, Enum):
+    NONE = "none"
+    USE_ASSET = "use_asset"
+    USE_BACKGROUND = "use_background"
+
+
+class FirstFrameMode(str, Enum):
+    COMPOSED = "composed"
+    HIDDEN_TEXT = "hidden_text"
+    ASSET = "asset"
+
+
+class Size(StrictModel):
+    width: PositiveInt
+    height: PositiveInt
+
+
+class Point(StrictModel):
+    x: int
+    y: int
+
+
+class Box(StrictModel):
+    position: Point
+    size: Size
+
+    def intersects(self, canvas: Size) -> bool:
+        return (
+            self.position.x < canvas.width
+            and self.position.y < canvas.height
+            and self.position.x + self.size.width > 0
+            and self.position.y + self.size.height > 0
+        )
+
+
+class LocalAsset(StrictModel):
+    id: Identifier
+    path: Path
+    media_type: AssetMediaType
+    sha256: Annotated[str, StringConstraints(pattern=r"^[0-9A-Fa-f]{64}$")] | None = (
+        None
+    )
+
+    @field_validator("path")
+    @classmethod
+    def reject_empty_path(cls, value: Path) -> Path:
+        if not str(value).strip():
+            raise ValueError("path must not be empty")
+        return value
+
+    @field_validator("sha256")
+    @classmethod
+    def normalize_sha256(cls, value: str | None) -> str | None:
+        return value.lower() if value is not None else None
+
+
+class PureImageLayer(StrictModel):
+    id: Identifier
+    slot: Identifier
+    z_index: Literal[1] = 1
+    box: Box
+    fit: Literal["cover"] = "cover"
+
+
+class PureImageTemplate(StrictModel):
+    template_id: Identifier
+    revision: PositiveInt
+    canvas: Size
+    layer: PureImageLayer
+
+    @model_validator(mode="after")
+    def validate_full_canvas_layer(self) -> PureImageTemplate:
+        if (
+            self.layer.box.position != Point(x=0, y=0)
+            or self.layer.box.size != self.canvas
+        ):
+            raise ValueError("pure-image layer must cover the complete canvas")
+        return self
+
+
+class PureImageBinding(StrictModel):
+    slot: Identifier
+    asset: LocalAsset
+
+    @model_validator(mode="after")
+    def validate_asset(self) -> PureImageBinding:
+        if self.asset.media_type != AssetMediaType.IMAGE:
+            raise ValueError("pure-image binding requires an image asset")
+        return self
+
+
+class PureImageBindings(StrictModel):
+    image: PureImageBinding
+
+
+class _GraphicTextHtmlParser(HTMLParser):
+    def __init__(self, allowed_colors: set[str]) -> None:
+        super().__init__(convert_charrefs=True)
+        self.allowed_colors = allowed_colors
+        self.stack: list[str] = []
+        self.root_count = 0
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.lower()
+        if tag not in {"p", "br", "span"}:
+            raise ValueError(f"graphic-text html tag is not allowed: {tag}")
+        if tag == "p":
+            if self.stack or self.root_count:
+                raise ValueError(
+                    "graphic-text html must contain exactly one root p element"
+                )
+            if attrs:
+                raise ValueError("graphic-text p does not accept attributes")
+            self.root_count += 1
+            self.stack.append(tag)
+            return
+        if not self.stack or self.stack[0] != "p":
+            raise ValueError(
+                "graphic-text inline content must be inside the root p element"
+            )
+        if tag == "br":
+            if attrs:
+                raise ValueError("graphic-text br does not accept attributes")
+            return
+        if len(attrs) != 1 or attrs[0][0].lower() != "style" or attrs[0][1] is None:
+            raise ValueError("graphic-text span requires exactly one style attribute")
+        match = re.fullmatch(
+            r"\s*color\s*:\s*(#[0-9A-Fa-f]{6}(?:[0-9A-Fa-f]{2})?)\s*;?\s*",
+            attrs[0][1],
+        )
+        if match is None or match.group(1).upper() not in self.allowed_colors:
+            raise ValueError("graphic-text span color is not allowed")
+        self.stack.append(tag)
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        self.handle_starttag(tag, attrs)
+        if tag.lower() != "br":
+            self.handle_endtag(tag)
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.lower()
+        if tag == "br" or not self.stack or self.stack[-1] != tag:
+            raise ValueError("graphic-text html tags are not balanced")
+        self.stack.pop()
+
+    def handle_data(self, data: str) -> None:
+        if data.strip() and (not self.stack or self.stack[0] != "p"):
+            raise ValueError("graphic-text text must be inside the root p element")
+
+    def handle_comment(self, data: str) -> None:
+        del data
+        raise ValueError("graphic-text html comments are not allowed")
+
+    def handle_decl(self, decl: str) -> None:
+        del decl
+        raise ValueError("graphic-text html declarations are not allowed")
+
+    def handle_pi(self, data: str) -> None:
+        del data
+        raise ValueError("graphic-text html processing instructions are not allowed")
+
+    def unknown_decl(self, data: str) -> None:
+        del data
+        raise ValueError("graphic-text html declarations are not allowed")
+
+    def validate_complete(self) -> None:
+        if self.root_count != 1 or self.stack:
+            raise ValueError(
+                "graphic-text html must contain one balanced root p element"
+            )
+
+
+class GraphicTextRichTextPolicy(StrictModel):
+    allowed_tags: tuple[Literal["p", "br", "span"], ...]
+    allowed_span_styles: tuple[Literal["color"], ...]
+    allowed_colors: tuple[Color, ...]
+
+    @field_validator("allowed_colors")
+    @classmethod
+    def normalize_colors(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        return tuple(item.upper() for item in value)
+
+    @model_validator(mode="after")
+    def validate_policy(self) -> GraphicTextRichTextPolicy:
+        if self.allowed_tags != ("p", "br", "span"):
+            raise ValueError("graphic-text allowed_tags must be ('p', 'br', 'span')")
+        if self.allowed_span_styles != ("color",):
+            raise ValueError("graphic-text allowed_span_styles must be ('color',)")
+        if self.allowed_colors != ("#000000FF", "#FF0000FF"):
+            raise ValueError(
+                "graphic-text allowed_colors must be ('#000000FF', '#FF0000FF')"
+            )
+        return self
+
+
+class FontAsset(StrictModel):
+    id: Identifier
+    path: Path
+    sha256: Annotated[str, StringConstraints(pattern=r"^[0-9A-Fa-f]{64}$")] | None = (
+        None
+    )
+
+    @field_validator("sha256")
+    @classmethod
+    def normalize_sha256(cls, value: str | None) -> str | None:
+        return value.lower() if value is not None else None
+
+
+class FontStyle(StrictModel):
+    font: FontAsset
+    font_size: PositiveInt
+    line_spacing: int = 0
+    color: Color = "#FFFFFF"
+    alignment: HorizontalAlignment = HorizontalAlignment.CENTER
+    stroke_size: Annotated[int, Field(ge=0, le=32)] = 0
+    stroke_color: Color = "#000000"
+
+    @field_validator("color", "stroke_color")
+    @classmethod
+    def normalize_color(cls, value: str) -> str:
+        return value.upper()
+
+
+class MaskStyle(StrictModel):
+    mode: Annotated[int, Field(ge=0, le=3)] = 0
+    color: Color = "#000000C8"
+    offset: Point = Point(x=0, y=0)
+    corner_radius: Annotated[int, Field(ge=0, le=512)] = 0
+
+    @field_validator("color")
+    @classmethod
+    def normalize_color(cls, value: str) -> str:
+        return value.upper()
+
+
+class TextStyle(StrictModel):
+    font: FontStyle
+    mask: MaskStyle = MaskStyle()
+    padding: Point = Point(x=4, y=4)
+    adjust: TextAdjustMode = TextAdjustMode.WIDTH
+    vertical_alignment: VerticalAlignment = VerticalAlignment.MIDDLE
+    min_words_per_block: PositiveInt = 8
+
+    @model_validator(mode="after")
+    def validate_padding(self) -> TextStyle:
+        if self.padding.x < 0 or self.padding.y < 0:
+            raise ValueError("padding values must be non-negative")
+        return self
+
+
+class LayerBase(StrictModel):
+    id: Identifier
+    z_index: int
+    opacity: Annotated[int, Field(ge=0, le=255)] = 255
+
+
+class BoxLayerBase(LayerBase):
+    box: Box
+
+
+class BackgroundLayer(BoxLayerBase):
+    type: Literal["background"] = "background"
+    slot: Identifier
+    crop: CropMode = CropMode.COVER
+    required: bool = True
+
+
+class TextLayer(BoxLayerBase):
+    type: Literal["text"] = "text"
+    slot: Identifier
+    style: TextStyle
+    required: bool = True
+
+
+class ScrollTextLayer(LayerBase):
+    type: Literal["scroll_text"] = "scroll_text"
+    slot: Identifier
+    viewport: Box
+    style: TextStyle
+    required: bool = True
+    fade_length_px: Annotated[int, Field(ge=0)] = 80
+    scroll_speed_px_s: PositiveFloat = 50.0
+    start_offset_y_px: int = 160
+    begin_hold_s: Annotated[float, Field(ge=0)] = 5.0
+    end_hold_s: Annotated[float, Field(ge=0)] = 5.0
+
+
+ScrollLayer: TypeAlias = Annotated[  # noqa: UP040
+    BackgroundLayer | TextLayer | ScrollTextLayer,
+    Field(discriminator="type"),
+]
+
+
+class ScrollTemplate(StrictModel):
+    template_id: Identifier
+    revision: PositiveInt
+    canvas: Size
+    layers: tuple[ScrollLayer, ...]
+
+    @model_validator(mode="after")
+    def validate_layers(self) -> ScrollTemplate:
+        if not self.layers:
+            raise ValueError("scroll template must contain at least one layer")
+        ids = [layer.id for layer in self.layers]
+        if len(ids) != len(set(ids)):
+            raise ValueError("scroll template layer ids must be unique")
+        slots = [layer.slot for layer in self.layers]
+        if len(slots) != len(set(slots)):
+            raise ValueError("scroll template slots must be unique")
+        if sum(isinstance(layer, ScrollTextLayer) for layer in self.layers) > 1:
+            raise ValueError("scroll template supports at most one scroll_text layer")
+        for layer in self.layers:
+            geometry = (
+                layer.viewport if isinstance(layer, ScrollTextLayer) else layer.box
+            )
+            if not geometry.intersects(self.canvas):
+                raise ValueError(f"layer {layer.id} does not intersect the canvas")
+            if (
+                isinstance(layer, ScrollTextLayer)
+                and layer.fade_length_px * 2 > layer.viewport.size.height
+            ):
+                raise ValueError(
+                    f"scroll layer {layer.id} fade length exceeds its visible area"
+                )
+        return self
+
+
+class BackgroundBinding(StrictModel):
+    slot: Identifier
+    asset: LocalAsset
+
+    @model_validator(mode="after")
+    def validate_asset(self) -> BackgroundBinding:
+        if self.asset.media_type not in {AssetMediaType.IMAGE, AssetMediaType.VIDEO}:
+            raise ValueError("background asset must be image or video")
+        return self
+
+
+class TextBinding(StrictModel):
+    slot: Identifier
+    html: Annotated[str, StringConstraints(min_length=1)]
+    language: Annotated[
+        str, StringConstraints(strip_whitespace=True, min_length=2, max_length=16)
+    ]
+    font_size_scale: FontSizeScale = 1.0
+
+    @field_validator("html")
+    @classmethod
+    def reject_blank_html(cls, value: str) -> str:
+        if not re.sub(r"<[^>]+>|\s|&nbsp;", "", value, flags=re.IGNORECASE):
+            raise ValueError("html must contain visible text")
+        return value
+
+    @field_validator("language")
+    @classmethod
+    def normalize_language(cls, value: str) -> str:
+        return value.upper()
+
+
+class ScrollBindings(StrictModel):
+    backgrounds: tuple[BackgroundBinding, ...] = ()
+    texts: tuple[TextBinding, ...] = ()
+
+    @model_validator(mode="after")
+    def validate_unique_bindings(self) -> ScrollBindings:
+        slots = [item.slot for item in self.backgrounds] + [
+            item.slot for item in self.texts
+        ]
+        if len(slots) != len(set(slots)):
+            raise ValueError("each scroll slot may be bound at most once")
+        return self
+
+
+class AudioSpec(StrictModel):
+    mode: AudioMode = AudioMode.NONE
+    asset: LocalAsset | None = None
+    loop: bool = True
+    fade_in_s: Annotated[float, Field(ge=0)] = 1.0
+    fade_out_s: Annotated[float, Field(ge=0)] = 3.0
+    volume: Annotated[float, Field(gt=0, le=4)] = 1.0
+
+    @model_validator(mode="after")
+    def validate_asset(self) -> AudioSpec:
+        if self.mode == AudioMode.USE_ASSET:
+            if self.asset is None or self.asset.media_type != AssetMediaType.AUDIO:
+                raise ValueError("use_asset audio mode requires an audio asset")
+        elif self.asset is not None:
+            raise ValueError("audio asset is only valid for use_asset mode")
+        return self
+
+
+class FirstFrameSpec(StrictModel):
+    mode: FirstFrameMode = FirstFrameMode.COMPOSED
+    asset: LocalAsset | None = None
+
+    @model_validator(mode="after")
+    def validate_asset(self) -> FirstFrameSpec:
+        if self.mode == FirstFrameMode.ASSET:
+            if self.asset is None or self.asset.media_type != AssetMediaType.IMAGE:
+                raise ValueError("asset first-frame mode requires an image asset")
+        elif self.asset is not None:
+            raise ValueError("first-frame asset is only valid for asset mode")
+        return self
+
+
+class ImageOutputSpec(StrictModel):
+    format: Literal["png"] = "png"
+
+
+class PureImageRenderTask(StrictModel):
+    schema_version: Literal["2.0"] = "2.0"
+    kind: Literal["pure_image"] = "pure_image"
+    template: PureImageTemplate
+    bindings: PureImageBindings
+    output: ImageOutputSpec = ImageOutputSpec()
+
+
+class GraphicTextTemplate(StrictModel):
+    template_id: Identifier
+    revision: PositiveInt
+    canvas: Size
+    background_color: Color
+    image_layer: PureImageLayer
+    text_layer: TextLayer
+    rich_text: GraphicTextRichTextPolicy
+
+    @field_validator("background_color")
+    @classmethod
+    def normalize_background_color(cls, value: str) -> str:
+        return value.upper()
+
+    @model_validator(mode="after")
+    def validate_layers(self) -> GraphicTextTemplate:
+        layers = (self.image_layer, self.text_layer)
+        if self.image_layer.id == self.text_layer.id:
+            raise ValueError("graphic-text layer ids must be unique")
+        if self.image_layer.slot == self.text_layer.slot:
+            raise ValueError("graphic-text layer slots must be unique")
+        if self.image_layer.z_index >= self.text_layer.z_index:
+            raise ValueError("graphic-text image layer must be below the text layer")
+        if self.text_layer.style.adjust != TextAdjustMode.WIDTH:
+            raise ValueError("graphic-text text adjustment must be WIDTH")
+        for layer in layers:
+            box = layer.box
+            if (
+                box.position.x < 0
+                or box.position.y < 0
+                or box.position.x + box.size.width > self.canvas.width
+                or box.position.y + box.size.height > self.canvas.height
+            ):
+                raise ValueError(
+                    f"graphic-text layer {layer.id} must remain inside the canvas"
+                )
+        return self
+
+
+class GraphicTextBindings(StrictModel):
+    image: PureImageBinding
+    text: TextBinding
+
+
+class GraphicTextRenderTask(StrictModel):
+    schema_version: Literal["2.0"] = "2.0"
+    kind: Literal["graphic_text"] = "graphic_text"
+    template: GraphicTextTemplate
+    bindings: GraphicTextBindings
+    output: ImageOutputSpec = ImageOutputSpec()
+
+    @model_validator(mode="after")
+    def validate_rich_text(self) -> GraphicTextRenderTask:
+        parser = _GraphicTextHtmlParser(set(self.template.rich_text.allowed_colors))
+        parser.feed(self.bindings.text.html)
+        parser.close()
+        parser.validate_complete()
+        return self
+
+
+class VideoOutputSpec(StrictModel):
+    size: Size
+    fps: Annotated[int, Field(ge=1, le=120)] = 24
+    codec: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)] = (
+        "libx264"
+    )
+    audio_codec: Annotated[
+        str, StringConstraints(strip_whitespace=True, min_length=1)
+    ] = "aac"
+    crf: Annotated[int, Field(ge=0, le=51)] = 28
+    preset: Annotated[str, StringConstraints(strip_whitespace=True, min_length=1)] = (
+        "fast"
+    )
+    threads: Annotated[int, Field(ge=1, le=64)] = 6
+    metadata_comment: Annotated[str, StringConstraints(min_length=1)] = "orange"
+    minimum_duration_s: Annotated[float, Field(ge=0)] = 0.0
+
+
+class ScrollRenderTask(StrictModel):
+    schema_version: Literal["2.0"] = "2.0"
+    kind: Literal["scroll_video"] = "scroll_video"
+    template: ScrollTemplate
+    bindings: ScrollBindings
+    audio: AudioSpec = AudioSpec()
+    first_frame: FirstFrameSpec = FirstFrameSpec()
+    output: VideoOutputSpec
+
+
+class TimelineSubtitleLayout(StrictModel):
+    spacing_px: Annotated[int, Field(ge=0)] = 20
+
+
+class TimelineSubtitleTemplate(StrictModel):
+    box: Box
+    style: TextStyle
+    layout: TimelineSubtitleLayout = TimelineSubtitleLayout()
+    base_font_size: PositiveInt = 18
+    max_blocks_per_frame: Annotated[int, Field(ge=1, le=3)] | None = None
+
+    @model_serializer(mode="wrap")
+    def serialize_template(self, handler: Any) -> dict[str, Any]:
+        result = handler(self)
+        if self.max_blocks_per_frame is None:
+            result.pop("max_blocks_per_frame", None)
+        return result
+
+
+class TimelineTemplate(StrictModel):
+    template_id: Identifier
+    revision: PositiveInt
+    canvas: Size
+    subtitle: TimelineSubtitleTemplate
+
+    @model_validator(mode="after")
+    def validate_subtitle_box(self) -> TimelineTemplate:
+        if not self.subtitle.box.intersects(self.canvas):
+            raise ValueError("subtitle box does not intersect the canvas")
+        return self
+
+
+class WpmSubtitleGenerationOptions(StrictModel):
+    wpm: PositiveFloat | None = None
+    min_words_per_block: PositiveInt = 8
+    max_blocks_per_frame: Annotated[int, Field(ge=0, le=20)] = 2
+    track_mode: TrackMode = TrackMode.SEQUENTIAL
+
+
+class TimelineSubtitleBlock(StrictModel):
+    block_id: Identifier
+    html: Annotated[str, StringConstraints(min_length=1)]
+
+    @field_validator("html")
+    @classmethod
+    def reject_blank_html(cls, value: str) -> str:
+        if not re.sub(r"<[^>]+>|\s|&nbsp;", "", value, flags=re.IGNORECASE):
+            raise ValueError("html must contain visible text")
+        return value
+
+
+class TimelineSubtitleFrameItem(StrictModel):
+    block_id: Identifier
+    slot_index: Annotated[int, Field(ge=0)]
+    start_time_s: Annotated[float, Field(ge=0, allow_inf_nan=False)]
+    end_time_s: Annotated[float, Field(gt=0, allow_inf_nan=False)]
+
+    @model_validator(mode="after")
+    def validate_time_range(self) -> TimelineSubtitleFrameItem:
+        if self.end_time_s <= self.start_time_s:
+            raise ValueError("end_time_s must be greater than start_time_s")
+        return self
+
+
+class TimelineSubtitleFrameLayout(str, Enum):
+    STACK = "stack"
+    COLUMNS = "columns"
+
+
+class TimelineSubtitleFrameReveal(str, Enum):
+    TOGETHER = "together"
+    PROGRESSIVE = "progressive"
+
+
+class TimelineSubtitleFrame(StrictModel):
+    frame_id: Identifier
+    items: tuple[TimelineSubtitleFrameItem, ...]
+    layout: TimelineSubtitleFrameLayout | None = None
+    reveal: TimelineSubtitleFrameReveal | None = None
+
+    @model_serializer(mode="wrap")
+    def serialize_frame(self, handler: Any) -> dict[str, Any]:
+        result = handler(self)
+        if self.layout is None:
+            result.pop("layout", None)
+        if self.reveal is None:
+            result.pop("reveal", None)
+        return result
+
+    @model_validator(mode="after")
+    def validate_items(self) -> TimelineSubtitleFrame:
+        if not self.items:
+            raise ValueError("timeline subtitle frame must contain at least one item")
+        slot_indexes = [item.slot_index for item in self.items]
+        if len(slot_indexes) != len(set(slot_indexes)):
+            raise ValueError("timeline subtitle frame slot_index values must be unique")
+        if sorted(slot_indexes) != list(range(len(slot_indexes))):
+            raise ValueError("timeline subtitle frame slot_index values must start at zero and be contiguous")
+        return self
+
+
+class TimelineSubtitleConfig(StrictModel):
+    schema_version: Literal["1.0", "2.0"] = "1.0"
+    language: Annotated[
+        str, StringConstraints(strip_whitespace=True, min_length=2, max_length=16)
+    ]
+    font_size_scale: FontSizeScale = 1.0
+    blocks: tuple[TimelineSubtitleBlock, ...]
+    frames: tuple[TimelineSubtitleFrame, ...]
+
+    @field_validator("language")
+    @classmethod
+    def normalize_language(cls, value: str) -> str:
+        return value.upper()
+
+    @model_validator(mode="after")
+    def validate_references(self) -> TimelineSubtitleConfig:
+        if not self.blocks:
+            raise ValueError("timeline subtitle config must contain at least one block")
+        if not self.frames:
+            raise ValueError("timeline subtitle config must contain at least one frame")
+        block_ids = [block.block_id for block in self.blocks]
+        if len(block_ids) != len(set(block_ids)):
+            raise ValueError("timeline subtitle block ids must be unique")
+        frame_ids = [frame.frame_id for frame in self.frames]
+        if len(frame_ids) != len(set(frame_ids)):
+            raise ValueError("timeline subtitle frame ids must be unique")
+        known_block_ids = set(block_ids)
+        referenced_block_ids = [
+            item.block_id for frame in self.frames for item in frame.items
+        ]
+        unknown_block_ids = sorted(set(referenced_block_ids) - known_block_ids)
+        if unknown_block_ids:
+            raise ValueError(
+                f"timeline frames reference unknown block ids: {unknown_block_ids}"
+            )
+        if self.schema_version == "1.0":
+            if any(frame.layout is not None or frame.reveal is not None for frame in self.frames):
+                raise ValueError("timeline subtitle config 1.0 does not support layout or reveal")
+            return self
+        if any(frame.layout is None or frame.reveal is None for frame in self.frames):
+            raise ValueError("timeline subtitle config 2.0 requires layout and reveal")
+        if len(referenced_block_ids) != len(set(referenced_block_ids)):
+            raise ValueError("timeline subtitle config 2.0 blocks must be used once")
+        if set(referenced_block_ids) != known_block_ids:
+            raise ValueError("timeline subtitle config 2.0 frames must use every block")
+        for frame in self.frames:
+            item_count = len(frame.items)
+            if frame.layout == TimelineSubtitleFrameLayout.STACK and not 1 <= item_count <= 3:
+                raise ValueError("stack frame must contain 1..3 blocks")
+            if (
+                frame.layout == TimelineSubtitleFrameLayout.COLUMNS
+                and item_count != 2
+            ):
+                raise ValueError("columns frame must contain 2 blocks")
+        return self
+
+
+class TimelineBindings(StrictModel):
+    background: LocalAsset
+    subtitles: TimelineSubtitleConfig
+
+    @model_validator(mode="after")
+    def validate_background(self) -> TimelineBindings:
+        if self.background.media_type not in {
+            AssetMediaType.IMAGE,
+            AssetMediaType.VIDEO,
+        }:
+            raise ValueError("timeline background must be image or video")
+        return self
+
+
+class TimelineRenderTask(StrictModel):
+    schema_version: Literal["2.0"] = "2.0"
+    kind: Literal["timeline_video"] = "timeline_video"
+    template: TimelineTemplate
+    bindings: TimelineBindings
+    audio: AudioSpec = AudioSpec()
+    output: VideoOutputSpec
+
+
+RenderTask: TypeAlias = Annotated[  # noqa: UP040
+    PureImageRenderTask | GraphicTextRenderTask | ScrollRenderTask | TimelineRenderTask,
+    Field(discriminator="kind"),
+]