@oh-story/dsh 0.1.4 → 0.1.6

package/lib/video-recap/skills/video-assemble/scripts/jianying_model.py

@@ -0,0 +1,111 @@
+"""Thin internal model used at the JianYing adapter boundary."""
+
+import os
+from dataclasses import dataclass, field
+from typing import Callable
+
+from jianying_schema import us
+from jianying_tracks import TrackAllocator
+
+
+ProbeFn = Callable[[str], tuple[int, int, int]]
+NewIdFn = Callable[[], str]
+
+
+@dataclass
+class DraftBuildContext:
+    """Normalized draft build state and overlap-safe track collection."""
+
+    width: int
+    height: int
+    fps: float
+    total_us: int
+    new_id: NewIdFn
+    probe: ProbeFn
+    resource_packages: dict = field(default_factory=dict)
+    style_presets: dict = field(default_factory=dict)
+    materials: dict[str, list] = field(
+        default_factory=lambda: {
+            key: []
+            for key in (
+                "audios",
+                "chromas",
+                "common_mask",
+                "drafts",
+                "effects",
+                "masks",
+                "speeds",
+                "stickers",
+                "text_templates",
+                "texts",
+                "transitions",
+                "video_effects",
+                "videos",
+            )
+        }
+    )
+    tracks: list[dict] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+    track_allocator: TrackAllocator = field(default_factory=TrackAllocator)
+
+    @classmethod
+    def from_timeline(cls, timeline, new_id, probe):
+        canvas = timeline.get("canvas", {})
+        return cls(
+            width=int(canvas.get("width", 1920)),
+            height=int(canvas.get("height", 1080)),
+            fps=float(canvas.get("fps", 30)),
+            total_us=us(timeline.get("duration", 0)),
+            new_id=new_id,
+            probe=probe,
+            resource_packages=dict(timeline.get("resource_packages") or {}),
+            style_presets=dict(timeline.get("style_presets") or {}),
+        )
+
+    def media_duration(self, path, fallback_us):
+        if path and os.path.exists(path):
+            duration_us, width, height = self.probe(path)
+            return duration_us or fallback_us, width, height
+        return fallback_us, 0, 0
+
+    def add_segment(self, kind, base_name, start_us, duration_us, segment):
+        allocated = self.track_allocator.allocate(kind, base_name, start_us, duration_us)
+        track = next(
+            (
+                item for item in self.tracks
+                if item["_semantic_kind"] == allocated.kind
+                and item["name"] == allocated.name
+            ),
+            None,
+        )
+        if track is None:
+            track = {
+                "attribute": 0,
+                "flag": 0,
+                "id": self.new_id(),
+                "is_default_name": True,
+                "name": allocated.name,
+                "segments": [],
+                "type": allocated.track_type,
+                "_semantic_kind": allocated.kind,
+                "_layout_order": allocated.layout_order,
+            }
+            self.tracks.append(track)
+        track["segments"].append(segment)
+        return track
+
+    def finalize_tracks(self):
+        # Python's stable sort preserves the timeline's authored order inside
+        # one semantic band (for example narration before BGM).
+        self.tracks.sort(key=lambda item: item.get("_layout_order", 120_000))
+        type_counts = {}
+        for track in self.tracks:
+            count = type_counts.get(track["type"], 0)
+            track["flag"] = 0 if count == 0 else 2
+            type_counts[track["type"]] = count + 1
+            track.pop("_semantic_kind", None)
+            track.pop("_layout_order", None)
+        return self.tracks
+
+    def note(self, message):
+        self.notes.append(message)

package/lib/video-recap/skills/video-assemble/scripts/jianying_optional.py

@@ -0,0 +1,24 @@
+"""Failure-isolated optional JianYing export invoked after canonical rendering."""
+
+from pathlib import Path
+
+from lib import CONFIG, log
+
+def _maybe_export_jianying(work_dir, out_dir, stem):
+    """Lazy-import the optional 剪映 exporter and write a draft from timeline.json."""
+    timeline_path = Path(work_dir) / "timeline.json"
+    if not timeline_path.exists():
+        log("  ⚠️ 跳过剪映导出：未找到 timeline.json")
+        return
+    try:
+        from export_jianying import export_timeline_to_jianying
+        from timeline import load_timeline
+        parent = out_dir or CONFIG.get("jianying_draft_dir") or str(work_dir)
+        draft_dir, notes = export_timeline_to_jianying(
+            load_timeline(timeline_path), parent, draft_name=f"recap_{stem}",
+            bundle_media=CONFIG.get("jianying_bundle_media", False))
+        for n in notes:
+            log(f"  注意: {n}")
+        log(f"剪映草稿已导出: {draft_dir}")
+    except Exception as exc:  # optional feature must never fail the render
+        log(f"  ⚠️ 剪映导出失败（不影响成片）: {exc}")

