cut-fx 0.1.2__py3-none-any.whl

cut_fx/__init__.py

@@ -0,0 +1,39 @@
+# Filepath: src/cut_fx/__init__.py
+# Condensed Description: Package entry point; re-exports public API and version.
+# Architecture Layer: Package
+# Environment: Local
+# Script Hierarchy: Top
+# Dependencies: Internal: cut_fx.api / External: None
+# Exposes: __version__, apply_transition, apply_sequence, list_transitions, list_categories, get_transition_info, TransitionConfig
+# Configuration: N/A
+
+from __future__ import annotations
+
+__version__ = "0.1.2"
+
+from cut_fx.api import (
+    apply_sequence,
+    apply_transition,
+    get_transition_info,
+    list_categories,
+    list_transitions,
+)
+
+__all__ = [
+    "__version__",
+    "apply_transition",
+    "apply_sequence",
+    "list_transitions",
+    "list_categories",
+    "get_transition_info",
+    "TransitionConfig",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Lazy-load optional names to avoid ImportError at package import."""
+    if name == "TransitionConfig":
+        from cut_fx.config import TransitionConfig  # noqa: PLC0415
+
+        return TransitionConfig
+    raise AttributeError(f"module 'cut_fx' has no attribute {name!r}")

cut_fx/api.py

@@ -0,0 +1,189 @@
+# Filepath: src/cut_fx/api.py
+# Condensed Description: Expose top-level public functions for applying and listing transitions.
+# Architecture Layer: API
+# Environment: Local
+# Script Hierarchy: High
+# Dependencies: Internal: cut_fx.resolver, cut_fx.config, cut_fx.catalog.loader, cut_fx.catalog.mapping / External: stdlib
+# Exposes: apply_transition, apply_sequence, list_transitions, list_categories, get_transition_info
+# Configuration: N/A
+
+from __future__ import annotations
+
+import logging
+import subprocess
+import tempfile
+from pathlib import Path
+
+from cut_fx.config import DEFAULT_OVERLAP, TransitionConfig
+
+_log = logging.getLogger(__name__)
+
+
+def apply_transition(
+    clip_a: str | Path,
+    clip_b: str | Path,
+    transition: str,
+    output: str | Path,
+    overlap_seconds: float = DEFAULT_OVERLAP,
+    config: TransitionConfig | None = None,
+) -> Path:
+    """Apply a named transition between two clips and write to output.
+
+    Args:
+        clip_a: Path to the first (outgoing) clip.
+        clip_b: Path to the second (incoming) clip.
+        transition: Transition slug or display name.
+        output: Destination path for the rendered file.
+        overlap_seconds: Duration of the transition overlap in seconds.
+        config: Optional pre-built TransitionConfig; built from other args when None.
+
+    Returns:
+        Resolved Path to the written output file.
+    """
+    from cut_fx.resolver import resolve_and_render  # noqa: PLC0415
+
+    if config is None:
+        config = TransitionConfig(transition=transition, overlap_seconds=overlap_seconds)
+
+    result = resolve_and_render(
+        transition=transition,
+        clip_a=Path(clip_a),
+        clip_b=Path(clip_b),
+        config=config,
+        output=Path(output),
+    )
+    _log.debug(f"apply_transition: wrote {result.output_path} via {result.engine_used}")
+    return result.output_path
+
+
+def apply_sequence(
+    clips: list[str | Path],
+    transitions: list[str | TransitionConfig],
+    output: str | Path,
+    default_overlap: float = DEFAULT_OVERLAP,
+) -> Path:
+    """Apply transitions across N clips (N-1 transitions) and concatenate to output.
+
+    Args:
+        clips: Ordered list of clip paths; must have at least 2 entries.
+        transitions: List of transition slugs/names or TransitionConfig objects.
+            Length must equal ``len(clips) - 1``.
+        output: Destination path for the concatenated result.
+        default_overlap: Overlap seconds used when a transition entry is a plain string.
+
+    Returns:
+        Resolved Path to the written output file.
+
+    Raises:
+        ValueError: When the lengths of clips and transitions are inconsistent.
+    """
+    if len(clips) < 2:
+        raise ValueError("apply_sequence requires at least 2 clips")
+    if len(transitions) != len(clips) - 1:
+        raise ValueError(f"Expected {len(clips) - 1} transitions for {len(clips)} clips, got {len(transitions)}")
+
+    output = Path(output)
+    segment_paths: list[Path] = []
+
+    with tempfile.TemporaryDirectory(prefix="cut_fx_seq_") as tmpdir:
+        tmp = Path(tmpdir)
+
+        for i, (clip_a, clip_b, trans) in enumerate(zip(clips, clips[1:], transitions)):
+            seg_out = tmp / f"seg_{i:04d}.mp4"
+
+            if isinstance(trans, TransitionConfig):
+                cfg = trans
+                trans_name = cfg.transition
+            else:
+                trans_name = trans
+                cfg = TransitionConfig(
+                    transition=trans_name,
+                    overlap_seconds=default_overlap,
+                )
+
+            apply_transition(
+                clip_a=clip_a,
+                clip_b=clip_b,
+                transition=trans_name,
+                output=seg_out,
+                config=cfg,
+            )
+            segment_paths.append(seg_out)
+            _log.debug(f"Rendered segment {i}: {seg_out}")
+
+        concat_list = tmp / "concat.txt"
+        concat_list.write_text(
+            "\n".join(f"file '{p}'" for p in segment_paths),
+            encoding="utf-8",
+        )
+
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-f",
+            "concat",
+            "-safe",
+            "0",
+            "-i",
+            str(concat_list),
+            "-c",
+            "copy",
+            str(output),
+        ]
+        _log.debug(f"Running ffmpeg concat: {' '.join(cmd)}")
+        subprocess.run(cmd, check=True, capture_output=True)
+
+    return output
+
+
+def list_transitions(category: str | None = None) -> list[str]:
+    """Return display names of all transitions; optionally filter by category.
+
+    Args:
+        category: Category slug to filter by, or None for all 559 transitions.
+
+    Returns:
+        List of transition display names.
+    """
+    from cut_fx.catalog.loader import list_transitions as _list  # noqa: PLC0415
+
+    return _list(category)
+
+
+def list_categories() -> list[str]:
+    """Return the 11 category names in catalog order.
+
+    Returns:
+        List of category slug strings.
+    """
+    from cut_fx.catalog.loader import list_categories as _list  # noqa: PLC0415
+
+    return _list()
+
+
+def get_transition_info(transition: str) -> dict:
+    """Return info dict for a transition, merging catalog and engine-mapping data.
+
+    Args:
+        transition: Transition slug or display name (case-insensitive).
+
+    Returns:
+        Dict with catalog fields plus engine, base, params, and duration_default
+        where available.
+
+    Raises:
+        TransitionNotFound: When the transition cannot be resolved.
+    """
+    from cut_fx.catalog.loader import get_transition_info as _get  # noqa: PLC0415
+    from cut_fx.catalog.mapping import get_render_plan  # noqa: PLC0415
+
+    info = _get(transition)
+
+    try:
+        plan = get_render_plan(info["slug"])
+        # Merge plan keys that are not already in info (avoid overwriting name/slug/categories)
+        info = {**info, **{k: v for k, v in plan.items() if k not in info}}
+    except Exception:
+        pass
+
+    return info

cut_fx/beats/__init__.py

@@ -0,0 +1,15 @@
+# Filepath: src/cut_fx/beats/__init__.py
+# Condensed Description: Re-export beat detection and beat-aligned placement utilities.
+# Architecture Layer: Beats
+# Environment: Local
+# Script Hierarchy: Mid
+# Dependencies: Internal: cut_fx.beats.detector, cut_fx.beats.placer / External: None
+# Exposes: detect_beats, transitions_on_beats
+# Configuration: N/A
+
+from __future__ import annotations
+
+from cut_fx.beats.detector import detect_beats
+from cut_fx.beats.placer import transitions_on_beats
+
+__all__ = ["detect_beats", "transitions_on_beats"]

cut_fx/beats/detector.py

@@ -0,0 +1,49 @@
+# Filepath: src/cut_fx/beats/detector.py
+# Condensed Description: Detect beat timestamps in an audio file using librosa.
+# Architecture Layer: Beats
+# Environment: Local
+# Script Hierarchy: Mid
+# Dependencies: Internal: cut_fx.exceptions / External: librosa (optional)
+# Exposes: detect_beats
+# Configuration: N/A
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from cut_fx.exceptions import EngineUnavailable
+
+_log = logging.getLogger(__name__)
+
+
+def detect_beats(audio_path: str | Path) -> list[float]:
+    """Detect beat timestamps in seconds from an audio file.
+
+    Args:
+        audio_path: Path to any audio file supported by librosa/soundfile.
+
+    Returns:
+        Sorted list of beat timestamps in seconds.
+
+    Raises:
+        EngineUnavailable: When librosa is not installed.
+    """
+    try:
+        import librosa  # noqa: PLC0415
+    except ImportError as exc:
+        raise EngineUnavailable(
+            "beats",
+            "librosa is not installed",
+            "pip install cut-fx[beats]",
+        ) from exc
+
+    audio_path = Path(audio_path)
+    _log.debug(f"Loading audio for beat detection: {audio_path}")
+
+    y, sr = librosa.load(str(audio_path), sr=None)
+    _tempo, beat_frames = librosa.beat.beat_track(y=y, sr=sr)
+    beat_times: list[float] = sorted(float(t) for t in librosa.frames_to_time(beat_frames, sr=sr))
+
+    _log.debug(f"Detected {len(beat_times)} beats, tempo={float(_tempo):.1f} BPM")
+    return beat_times

cut_fx/beats/placer.py

@@ -0,0 +1,76 @@
+# Filepath: src/cut_fx/beats/placer.py
+# Condensed Description: Place transitions at beat timestamps and concatenate clips to output.
+# Architecture Layer: Beats
+# Environment: Local
+# Script Hierarchy: Mid
+# Dependencies: Internal: cut_fx.beats.detector, cut_fx.api / External: None
+# Exposes: transitions_on_beats
+# Configuration: N/A
+
+from __future__ import annotations
+
+import logging
+import statistics
+from pathlib import Path
+
+_log = logging.getLogger(__name__)
+
+
+def transitions_on_beats(
+    clips: list[str | Path],
+    audio: str | Path,
+    transitions: list[str],
+    output: str | Path,
+    beats: list[float] | None = None,
+) -> Path:
+    """Place transitions at beat timestamps and concatenate clips to output.
+
+    Detects beats automatically when ``beats`` is omitted. Cycles through the
+    ``transitions`` list if it is shorter than the number of required cuts
+    (``len(clips) - 1``).
+
+    Args:
+        clips: Ordered list of video clip paths.
+        audio: Path to the audio file used for beat detection.
+        transitions: One or more transition names (slugs or display names).
+        output: Destination path for the concatenated result.
+        beats: Pre-computed beat timestamps in seconds. Detected from ``audio``
+            when None.
+
+    Returns:
+        Resolved Path to the written output file.
+
+    Raises:
+        ValueError: When fewer than 2 clips are provided.
+        EngineUnavailable: When librosa is missing and beats must be detected.
+    """
+    if len(clips) < 2:
+        raise ValueError("transitions_on_beats requires at least 2 clips")
+
+    if beats is None:
+        from cut_fx.beats.detector import detect_beats  # noqa: PLC0415
+
+        beats = detect_beats(audio)
+        _log.debug(f"Auto-detected {len(beats)} beats from {audio}")
+
+    n_transitions = len(clips) - 1
+
+    # Use median beat interval as the overlap duration for all transitions
+    overlap_seconds: float = 0.5
+    if len(beats) >= 2:
+        intervals = [beats[i + 1] - beats[i] for i in range(len(beats) - 1)]
+        overlap_seconds = round(min(statistics.median(intervals) * 0.5, 1.0), 3)
+        _log.debug(f"Median beat interval={statistics.median(intervals):.3f}s, overlap={overlap_seconds}s")
+
+    # Cycle transitions list to cover all required cuts
+    resolved_transitions = [transitions[i % len(transitions)] for i in range(n_transitions)]
+
+    # Lazy import to avoid circular dependency at module load time
+    from cut_fx.api import apply_sequence  # noqa: PLC0415
+
+    return apply_sequence(
+        clips=list(clips),
+        transitions=resolved_transitions,
+        output=output,
+        default_overlap=overlap_seconds,
+    )

cut_fx/catalog/__init__.py

@@ -0,0 +1,19 @@
+# Filepath: src/cut_fx/catalog/__init__.py
+# Condensed Description: Re-export catalog query functions from loader.
+# Architecture Layer: Catalog
+# Environment: Local
+# Script Hierarchy: Mid
+# Dependencies: Internal: cut_fx.catalog.loader / External: None
+# Exposes: load_catalog, list_transitions, list_categories, get_transition_info
+# Configuration: N/A
+
+from __future__ import annotations
+
+from cut_fx.catalog.loader import (
+    get_transition_info,
+    list_categories,
+    list_transitions,
+    load_catalog,
+)
+
+__all__ = ["load_catalog", "list_transitions", "list_categories", "get_transition_info"]

cut_fx/catalog/loader.py

@@ -0,0 +1,77 @@
+# Filepath: src/cut_fx/catalog/loader.py
+# Condensed Description: Load, cache, and query the transitions catalog JSON.
+# Architecture Layer: Catalog
+# Environment: Local
+# Script Hierarchy: Leaf
+# Dependencies: Internal: cut_fx.exceptions / External: stdlib (json, difflib, pathlib)
+# Exposes: load_catalog, list_transitions, list_categories, get_transition_info
+# Configuration: N/A
+
+from __future__ import annotations
+
+import difflib
+import json
+import logging
+from pathlib import Path
+
+from cut_fx.exceptions import TransitionNotFound
+
+_log = logging.getLogger(__name__)
+
+_DATA_PATH = Path(__file__).parent.parent / "data" / "transitions_catalog.json"
+
+_CATALOG: dict | None = None
+
+
+def load_catalog() -> dict:
+    """Load and cache transitions_catalog.json."""
+    global _CATALOG
+    if _CATALOG is None:
+        with _DATA_PATH.open("r", encoding="utf-8") as f:
+            _CATALOG = json.load(f)
+        _log.debug(f"Loaded catalog with {len(_CATALOG['transitions'])} entries from {_DATA_PATH}")
+    return _CATALOG
+
+
+def list_transitions(category: str | None = None) -> list[str]:
+    """Return display names of all transitions; optionally filter by category slug."""
+    catalog = load_catalog()
+    transitions = catalog["transitions"]
+    if category is not None:
+        transitions = [t for t in transitions if category in t.get("categories", [])]
+    return [t["name"] for t in transitions]
+
+
+def list_categories() -> list[str]:
+    """Return the 11 category names from catalog['categories']."""
+    return load_catalog()["categories"]
+
+
+def get_transition_info(transition: str) -> dict:
+    """Look up transition by slug or display name (case-insensitive). Raises TransitionNotFound."""
+    entry = _resolve_name(transition)
+    if entry is not None:
+        return entry
+
+    all_slugs = [t["slug"] for t in load_catalog()["transitions"]]
+    matches = difflib.get_close_matches(transition.lower(), all_slugs, n=1, cutoff=0.5)
+    suggestion = matches[0] if matches else None
+    raise TransitionNotFound(transition, suggestion=suggestion)
+
+
+def _resolve_name(name: str) -> dict | None:
+    """Try exact slug, case-folded slug, exact name, case-folded name, slug-from-name."""
+    transitions = load_catalog()["transitions"]
+    folded = name.lower()
+    slug_form = folded.replace(" ", "_").replace("-", "_")
+
+    for entry in transitions:
+        if (
+            entry["slug"] == name
+            or entry["slug"] == folded
+            or entry["name"] == name
+            or entry["name"].lower() == folded
+            or entry["slug"] == slug_form
+        ):
+            return entry
+    return None

cut_fx/catalog/mapping.py

@@ -0,0 +1,41 @@
+# Filepath: src/cut_fx/catalog/mapping.py
+# Condensed Description: Load engine_mapping.json and serve per-slug render plans.
+# Architecture Layer: Catalog
+# Environment: Local
+# Script Hierarchy: Leaf
+# Dependencies: Internal: cut_fx.exceptions / External: stdlib (json, pathlib)
+# Exposes: load_engine_mapping, get_render_plan
+# Configuration: N/A
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from cut_fx.exceptions import TransitionNotFound
+
+_log = logging.getLogger(__name__)
+
+_DATA_PATH = Path(__file__).parent.parent / "data" / "engine_mapping.json"
+
+_MAPPING: dict | None = None
+
+
+def load_engine_mapping() -> dict:
+    """Load and cache engine_mapping.json."""
+    global _MAPPING
+    if _MAPPING is None:
+        with _DATA_PATH.open("r", encoding="utf-8") as f:
+            _MAPPING = json.load(f)
+        _log.debug(f"Loaded engine mapping with {len(_MAPPING)} entries from {_DATA_PATH}")
+    return _MAPPING
+
+
+def get_render_plan(slug: str) -> dict:
+    """Return render plan for slug. Raises TransitionNotFound if missing."""
+    mapping = load_engine_mapping()
+    plan = mapping.get(slug)
+    if plan is None:
+        raise TransitionNotFound(slug)
+    return plan