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

creative_render_engine/engines/common.py

@@ -0,0 +1,484 @@
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+from collections.abc import Callable
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from moviepy import AudioFileClip, VideoFileClip, afx
+from PIL import Image, ImageChops, ImageDraw
+from proglog import ProgressBarLogger
+from textblockrenderer import (
+    ColoredSubtitleBlock,
+    FontSpec,
+    RenderConstraint,
+    RenderStyle,
+    SplitConfig,
+    TextMeasurer,
+    render_colored_block,
+    render_text_image,
+    text_to_long_image,
+)
+
+from ..errors import RenderError
+from ..plans import (
+    ResolvedAsset,
+    ResolvedAudioSpec,
+    ResolvedTextStyle,
+    ScrollBackgroundPlan,
+    ScrollLongTextPlan,
+    ScrollRenderPlan,
+    ScrollTextPlan,
+    TimelineBlockPlan,
+    TimelineRenderPlan,
+)
+from ..schemas import AudioMode, CropMode
+
+# pyright: reportMissingImports=false, reportArgumentType=false, reportAttributeAccessIssue=false
+
+logger = logging.getLogger(__name__)
+
+_VIDEO_PROGRESS_INTERVAL_FRAMES = 100
+
+
+class _FrameIntervalProgressLogger(ProgressBarLogger):
+    def __init__(self) -> None:
+        super().__init__(logged_bars=None)
+        self._next_frame_report = _VIDEO_PROGRESS_INTERVAL_FRAMES
+
+    def callback(self, **changes: Any) -> None:
+        message = str(changes.get("message") or "").rstrip()
+        if message:
+            logger.info(message)
+
+    def bars_callback(
+        self,
+        bar: str,
+        attr: str,
+        value: int,
+        old_value: int | None = None,
+    ) -> None:
+        if bar != "frame_index" or attr != "index" or value <= 0:
+            return
+        if old_value is not None and value < old_value:
+            self._next_frame_report = _VIDEO_PROGRESS_INTERVAL_FRAMES
+        while value >= self._next_frame_report:
+            logger.info(
+                "MoviePy - frame_index: %s/%s",
+                self._next_frame_report,
+                self.bars[bar]["total"],
+            )
+            self._next_frame_report += _VIDEO_PROGRESS_INTERVAL_FRAMES
+
+
+FrameProvider = Callable[[float], Image.Image]
+
+
+def resize_image(image: Image.Image, target_size: tuple[int, int], mode: CropMode | str) -> Image.Image:
+    mode_value = CropMode(mode)
+    target_width, target_height = target_size
+    source = image.convert("RGBA")
+    if mode_value == CropMode.STRETCH:
+        return source.resize((target_width, target_height), Image.Resampling.LANCZOS)
+    source_ratio = source.width / source.height
+    target_ratio = target_width / target_height
+    if mode_value == CropMode.COVER:
+        if source_ratio > target_ratio:
+            new_height = target_height
+            new_width = int(source.width * (new_height / source.height))
+        else:
+            new_width = target_width
+            new_height = int(source.height * (new_width / source.width))
+        resized = source.resize((new_width, new_height), Image.Resampling.LANCZOS)
+        left = (new_width - target_width) // 2
+        top = (new_height - target_height) // 2
+        return resized.crop((left, top, left + target_width, top + target_height))
+    if source_ratio > target_ratio:
+        new_width = target_width
+        new_height = int(source.height * (new_width / source.width))
+    else:
+        new_height = target_height
+        new_width = int(source.width * (new_height / source.height))
+    resized = source.resize((new_width, new_height), Image.Resampling.LANCZOS)
+    canvas = Image.new("RGBA", (target_width, target_height), (0, 0, 0, 0))
+    canvas.alpha_composite(resized, ((target_width - new_width) // 2, (target_height - new_height) // 2))
+    return canvas
+
+
+def apply_opacity(image: Image.Image, opacity: int) -> Image.Image:
+    result = image.convert("RGBA")
+    if opacity >= 255:
+        return result
+    red, green, blue, alpha = result.split()
+    adjusted_alpha = alpha.point(lambda value: int(value * opacity / 255))
+    return Image.merge("RGBA", (red, green, blue, adjusted_alpha))
+
+
+def create_scroll_mask(width: int, height: int, fade_length: int) -> Image.Image:
+    if fade_length <= 0:
+        return Image.new("L", (width, height), 255)
+    mask = Image.new("L", (width, height), 255)
+    draw = ImageDraw.Draw(mask)
+    for offset in range(fade_length):
+        top_alpha = int(offset / fade_length * 255)
+        bottom_alpha = int((fade_length - offset) / fade_length * 255)
+        draw.line((0, offset, width, offset), fill=top_alpha)
+        y = height - fade_length + offset
+        draw.line((0, y, width, y), fill=bottom_alpha)
+    return mask
+
+
+def render_text_plan(layer: ScrollTextPlan, output_path: Path) -> Image.Image:
+    style = layer.style
+    try:
+        render_text_image(
+            html_text=layer.html,
+            font_spec=_font_spec(style),
+            constraint=RenderConstraint(
+                max_width=layer.box.size.width,
+                max_height=layer.box.size.height,
+                min_width=layer.box.size.width if style.adjust.value == "WIDTH" else 0,
+            ),
+            output_path=str(output_path),
+            adjust=style.adjust.value,
+            vertical_align=style.vertical_alignment.value,
+            split_config=_split_config(style, layer.language),
+            style=_render_style(style),
+            base_font_size=18,
+        )
+        with Image.open(output_path) as image:
+            return image.convert("RGBA").copy()
+    except Exception as exc:
+        raise RenderError(
+            f"failed to render text layer {layer.id}",
+            code="text_render_failed",
+            field_path=f"layers.{layer.id}",
+        ) from exc
+
+
+def render_long_text_plan(layer: ScrollLongTextPlan, output_path: Path) -> Image.Image:
+    style = layer.style
+    try:
+        text_to_long_image(
+            html_text=layer.html,
+            font_spec=_font_spec(style),
+            constraint=RenderConstraint(max_width=layer.viewport.size.width, max_height=0, min_width=0),
+            output_path=str(output_path),
+            split_config=_split_config(style, layer.language),
+            style=_render_style(style),
+            base_font_size=18,
+        )
+        with Image.open(output_path) as image:
+            return image.convert("RGBA").copy()
+    except Exception as exc:
+        raise RenderError(
+            f"failed to render scrolling text layer {layer.id}",
+            code="scroll_text_render_failed",
+            field_path=f"layers.{layer.id}",
+        ) from exc
+
+
+def render_timeline_block(block: TimelineBlockPlan, plan: TimelineRenderPlan) -> Image.Image:
+    style = plan.body.style
+    colored_block = ColoredSubtitleBlock.model_validate(block.renderer_block)
+    try:
+        return render_colored_block(
+            block=colored_block,
+            measurer=TextMeasurer(_font_spec(style), stroke_size=style.font.stroke_size),
+            default_color=style.font.color,
+            align=style.font.alignment.value,
+            padding=(style.padding.x, style.padding.y),
+            mask_offset=(style.mask.offset.x, style.mask.offset.y),
+            mask_mode=style.mask.mode,
+            mask_color=style.mask.color,
+            mask_radius=style.mask.corner_radius,
+            stroke_size=style.font.stroke_size,
+            stroke_color=style.font.stroke_color,
+            target_width=block.size.width,
+            target_height=block.size.height,
+        ).convert("RGBA")
+    except Exception as exc:
+        raise RenderError(
+            f"failed to render timeline block {block.block_id}",
+            code="timeline_block_render_failed",
+            field_path=f"blocks.{block.block_id}",
+        ) from exc
+
+
+def prepare_scroll_frames(plan: ScrollRenderPlan, workspace: Path, stack: ExitStack):
+    workspace.mkdir(parents=True, exist_ok=True)
+    prepared: dict[str, Image.Image | FrameProvider] = {}
+    for layer in plan.body.layers:
+        if isinstance(layer, ScrollBackgroundPlan):
+            prepared[layer.id] = _scroll_asset_provider(layer.asset, layer.box.size.model_dump(), layer.crop, stack)
+        elif isinstance(layer, ScrollTextPlan):
+            prepared[layer.id] = render_text_plan(layer, workspace / f"{layer.id}.png")
+        elif isinstance(layer, ScrollLongTextPlan):
+            prepared[layer.id] = render_long_text_plan(layer, workspace / f"{layer.id}.png")
+    return prepared
+
+
+def compose_scroll_frame(
+    plan: ScrollRenderPlan,
+    prepared: dict[str, Image.Image | FrameProvider],
+    timestamp_s: float,
+    *,
+    hide_text: bool = False,
+) -> Image.Image:
+    canvas = Image.new(
+        "RGB",
+        (plan.body.canvas.width, plan.body.canvas.height),
+        (0, 0, 0, 255),
+    )
+    frame_index = int(timestamp_s * plan.body.output.fps)
+    frame_time_s = frame_index / plan.body.output.fps
+    for layer in plan.body.layers:
+        if hide_text and isinstance(layer, (ScrollTextPlan, ScrollLongTextPlan)):
+            continue
+        value = prepared[layer.id]
+        image = value(frame_time_s) if callable(value) else value.copy()
+        if isinstance(layer, ScrollLongTextPlan):
+            viewport = layer.viewport
+            visible = Image.new("RGBA", (viewport.size.width, viewport.size.height), (0, 0, 0, 0))
+            scroll_y = _scroll_y(layer, frame_time_s)
+            x = (viewport.size.width - image.width) // 2
+            if scroll_y + image.height > 0 and scroll_y < viewport.size.height:
+                visible.paste(image, (x, scroll_y))
+            original_alpha = visible.getchannel("A")
+            visible.putalpha(
+                ImageChops.multiply(
+                    original_alpha,
+                    create_scroll_mask(viewport.size.width, viewport.size.height, layer.fade_length_px),
+                )
+            )
+            canvas.paste(visible, (viewport.position.x, viewport.position.y), visible)
+            continue
+        position = (layer.box.position.x, layer.box.position.y)
+        if isinstance(layer, ScrollTextPlan):
+            x_offset = (layer.box.size.width - image.width) // 2
+            if layer.style.vertical_alignment.value == "top":
+                y_offset = 0
+            elif layer.style.vertical_alignment.value == "bottom":
+                y_offset = layer.box.size.height - image.height
+            else:
+                y_offset = (layer.box.size.height - image.height) // 2
+            position = (position[0] + x_offset, position[1] + y_offset)
+        if layer.opacity < 255:
+            image = apply_opacity(image, layer.opacity)
+            canvas.paste(image, position, image)
+        elif image.mode == "RGBA":
+            canvas.paste(image, position, image)
+        else:
+            canvas.paste(image, position)
+    return canvas
+
+
+def prepare_timeline_frames(plan: TimelineRenderPlan, stack: ExitStack):
+    background = _timeline_asset_provider(
+        plan.body.background,
+        plan.body.canvas.model_dump(),
+        stack,
+    )
+    block_images = {block.block_id: render_timeline_block(block, plan) for block in plan.body.blocks}
+    return background, block_images
+
+
+def compose_timeline_frame(
+    plan: TimelineRenderPlan,
+    background: Image.Image | FrameProvider,
+    block_images: dict[str, Image.Image],
+    timestamp_s: float,
+) -> Image.Image:
+    value = background(timestamp_s) if callable(background) else background.copy()
+    frame = value.convert("RGB")
+    for item in plan.body.frames:
+        for timing in item.timings:
+            if timing.start_time_s <= timestamp_s < timing.end_time_s:
+                block_image = block_images[timing.block_id]
+                frame.paste(block_image, (timing.position.x, timing.position.y), block_image)
+    return frame
+
+
+def open_audio_clip(spec: ResolvedAudioSpec, background: ResolvedAsset, duration: float, stack: ExitStack):
+    clip = None
+    if spec.mode == AudioMode.USE_ASSET and spec.asset is not None:
+        clip = stack.enter_context(AudioFileClip(str(spec.asset.path)))
+    elif spec.mode == AudioMode.USE_BACKGROUND and background.media_type == "video":
+        clip = stack.enter_context(AudioFileClip(str(background.path)))
+    if clip is None:
+        return None
+    if spec.loop and clip.duration < duration:
+        clip = clip.with_effects([afx.AudioLoop(duration=duration)])
+    elif clip.duration >= duration:
+        clip = clip.subclipped(0, duration)
+    effects = []
+    if spec.volume != 1.0:
+        effects.append(afx.MultiplyVolume(factor=spec.volume))
+    if spec.fade_in_s:
+        effects.append(afx.AudioFadeIn(duration=spec.fade_in_s))
+    if spec.fade_out_s:
+        effects.append(afx.AudioFadeOut(duration=spec.fade_out_s))
+    return clip.with_effects(effects) if effects else clip
+
+
+def write_video(
+    output_path: Path,
+    frame_function,
+    duration: float,
+    fps: int,
+    output_spec,
+    audio_clip,
+    *,
+    show_progress: bool = False,
+) -> None:
+    from moviepy import VideoClip
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_audio_path = Path(tempfile.gettempdir()) / f"creative-render-engine-{os.getpid()}-{output_path.stem}.m4a"
+    clip = VideoClip(lambda timestamp: np.array(frame_function(timestamp)), duration=duration)
+    clip.fps = fps
+    if audio_clip is not None:
+        clip.audio = audio_clip
+    try:
+        clip.write_videofile(
+            str(output_path),
+            fps=fps,
+            codec=output_spec.codec,
+            audio_codec=output_spec.audio_codec,
+            temp_audiofile=str(temp_audio_path),
+            remove_temp=True,
+            threads=output_spec.threads,
+            preset=output_spec.preset,
+            ffmpeg_params=[
+                "-crf",
+                str(output_spec.crf),
+                "-metadata",
+                f"comment={output_spec.metadata_comment}",
+            ],
+            logger=_FrameIntervalProgressLogger() if show_progress else None,
+        )
+    except Exception as exc:
+        raise RenderError(
+            f"failed to write video: {output_path}",
+            code="video_write_failed",
+        ) from exc
+    finally:
+        clip.close()
+        if temp_audio_path.exists():
+            temp_audio_path.unlink()
+
+
+def _scroll_asset_provider(
+    asset: ResolvedAsset,
+    raw_size: dict[str, int],
+    crop: CropMode,
+    stack: ExitStack,
+):
+    target_size = (int(raw_size["width"]), int(raw_size["height"]))
+    if asset.media_type == "image":
+        with Image.open(asset.path) as image:
+            return resize_image(image.copy(), target_size, crop)
+    target_width, target_height = target_size
+    if crop == CropMode.COVER:
+        clip = stack.enter_context(
+            VideoFileClip(
+                str(asset.path),
+                target_resolution=(target_width, None),
+                resize_algorithm="fast_bilinear",
+                audio=False,
+            )
+        )
+        clip = clip.cropped(
+            width=target_width,
+            height=target_height,
+            x_center=target_width // 2,
+            y_center=clip.size[1] // 2,
+        )
+
+        def cover_provider(timestamp_s: float) -> Image.Image:
+            timestamp = timestamp_s % clip.duration if clip.duration else 0.0
+            return Image.fromarray(clip.get_frame(timestamp))
+
+        return cover_provider
+
+    clip = stack.enter_context(VideoFileClip(str(asset.path), audio=False))
+
+    def fitted_provider(timestamp_s: float) -> Image.Image:
+        timestamp = timestamp_s % clip.duration if clip.duration else 0.0
+        frame = Image.fromarray(clip.get_frame(timestamp))
+        return resize_image(frame, target_size, crop)
+
+    return fitted_provider
+
+
+def _timeline_asset_provider(
+    asset: ResolvedAsset,
+    raw_size: dict[str, int],
+    stack: ExitStack,
+):
+    target_width = int(raw_size["width"])
+    target_height = int(raw_size["height"])
+    if asset.media_type == "image":
+        with Image.open(asset.path) as image:
+            return resize_image(image.copy(), (target_width, target_height), CropMode.COVER)
+    clip = stack.enter_context(VideoFileClip(str(asset.path), audio=False))
+    original_width, original_height = clip.size
+    source_ratio = original_width / original_height
+    target_ratio = target_width / target_height
+    scale_factor = target_height / original_height if source_ratio > target_ratio else target_width / original_width
+    new_width = int(original_width * scale_factor)
+    new_height = int(original_height * scale_factor)
+    clip = clip.resized((new_width, new_height)).cropped(
+        width=target_width,
+        height=target_height,
+        x_center=new_width // 2,
+        y_center=new_height // 2,
+    )
+
+    def provider(timestamp_s: float) -> Image.Image:
+        timestamp = timestamp_s % clip.duration if clip.duration else 0.0
+        return Image.fromarray(clip.get_frame(timestamp))
+
+    return provider
+
+
+def _scroll_y(layer: ScrollLongTextPlan, timestamp_s: float) -> int:
+    if timestamp_s < layer.begin_hold_s:
+        return layer.start_y_px
+    if timestamp_s < layer.begin_hold_s + layer.scroll_duration_s:
+        current_y = layer.start_y_px - (
+            timestamp_s - layer.begin_hold_s
+        ) * layer.scroll_speed_px_s
+        return max(layer.end_y_px, int(current_y))
+    return layer.end_y_px
+
+
+def _font_spec(style: ResolvedTextStyle) -> FontSpec:
+    return FontSpec(
+        font_path=str(style.font.font.path),
+        font_size=style.font.font_size,
+        line_spacing=style.font.line_spacing,
+    )
+
+
+def _split_config(style: ResolvedTextStyle, language: str) -> SplitConfig:
+    return SplitConfig(min_words_per_block=style.min_words_per_block, language=language.upper())
+
+
+def _render_style(style: ResolvedTextStyle) -> RenderStyle:
+    return 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,
+    )

creative_render_engine/engines/pure_image.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import hashlib
+import tempfile
+from io import BytesIO
+from pathlib import Path
+from typing import cast
+
+from PIL import Image, ImageColor, ImageOps
+
+from ..errors import RenderError
+from ..plans import GraphicTextRenderPlan, PureImageRenderPlan, ResolvedAsset
+from .common import render_text_plan, resize_image
+
+
+def _load_static_image(asset: ResolvedAsset) -> Image.Image:
+    content = asset.path.read_bytes()
+    if hashlib.sha256(content).hexdigest() != asset.sha256:
+        raise RenderError(
+            "static image sha256 changed after compile",
+            code="asset_hash_mismatch",
+            field_path="body.image.sha256",
+        )
+    with Image.open(BytesIO(content)) as image:
+        if (
+            bool(getattr(image, "is_animated", False))
+            or getattr(image, "n_frames", 1) > 1
+        ):
+            raise RenderError(
+                "animated images are not supported for static image rendering",
+                code="animated_image_not_supported",
+                field_path="body.image.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()
+        return oriented.copy()
+
+
+def compose_pure_image(plan: PureImageRenderPlan) -> Image.Image:
+    try:
+        return resize_image(
+            _load_static_image(plan.body.image),
+            (plan.body.canvas.width, plan.body.canvas.height),
+            plan.body.layer.fit,
+        )
+    except RenderError:
+        raise
+    except Exception as exc:
+        raise RenderError(
+            f"failed to compose pure image: {plan.body.image.path}",
+            code="pure_image_compose_failed",
+            field_path="body.image.path",
+        ) from exc
+
+
+def compose_graphic_text(plan: GraphicTextRenderPlan) -> Image.Image:
+    try:
+        canvas = Image.new(
+            "RGBA",
+            (plan.body.canvas.width, plan.body.canvas.height),
+            ImageColor.getcolor(plan.body.background_color, "RGBA"),
+        )
+        image_layer = plan.body.image_layer
+        image = resize_image(
+            _load_static_image(plan.body.image),
+            (image_layer.box.size.width, image_layer.box.size.height),
+            image_layer.fit,
+        )
+        canvas.paste(
+            image,
+            (image_layer.box.position.x, image_layer.box.position.y),
+            image if image.mode == "RGBA" else None,
+        )
+        with tempfile.TemporaryDirectory(
+            prefix="creative-render-engine-graphic-text-"
+        ) as value:
+            text = render_text_plan(plan.body.text, Path(value) / "text.png")
+        text_layer = plan.body.text
+        x = text_layer.box.position.x + (text_layer.box.size.width - text.width) // 2
+        if text_layer.style.vertical_alignment.value == "top":
+            y_offset = 0
+        elif text_layer.style.vertical_alignment.value == "bottom":
+            y_offset = text_layer.box.size.height - text.height
+        else:
+            y_offset = (text_layer.box.size.height - text.height) // 2
+        y = text_layer.box.position.y + y_offset
+        canvas.paste(text, (x, y), text)
+        return canvas
+    except RenderError:
+        raise
+    except Exception as exc:
+        raise RenderError(
+            f"failed to compose graphic text: {plan.body.image.path}",
+            code="graphic_text_compose_failed",
+            field_path="body.image.path",
+        ) from exc

creative_render_engine/errors.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+class CreativeRenderEngineError(Exception):
+    """Base error with a stable machine-readable code and optional field path."""
+
+    default_code = "creative_render_engine_error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        field_path: str | None = None,
+        details: Mapping[str, Any] | None = None,
+    ) -> None:
+        self.code = code or self.default_code
+        self.field_path = field_path
+        self.details = dict(details or {})
+        prefix = f"{field_path}: " if field_path else ""
+        super().__init__(f"{self.code}: {prefix}{message}")
+
+
+class ContractError(CreativeRenderEngineError):
+    default_code = "contract_error"
+
+
+class ConfigurationError(CreativeRenderEngineError):
+    default_code = "configuration_error"
+
+
+class AssetError(CreativeRenderEngineError):
+    default_code = "asset_error"
+
+
+class CompileError(CreativeRenderEngineError):
+    default_code = "compile_error"
+
+
+class RenderError(CreativeRenderEngineError):
+    default_code = "render_error"

creative_render_engine/hashing.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+
+def file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def canonical_json_bytes(value: BaseModel | dict[str, Any]) -> bytes:
+    payload = value.model_dump(mode="json") if isinstance(value, BaseModel) else value
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def stable_sha256(value: BaseModel | dict[str, Any]) -> str:
+    return hashlib.sha256(canonical_json_bytes(value)).hexdigest()