package/lib/video-recap/skills/video-assemble/scripts/jianying_schema.py

@@ -0,0 +1,109 @@
+"""Schema constants, skeleton factories, and material registry for JianYing export.
+
+This module is intentionally data-oriented: it owns draft version metadata, the
+full `materials` parallel-array shape, and the implemented material dispatch.
+"""
+
+from jianying_templates import template
+
+# The full 剪映 materials object: ~45 parallel arrays. Only arrays backed by a
+# production builder are populated; retaining the full shape preserves compatibility.
+MATERIAL_KEYS = (
+    "ai_translates audio_balances audio_effects audio_fades audio_track_indexes audios "
+    "beats canvases chromas color_curves digital_humans drafts effects flowers green_screens "
+    "handwrites hsl images log_color_wheels loudnesses manual_deformations masks common_mask "
+    "material_animations material_colors multi_language_refs placeholders plugin_effects "
+    "primary_color_wheels realtime_denoises shapes smart_crops smart_relights "
+    "sound_channel_mappings speeds stickers tail_leaders text_templates texts time_marks "
+    "transitions video_effects video_trackings videos vocal_beautifys vocal_separations"
+).split()
+
+
+def us(seconds):
+    """Seconds (float) -> integer microseconds. The single seconds->µs boundary."""
+    return int(round(float(seconds) * 1_000_000))
+
+
+def full_materials(filled):
+    """Return a complete JianYing `materials` object with all known arrays."""
+    out = {k: [] for k in MATERIAL_KEYS}
+    out.update(filled)
+    return out
+
+
+def scrub_platform_identity(project):
+    """Remove hardware fingerprints carried by the pinned upstream templates."""
+    for platform_key in ("last_modified_platform", "platform"):
+        platform = project.get(platform_key)
+        if not isinstance(platform, dict):
+            continue
+        for identity_key in ("device_id", "hard_disk_id", "mac_address"):
+            platform[identity_key] = ""
+    return project
+
+
+def draft_content_skeleton(draft_id, width, height, fps, total_us, materials, tracks):
+    """Build the root `draft_content.json` / `draft_info.json` skeleton."""
+    content = template("project")
+    scrub_platform_identity(content)
+    content["canvas_config"] = {"width": width, "height": height, "ratio": "original"}
+    content["duration"] = int(total_us)
+    content["fps"] = float(fps)
+    content["id"] = draft_id
+    content["materials"] = full_materials(materials)
+    content["tracks"] = tracks
+    return content
+
+
+def meta_info(draft_id, total_us):
+    """Build the companion `draft_meta_info.json` skeleton."""
+    meta = template("meta")
+    meta["draft_id"] = draft_id
+    meta["draft_timeline_materials_size_"] = 0
+    meta["tm_duration"] = int(total_us)
+    return meta
+
+
+def material_category_registry():
+    """Material category support table inspired by duo-video's MaterialTypeEnum.
+
+    Keyframes, bundling, and path rewrite are exporter behavior, not material
+    categories, so they intentionally do not appear here.
+    """
+    return {
+        "video": {"status": "supported", "materials_key": "videos", "track_type": "video"},
+        "audio": {"status": "supported", "materials_key": "audios", "track_type": "audio"},
+        "text": {"status": "supported", "materials_key": "texts", "track_type": "text"},
+        "subtitle": {"status": "supported", "materials_key": "texts", "track_type": "text"},
+        "speed": {"status": "supported_auxiliary", "materials_key": "speeds", "track_type": None},
+        # JianYing represents photos in materials.videos with material.type=photo.
+        "image": {"status": "supported", "materials_key": "videos", "track_type": "video"},
+        "sticker": {"status": "supported_offline_payload", "materials_key": "stickers", "track_type": "sticker"},
+        "sound": {"status": "supported_offline_payload", "materials_key": "audios", "track_type": "audio"},
+        "text_template": {"status": "supported_offline_payload", "materials_key": "text_templates", "track_type": "text"},
+        "lut": {"status": "supported_offline_payload", "materials_key": "effects", "track_type": "video"},
+        "transition": {"status": "supported_offline_payload", "materials_key": "transitions", "track_type": "video"},
+        "video_effect": {"status": "supported_offline_payload", "materials_key": "video_effects", "track_type": "effect"},
+        "face_effect": {"status": "supported_offline_payload", "materials_key": "video_effects", "track_type": "effect"},
+        "mask": {"status": "supported_offline_payload", "materials_key": "masks", "track_type": "video"},
+        "chroma": {"status": "supported_offline_payload", "materials_key": "chromas", "track_type": "video"},
+        "green_screen": {"status": "supported", "materials_key": "drafts", "track_type": "video"},
+        "compound": {"status": "supported", "materials_key": "drafts", "track_type": "video"},
+        # duo-video style is authoring input rather than a direct material array.
+        "style": {"status": "supported", "materials_key": None, "track_type": None},
+    }
+
+
+def validate_material_category(category):
+    """Return deterministic support metadata for a public or future material kind."""
+    normalized = (category or "").strip().lower()
+    registry = material_category_registry()
+    info = dict(registry.get(normalized, {"status": "unsupported", "materials_key": None, "track_type": None}))
+    info["category"] = normalized
+    info["supported"] = info["status"] in {
+        "supported", "supported_auxiliary", "supported_offline_payload",
+    }
+    if not info["supported"]:
+        status = "保留但暂未实现" if info["status"] == "reserved" else "未知"
+        info["note"] = f"暂不支持的 JianYing material category: {normalized}（{status}），已跳过以避免生成无效草稿"
+    return info

