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

creative_render_engine/output_paths.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .errors import ConfigurationError, RenderError
+from .settings import settings
+
+
+def resolve_render_path(
+    output_path: str | Path | None,
+    *,
+    output_dir: str | Path | None,
+    output_filename: str | None,
+    kind: str,
+) -> Path:
+    root = settings.require_output_root()
+    if output_path is not None and (
+        output_dir is not None or output_filename is not None
+    ):
+        raise ConfigurationError(
+            "output_path cannot be combined with output_dir or output_filename",
+            code="conflicting_output_path_options",
+        )
+    if (output_dir is None) != (output_filename is None):
+        raise ConfigurationError(
+            "output_dir and output_filename must be provided together",
+            code="incomplete_output_path_options",
+        )
+    if output_path is not None:
+        destination = _under_root(root, output_path)
+    elif output_dir is not None and output_filename is not None:
+        directory = _under_root(root, output_dir)
+        destination = _under_root(root, directory / output_filename)
+    else:
+        suffix = ".png" if kind in {"pure_image", "graphic_text"} else ".mp4"
+        destination = _dated_root(root) / f"render-{uuid.uuid4().hex}{suffix}"
+    expected_suffix = ".png" if kind in {"pure_image", "graphic_text"} else ".mp4"
+    if destination.suffix.lower() != expected_suffix:
+        raise RenderError(
+            f"{kind} output path must use the {expected_suffix} extension",
+            code="invalid_output_extension",
+            field_path="output_path",
+        )
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    return destination
+
+
+def resolve_preview_dir(output_dir: str | Path | None) -> Path:
+    root = settings.require_output_root()
+    if output_dir is not None:
+        destination = _under_root(root, output_dir)
+    else:
+        destination = _dated_root(root) / f"preview-{uuid.uuid4().hex}"
+    destination.mkdir(parents=True, exist_ok=True)
+    return destination
+
+
+def _dated_root(root: Path) -> Path:
+    return root / datetime.now(timezone.utc).strftime("%Y%m%d")  # noqa: UP017
+
+
+def _under_root(root: Path, value: str | Path) -> Path:
+    candidate = Path(value).expanduser()
+    destination = (
+        candidate.resolve() if candidate.is_absolute() else (root / candidate).resolve()
+    )
+    if not destination.is_relative_to(root):
+        raise ConfigurationError(
+            f"output path must remain under settings.output_root: {destination}",
+            code="output_path_outside_root",
+            field_path="output_path",
+        )
+    return destination

creative_render_engine/plans.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Literal, TypeAlias
+
+from pydantic import ConfigDict, Field
+
+from .schemas import (
+    AudioMode,
+    Box,
+    CropMode,
+    FirstFrameMode,
+    HorizontalAlignment,
+    ImageOutputSpec,
+    Point,
+    PureImageLayer,
+    Size,
+    StrictModel,
+    TextAdjustMode,
+    VerticalAlignment,
+    VideoOutputSpec,
+)
+
+
+class PlanModel(StrictModel):
+    model_config = ConfigDict(
+        extra="forbid", frozen=True, arbitrary_types_allowed=False
+    )
+
+
+class ResolvedAsset(PlanModel):
+    id: str
+    path: Path
+    media_type: Literal["image", "video", "audio", "font"]
+    sha256: str
+    size: Size | None = None
+    duration_s: float | None = None
+
+
+class PureImageRenderPlanBody(PlanModel):
+    canvas: Size
+    layer: PureImageLayer
+    image: ResolvedAsset
+    output: ImageOutputSpec
+    asset_ids: tuple[str, ...]
+
+
+class GraphicTextMeasurement(PlanModel):
+    plain_text: str
+    image_width: int
+    image_height: int
+    line_count: int
+    fit_line_count: int
+    overflow_character_count: int
+    remaining_height_px: int
+    fill_ratio: float
+    fits: bool
+
+
+class ResolvedFontStyle(PlanModel):
+    font: ResolvedAsset
+    font_size: int
+    line_spacing: int
+    color: str
+    alignment: HorizontalAlignment
+    stroke_size: int
+    stroke_color: str
+
+
+class ResolvedMaskStyle(PlanModel):
+    mode: int
+    color: str
+    offset: Point
+    corner_radius: int
+
+
+class ResolvedTextStyle(PlanModel):
+    font: ResolvedFontStyle
+    mask: ResolvedMaskStyle
+    padding: Point
+    adjust: TextAdjustMode
+    vertical_alignment: VerticalAlignment
+    min_words_per_block: int
+
+
+class ResolvedAudioSpec(PlanModel):
+    mode: AudioMode
+    asset: ResolvedAsset | None
+    loop: bool
+    fade_in_s: float
+    fade_out_s: float
+    volume: float
+
+
+class ResolvedFirstFrameSpec(PlanModel):
+    mode: FirstFrameMode
+    asset: ResolvedAsset | None
+
+
+class ScrollBackgroundPlan(PlanModel):
+    type: Literal["background"] = "background"
+    id: str
+    z_index: int
+    box: Box
+    opacity: int
+    crop: CropMode
+    asset: ResolvedAsset
+
+
+class ScrollTextPlan(PlanModel):
+    type: Literal["text"] = "text"
+    id: str
+    z_index: int
+    box: Box
+    opacity: int
+    html: str
+    language: str
+    style: ResolvedTextStyle
+
+
+class GraphicTextRenderPlanBody(PlanModel):
+    canvas: Size
+    background_color: str
+    image_layer: PureImageLayer
+    image: ResolvedAsset
+    text: ScrollTextPlan
+    measurement: GraphicTextMeasurement
+    output: ImageOutputSpec
+    asset_ids: tuple[str, ...]
+
+
+class ScrollLongTextPlan(PlanModel):
+    type: Literal["scroll_text"] = "scroll_text"
+    id: str
+    z_index: int
+    viewport: Box
+    opacity: int
+    html: str
+    language: str
+    style: ResolvedTextStyle
+    fade_length_px: int
+    scroll_speed_px_s: float
+    start_offset_y_px: int
+    start_y_px: int
+    end_y_px: int
+    begin_hold_s: float
+    end_hold_s: float
+    estimated_image_size: Size
+    scroll_distance_px: float
+    scroll_duration_s: float
+
+
+ScrollPlanLayer: TypeAlias = Annotated[  # noqa: UP040
+    ScrollBackgroundPlan | ScrollTextPlan | ScrollLongTextPlan,
+    Field(discriminator="type"),
+]
+
+
+class ScrollRenderPlanBody(PlanModel):
+    canvas: Size
+    layers: tuple[ScrollPlanLayer, ...]
+    audio: ResolvedAudioSpec
+    first_frame: ResolvedFirstFrameSpec
+    output: VideoOutputSpec
+    duration_s: float
+    asset_ids: tuple[str, ...]
+
+
+class TimelineWordPlan(PlanModel):
+    word: str
+    color: str | None = None
+    font_size: int | None = None
+    force_newline: bool = False
+    leading_space: bool = False
+    glue_to_previous: bool = False
+
+
+class TimelineBlockPlan(PlanModel):
+    block_id: str
+    plain_text: str
+    colored_words: tuple[TimelineWordPlan, ...]
+    renderer_block: dict
+    size: Size
+
+
+class TimelineBlockTimingPlan(PlanModel):
+    block_id: str
+    position: Point
+    start_time_s: float
+    end_time_s: float
+
+
+class TimelineFramePlan(PlanModel):
+    frame_id: str
+    frame_index: int
+    start_time_s: float
+    end_time_s: float
+    timings: tuple[TimelineBlockTimingPlan, ...]
+
+
+class TimelineRenderPlanBody(PlanModel):
+    canvas: Size
+    subtitle_box: Box
+    style: ResolvedTextStyle
+    language: str
+    spacing_px: int
+    base_font_size: int
+    background: ResolvedAsset
+    audio: ResolvedAudioSpec
+    output: VideoOutputSpec
+    duration_s: float
+    blocks: tuple[TimelineBlockPlan, ...]
+    frames: tuple[TimelineFramePlan, ...]
+    asset_ids: tuple[str, ...]
+
+
+class PureImageRenderPlan(PlanModel):
+    schema_version: Literal["1.0"] = "1.0"
+    kind: Literal["pure_image"] = "pure_image"
+    template_id: str
+    template_revision: int
+    plan_hash: str
+    body: PureImageRenderPlanBody
+
+
+class GraphicTextRenderPlan(PlanModel):
+    schema_version: Literal["1.0"] = "1.0"
+    kind: Literal["graphic_text"] = "graphic_text"
+    template_id: str
+    template_revision: int
+    plan_hash: str
+    body: GraphicTextRenderPlanBody
+
+
+class ScrollRenderPlan(PlanModel):
+    schema_version: Literal["1.0"] = "1.0"
+    kind: Literal["scroll_video"] = "scroll_video"
+    template_id: str
+    template_revision: int
+    plan_hash: str
+    body: ScrollRenderPlanBody
+
+
+class TimelineRenderPlan(PlanModel):
+    schema_version: Literal["1.0"] = "1.0"
+    kind: Literal["timeline_video"] = "timeline_video"
+    template_id: str
+    template_revision: int
+    plan_hash: str
+    body: TimelineRenderPlanBody
+
+
+RenderPlan: TypeAlias = Annotated[  # noqa: UP040
+    PureImageRenderPlan | GraphicTextRenderPlan | ScrollRenderPlan | TimelineRenderPlan,
+    Field(discriminator="kind"),
+]
+
+
+class PreviewItem(PlanModel):
+    path: Path
+    timestamp_s: float
+    sha256: str
+    size_bytes: int
+    size: Size
+
+
+class PreviewManifest(PlanModel):
+    plan_hash: str
+    items: tuple[PreviewItem, ...]
+
+
+class VideoRenderOutput(PlanModel):
+    path: Path
+    sha256: str
+    size_bytes: int
+    width: int
+    height: int
+    duration_s: float
+    fps: float
+    media_type: Literal["video/mp4"] = "video/mp4"
+
+
+class ImageRenderOutput(PlanModel):
+    path: Path
+    sha256: str
+    size_bytes: int
+    width: int
+    height: int
+    media_type: Literal["image/png"] = "image/png"
+
+
+RenderOutput: TypeAlias = Annotated[  # noqa: UP040
+    VideoRenderOutput | ImageRenderOutput,
+    Field(discriminator="media_type"),
+]
+
+
+class EngineVersions(PlanModel):
+    creative_render_engine: str
+    text_block_renderer: str
+    moviepy: str
+    pillow: str
+    ffmpeg: str | None = None
+
+
+class RenderManifest(PlanModel):
+    plan_hash: str
+    output: RenderOutput
+    assets: tuple[ResolvedAsset, ...]
+    engine_versions: EngineVersions