package/lib/video-recap/skills/video-assemble/scripts/jianying_templates.py

@@ -0,0 +1,37 @@
+"""Load the pinned duo-video JianYing protocol templates."""
+
+import copy
+import json
+from functools import lru_cache
+from pathlib import Path
+
+
+_TEMPLATE_DIR = Path(__file__).resolve().parent.parent / "references" / "jianying"
+_TEMPLATE_FILES = {
+    "project": "empty_jy_project_info.json",
+    "video": "empty_jy_material_video.json",
+    "audio": "empty_yj_material_audio.json",
+    "text": "empty_yj_material_text.json",
+    "text_style": "empty_jy_text_styles.json",
+    "segment": "empty_jy_segment.json",
+    "draft": "empty_jy_draft.json",
+    "combination_segment": "empty_jy_combination_segment.json",
+    "combination_video": "empty_jy_combination_video_material.json",
+    "meta": "empty_draft_meta_info.json",
+    "meta_material": "empty_jy_meta_material_value.json",
+}
+
+
+@lru_cache(maxsize=None)
+def _read_template(name):
+    try:
+        filename = _TEMPLATE_FILES[name]
+    except KeyError as exc:
+        raise ValueError(f"unknown JianYing template: {name}") from exc
+    with open(_TEMPLATE_DIR / filename, encoding="utf-8") as source:
+        return json.load(source)
+
+
+def template(name):
+    """Return a mutable deep copy of a pinned protocol template."""
+    return copy.deepcopy(_read_template(name))

package/lib/video-recap/skills/video-assemble/scripts/jianying_timeline_contract.py