creative_render_engine/preview.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from contextlib import ExitStack, suppress
+from itertools import pairwise
+from pathlib import Path
+
+from PIL import Image
+
+from .engines.common import (
+    compose_scroll_frame,
+    compose_timeline_frame,
+    prepare_scroll_frames,
+    prepare_timeline_frames,
+)
+from .engines.pure_image import compose_graphic_text, compose_pure_image
+from .errors import RenderError
+from .hashing import file_sha256
+from .plans import (
+    GraphicTextRenderPlan,
+    PreviewItem,
+    PreviewManifest,
+    PureImageRenderPlan,
+    RenderPlan,
+    ScrollLongTextPlan,
+    ScrollRenderPlan,
+    TimelineRenderPlan,
+)
+from .schemas import Size
+
+MAX_TIMELINE_PREVIEW_FRAMES = 20
+
+
+def preview_plan(
+    plan: RenderPlan,
+    output_dir: str | Path,
+    *,
+    timestamps: Sequence[float] | None = None,
+) -> PreviewManifest:
+    destination = Path(output_dir).expanduser().resolve()
+    destination.mkdir(parents=True, exist_ok=True)
+    workspace = destination / f".workspace-{plan.plan_hash[:12]}"
+    workspace.mkdir(parents=True, exist_ok=True)
+    items: list[PreviewItem] = []
+    try:
+        with ExitStack() as stack:
+            frame_function: Callable[[float], Image.Image]
+            if isinstance(plan, PureImageRenderPlan):
+                resolved_timestamps = _preview_timestamps(plan, timestamps)
+
+                def pure_image_frame(_value: float) -> Image.Image:
+                    return compose_pure_image(plan)
+
+                frame_function = pure_image_frame
+            elif isinstance(plan, GraphicTextRenderPlan):
+                resolved_timestamps = _preview_timestamps(plan, timestamps)
+
+                def graphic_text_frame(_value: float) -> Image.Image:
+                    return compose_graphic_text(plan)
+
+                frame_function = graphic_text_frame
+            elif isinstance(plan, ScrollRenderPlan):
+                prepared = prepare_scroll_frames(plan, workspace, stack)
+                resolved_timestamps = _preview_timestamps(plan, timestamps)
+
+                def scroll_frame(value: float) -> Image.Image:
+                    return compose_scroll_frame(plan, prepared, value)
+
+                frame_function = scroll_frame
+            elif isinstance(plan, TimelineRenderPlan):
+                background, block_images = prepare_timeline_frames(plan, stack)
+                resolved_timestamps = _preview_timestamps(plan, timestamps)
+
+                def timeline_frame(value: float) -> Image.Image:
+                    return compose_timeline_frame(
+                        plan,
+                        background,
+                        block_images,
+                        value,
+                    )
+
+                frame_function = timeline_frame
+            else:
+                raise RenderError(
+                    "unsupported preview plan", code="invalid_render_plan"
+                )
+            for index, timestamp in enumerate(resolved_timestamps):
+                output_path = destination / f"preview-{index:03d}-{timestamp:.3f}.jpg"
+                image = frame_function(timestamp)
+                image.convert("RGB").save(output_path, format="JPEG", quality=90)
+                items.append(
+                    PreviewItem(
+                        path=output_path,
+                        timestamp_s=round(timestamp, 6),
+                        sha256=file_sha256(output_path),
+                        size_bytes=output_path.stat().st_size,
+                        size=Size(width=image.width, height=image.height),
+                    )
+                )
+    except RenderError:
+        raise
+    except Exception as exc:
+        raise RenderError(
+            "failed to generate preview frames",
+            code="preview_failed",
+        ) from exc
+    finally:
+        _remove_workspace(workspace)
+    if not items:
+        raise RenderError("preview produced no images", code="empty_preview")
+    return PreviewManifest(plan_hash=plan.plan_hash, items=tuple(items))
+
+
+def _preview_timestamps(
+    plan: RenderPlan,
+    timestamps: Sequence[float] | None,
+) -> tuple[float, ...]:
+    if timestamps is None:
+        if isinstance(plan, (PureImageRenderPlan, GraphicTextRenderPlan)):
+            return (0.0,)
+        if isinstance(plan, ScrollRenderPlan):
+            return _scroll_timestamps(plan)
+        if isinstance(plan, TimelineRenderPlan):
+            return _timeline_timestamps(plan)
+        raise RenderError("unsupported preview plan", code="invalid_render_plan")
+    if not timestamps:
+        raise RenderError(
+            "explicit preview timestamps must not be empty",
+            code="invalid_preview_timestamps",
+            field_path="timestamps",
+        )
+    if isinstance(plan, (PureImageRenderPlan, GraphicTextRenderPlan)):
+        duration = 0.0
+    elif isinstance(plan, (ScrollRenderPlan, TimelineRenderPlan)):
+        duration = plan.body.duration_s
+    else:
+        raise RenderError("unsupported preview plan", code="invalid_render_plan")
+    values: list[float] = []
+    for index, raw_value in enumerate(timestamps):
+        try:
+            value = float(raw_value)
+        except (TypeError, ValueError) as exc:
+            raise RenderError(
+                "preview timestamp must be a finite number",
+                code="invalid_preview_timestamps",
+                field_path=f"timestamps.{index}",
+            ) from exc
+        if not 0 <= value <= duration:
+            raise RenderError(
+                f"preview timestamp must be within 0 and {duration}",
+                code="invalid_preview_timestamps",
+                field_path=f"timestamps.{index}",
+            )
+        values.append(round(value, 6))
+    return tuple(dict.fromkeys(values))
+
+
+def _scroll_timestamps(plan: ScrollRenderPlan) -> tuple[float, ...]:
+    scroll_layer = next(
+        (layer for layer in plan.body.layers if isinstance(layer, ScrollLongTextPlan)),
+        None,
+    )
+    if scroll_layer is None:
+        return (0.0,)
+    movement_middle = scroll_layer.begin_hold_s + scroll_layer.scroll_duration_s / 2
+    end = max(0.0, plan.body.duration_s - min(0.001, plan.body.duration_s / 2))
+    return tuple(sorted({0.0, round(movement_middle, 6), round(end, 6)}))
+
+
+def _timeline_timestamps(plan: TimelineRenderPlan) -> tuple[float, ...]:
+    time_points = sorted(
+        {
+            value
+            for frame in plan.body.frames
+            for timing in frame.timings
+            for value in (timing.start_time_s, timing.end_time_s)
+        }
+    )
+    values = [
+        (start + end) / 2
+        for start, end in pairwise(time_points)
+        if any(
+            timing.start_time_s <= start and timing.end_time_s >= end
+            for frame in plan.body.frames
+            for timing in frame.timings
+        )
+    ]
+    if len(values) <= MAX_TIMELINE_PREVIEW_FRAMES:
+        return tuple(values)
+    step = (len(values) - 1) / (MAX_TIMELINE_PREVIEW_FRAMES - 1)
+    return tuple(
+        values[round(index * step)] for index in range(MAX_TIMELINE_PREVIEW_FRAMES)
+    )
+
+
+def _remove_workspace(path: Path) -> None:
+    if not path.exists():
+        return
+    for child in path.iterdir():
+        if child.is_file():
+            child.unlink()
+    with suppress(OSError):
+        path.rmdir()