@@ -0,0 +1,191 @@
+"""Timeline validation and migration at the JianYing adapter boundary."""
+
+import copy
+import math
+
+
+CURRENT_SCHEMA_VERSION = 2
+RESOURCE_TRACK_KINDS = {
+    "face_effect", "sound", "sticker", "text_template", "video_effect",
+}
+
+
+def _error(path, expectation):
+    raise ValueError(f"invalid timeline {path}: {expectation}")
+
+
+def _is_number(value):
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return False
+    try:
+        return math.isfinite(value)
+    except OverflowError:
+        return False
+
+
+def _field_path(path, key):
+    return f"{path}.{key}" if path else key
+
+
+def _require_number(container, key, path, *, minimum=None):
+    field_path = _field_path(path, key)
+    if key not in container or not _is_number(container[key]):
+        _error(field_path, "must be a finite number")
+    value = container[key]
+    if minimum is not None and value < minimum:
+        _error(field_path, f"must be >= {minimum}")
+    return value
+
+
+def _require_string(container, key, path):
+    value = container.get(key)
+    if not isinstance(value, str) or not value:
+        _error(_field_path(path, key), "must be a non-empty string")
+    return value
+
+
+def _validate_span(item, path, start_key="timeline_start", end_key="timeline_end"):
+    start = _require_number(item, start_key, path, minimum=0)
+    end = _require_number(item, end_key, path, minimum=0)
+    if end <= start:
+        _error(f"{path}.{end_key}", f"must be greater than {start_key}")
+
+
+def _validate_video_clip(clip, path):
+    if not isinstance(clip, dict):
+        _error(path, "must be an object")
+    _require_string(clip, "source_path", path)
+    _validate_span(clip, path)
+    _validate_span(clip, path, "source_start", "source_end")
+    if "audio" in clip and not isinstance(clip["audio"], dict):
+        _error(f"{path}.audio", "must be an object")
+    if "speed" in clip:
+        speed = _require_number(clip, "speed", path)
+        if speed <= 0:
+            _error(f"{path}.speed", "must be greater than 0")
+        source_duration = float(clip["source_end"]) - float(clip["source_start"])
+        target_duration = float(clip["timeline_end"]) - float(clip["timeline_start"])
+        expected_source_duration = target_duration * float(speed)
+        if not math.isclose(source_duration, expected_source_duration, rel_tol=1e-6, abs_tol=1e-4):
+            _error(
+                path,
+                "source duration must equal target duration multiplied by speed "
+                f"({source_duration} != {target_duration} * {speed})",
+            )
+    if "reverse" in clip and not isinstance(clip["reverse"], bool):
+        _error(f"{path}.reverse", "must be a boolean")
+    if clip.get("reverse"):
+        _require_string(clip, "reverse_path", path)
+    for field in ("scale", "position", "flip"):
+        if field in clip and not isinstance(clip[field], dict):
+            _error(f"{path}.{field}", "must be an object")
+    for field in ("transition", "mask", "lut", "chroma"):
+        if field in clip and not isinstance(clip[field], (dict, str)):
+            _error(f"{path}.{field}", "must be an object or resource-package name")
+    if "green_background" in clip and not isinstance(clip["green_background"], dict):
+        _error(f"{path}.green_background", "must be a local media object")
+    if "compound" in clip and not isinstance(clip["compound"], bool):
+        _error(f"{path}.compound", "must be a boolean")
+
+
+def _validate_segment(segment, path, kind):
+    if not isinstance(segment, dict):
+        _error(path, "must be an object")
+    _validate_span(segment, path)
+    if "speed" in segment:
+        speed = _require_number(segment, "speed", path)
+        if speed <= 0:
+            _error(f"{path}.speed", "must be greater than 0")
+    if kind in {"audio", "image"}:
+        _require_string(segment, "source_path", path)
+    elif kind == "text" and not isinstance(segment.get("text"), str):
+        _error(f"{path}.text", "must be a string")
+    elif kind in RESOURCE_TRACK_KINDS:
+        sources = [key for key in ("material", "resource_config", "resource_package") if key in segment]
+        if len(sources) != 1:
+            _error(path, "must define exactly one of material, resource_config, or resource_package")
+        source = segment[sources[0]]
+        if sources[0] == "resource_package":
+            if not isinstance(source, str) or not source:
+                _error(f"{path}.resource_package", "must be a non-empty string")
+        elif sources[0] == "material" and not isinstance(source, dict):
+            _error(f"{path}.material", "must be an object")
+        elif sources[0] == "resource_config" and not isinstance(source, (dict, str)):
+            _error(f"{path}.resource_config", "must be an object or JSON file path")
+
+
+def _validate_track(track, path):
+    if not isinstance(track, dict):
+        _error(path, "must be an object")
+    kind = _require_string(track, "kind", path)
+    if "name" in track and (not isinstance(track["name"], str) or not track["name"]):
+        _error(f"{path}.name", "must be a non-empty string")
+
+    if kind == "video":
+        clips = track.get("clips")
+        if not isinstance(clips, list):
+            _error(f"{path}.clips", "must be an array")
+        for index, clip in enumerate(clips):
+            _validate_video_clip(clip, f"{path}.clips[{index}]")
+        return
+
+    if kind in {"audio", "image", "text"} | RESOURCE_TRACK_KINDS:
+        segments = track.get("segments")
+        if not isinstance(segments, list):
+            _error(f"{path}.segments", "must be an array")
+        if kind == "audio":
+            if "role" in track and not isinstance(track["role"], str):
+                _error(f"{path}.role", "must be a string")
+            if "loop" in track and not isinstance(track["loop"], bool):
+                _error(f"{path}.loop", "must be a boolean")
+        for index, segment in enumerate(segments):
+            _validate_segment(segment, f"{path}.segments[{index}]", kind)
+        return
+
+    _error(f"{path}.kind", f"unsupported track kind {kind!r}")
+
+
+def _validate_v2(timeline):
+    canvas = timeline.get("canvas")
+    if not isinstance(canvas, dict):
+        _error("canvas", "must be an object")
+    for dimension in ("width", "height"):
+        value = canvas.get(dimension)
+        if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+            _error(f"canvas.{dimension}", "must be a positive integer")
+    fps = _require_number(canvas, "fps", "canvas")
+    if fps <= 0:
+        _error("canvas.fps", "must be greater than 0")
+
+    _require_number(timeline, "duration", "", minimum=0)
+    for registry_name in ("resource_packages", "style_presets"):
+        if registry_name in timeline and not isinstance(timeline[registry_name], dict):
+            _error(registry_name, "must be an object")
+    tracks = timeline.get("tracks")
+    if not isinstance(tracks, list):
+        _error("tracks", "must be an array")
+    for index, track in enumerate(tracks):
+        _validate_track(track, f"tracks[{index}]")
+
+
+def normalize_timeline(timeline):
+    """Return a validated schema-v2 copy, migrating schema v1 when necessary."""
+    if not isinstance(timeline, dict):
+        _error("root", "must be an object")
+    schema_version = timeline.get("schema_version")
+    if not isinstance(schema_version, int) or isinstance(schema_version, bool):
+        _error("schema_version", "must be integer 1 or 2")
+    if schema_version not in {1, CURRENT_SCHEMA_VERSION}:
+        raise ValueError(
+            f"unsupported timeline schema_version {schema_version}; "
+            f"supported versions are 1 and {CURRENT_SCHEMA_VERSION}"
+        )
+
+    normalized = copy.deepcopy(timeline)
+    if schema_version == 1:
+        # Schema v2 is an additive extension of v1 (local image tracks). The
+        # migration therefore preserves all authored v1 fields and only advances
+        # the version before applying the current contract.
+        normalized["schema_version"] = CURRENT_SCHEMA_VERSION
+    _validate_v2(normalized)
+    return normalized

package/lib/video-recap/skills/video-assemble/scripts/jianying_tracks.py

@@ -0,0 +1,75 @@
+"""Semantic track ordering and overlap-safe allocation for JianYing export.
+
+The order mirrors duo-video's authoring layout. It is used only to order track
+objects; JianYing segment ``render_index`` remains the schema default and must
+not be confused with this semantic layout value.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TrackBand:
+    kind: str
+    track_type: str
+    layout_order: int
+    description: str
+
+
+SEGMENT_RENDER_INDEX = 2
+
+
+TRACK_LAYOUT_BANDS = {
+    "sound": TrackBand("sound", "audio", 10_000, "sound effects"),
+    "audio": TrackBand("audio", "audio", 20_000, "narration, music, and general audio"),
+    "green_screen": TrackBand("green_screen", "video", 30_000, "green-screen background"),
+    "video": TrackBand("video", "video", 40_000, "base video"),
+    "image": TrackBand("image", "video", 50_000, "image and photo overlays"),
+    "mask": TrackBand("mask", "video", 60_000, "masks"),
+    "effect": TrackBand("effect", "effect", 70_000, "video effects"),
+    "video_effect": TrackBand("video_effect", "effect", 70_000, "video effects"),
+    "face_effect": TrackBand("face_effect", "effect", 70_010, "face effects"),
+    "sticker": TrackBand("sticker", "sticker", 80_000, "stickers"),
+    "subtitle": TrackBand("subtitle", "text", 90_000, "subtitles"),
+    "text": TrackBand("text", "text", 100_000, "plain text"),
+    "text_template": TrackBand("text_template", "text", 110_000, "text templates"),
+}
+
+
+@dataclass(frozen=True)
+class AllocatedTrack:
+    kind: str
+    name: str
+    track_type: str
+    layout_order: int
+
+
+class TrackAllocator:
+    """Allocate deterministic suffix tracks when same-name segments overlap.
+
+    Intervals are half-open, so adjacent segments reuse a track while true
+    overlap creates ``name-1``, ``name-2``, and so on.
+    """
+
+    def __init__(self):
+        self._occupied = {}
+
+    @staticmethod
+    def _overlaps(start_us, duration_us, existing):
+        end_us = int(start_us) + int(duration_us)
+        return any(int(start_us) < old_end and end_us > old_start for old_start, old_end in existing)
+
+    def allocate(self, kind, base_name, start_us, duration_us):
+        band = TRACK_LAYOUT_BANDS.get(kind)
+        if band is None:
+            band = TrackBand(kind, "video", 120_000, "unregistered fallback")
+        base_name = base_name or kind
+        suffix = 0
+        while True:
+            name = base_name if suffix == 0 else f"{base_name}-{suffix}"
+            key = (kind, name)
+            occupied = self._occupied.setdefault(key, [])
+            if not self._overlaps(start_us, duration_us, occupied):
+                occupied.append((int(start_us), int(start_us) + int(duration_us)))
+                return AllocatedTrack(kind, name, band.track_type, band.layout_order + suffix)
+            suffix += 1