xiaoxia-saas/tests/unit/test_xfade_per_transition_1766.py

"""#1766 xfade_builder 逐转场时长与位置微调测试.

覆盖：
- build_xfade_filter_chain：transition_durations 参数（逐转场独立时长）
- build_xfade_filter_chain：jitters 参数（位置微调偏移）
- 向后兼容：不传新参数时行为不变
- TransitionEngine.build_xfade_chain：透传新参数
"""

from __future__ import annotations

import sys
from pathlib import Path

import pytest

REPO_ROOT = Path(__file__).resolve().parents[2]
for sub in ("packages", ""):
    p = str(REPO_ROOT / sub) if sub else str(REPO_ROOT)
    if p not in sys.path:
        sys.path.insert(0, p)

from packages.domain.xfade_builder import (  # noqa: E402
    DEFAULT_TRANSITION_DURATION,
    build_xfade_filter_chain,
)


class TestBackwardCompatibility:
    """向后兼容测试：不传新参数时行为不变。"""

    def test_single_transition_duration(self):
        """全局 transition_duration 仍有效。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.5,
        )
        assert "xfade" in result
        assert "duration=0.500" in result
        assert dur > 0

    def test_default_transition_duration(self):
        """不传 transition_duration 时使用默认值 0.5。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
        )
        assert "duration=0.500" in result


class TestPerTransitionDurations:
    """逐转场独立时长测试。"""

    def test_different_durations_per_transition(self):
        """每个转场使用不同的时长。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0, 5.0],
            clip_video_labels=["v0", "v1", "v2"],
            transitions=["cut", "fade", "dissolve"],
            transition_durations=[0.3, 0.8],  # 第 1 个转场 0.3s，第 2 个 0.8s
        )
        assert "duration=0.300" in result
        assert "duration=0.800" in result

    def test_partial_durations_fallback_to_global(self):
        """transition_durations 长度不足时 fallback 到 transition_duration。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0, 5.0],
            clip_video_labels=["v0", "v1", "v2"],
            transitions=["cut", "fade", "dissolve"],
            transition_duration=0.5,
            transition_durations=[0.3],  # 只有第一个，第二个 fallback 到 0.5
        )
        assert "duration=0.300" in result
        assert "duration=0.500" in result

    def test_empty_durations_uses_global(self):
        """transition_durations=[] 时使用全局 transition_duration。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.6,
            transition_durations=[],
        )
        assert "duration=0.600" in result

    def test_none_durations_uses_global(self):
        """transition_durations=None 时使用全局 transition_duration。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.6,
            transition_durations=None,
        )
        assert "duration=0.600" in result

    def test_duration_clamped_by_clip_length(self):
        """转场时长不能超过相邻片段时长。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[2.0, 2.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_durations=[1.5],  # 1.5s > 2.0s * 0.4，会被钳制
        )
        # 钳制到可用范围内
        assert "duration=" in result

    def test_total_duration_reflects_per_transition(self):
        """总时长反映逐转场的重叠量。"""
        # 使用 0.3s 转场
        _, dur_short = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_durations=[0.3],
        )
        # 使用 0.8s 转场
        _, dur_long = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_durations=[0.8],
        )
        # 更长转场 → 更多重叠 → 总时长更短
        assert dur_long < dur_short


class TestJitters:
    """位置微调 jitter 测试。"""

    def test_positive_jitter_delays_transition(self):
        """正 jitter 推迟转场（offset 增大）。"""
        result_no_jitter, _ = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.5,
        )
        result_with_jitter, _ = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.5,
            jitters=[0.3],  # 正 jitter：推迟转场
        )
        # 提取 offset 值
        import re

        offset_no = float(re.search(r"offset=([\d.]+)", result_no_jitter).group(1))
        offset_yes = float(re.search(r"offset=([\d.]+)", result_with_jitter).group(1))
        assert offset_yes > offset_no

    def test_negative_jitter_advances_transition(self):
        """负 jitter 提前转场（offset 减小）。"""
        result_no_jitter, _ = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.5,
        )
        result_with_jitter, _ = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.5,
            jitters=[-0.3],  # 负 jitter：提前转场
        )
        import re

        offset_no = float(re.search(r"offset=([\d.]+)", result_no_jitter).group(1))
        offset_yes = float(re.search(r"offset=([\d.]+)", result_with_jitter).group(1))
        assert offset_yes < offset_no

    def test_jitter_clamped_to_valid_range(self):
        """jitter 不会使 offset 超出有效范围（>=0）。"""
        result, _ = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.5,
            jitters=[-100.0],  # 极大负 jitter
        )
        import re

        offset = float(re.search(r"offset=([\d.]+)", result).group(1))
        assert offset >= 0.0

    def test_per_transition_jitters(self):
        """每个转场可以有独立的 jitter。"""
        result, _ = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0, 5.0],
            clip_video_labels=["v0", "v1", "v2"],
            transitions=["cut", "fade", "dissolve"],
            transition_duration=0.5,
            jitters=[0.2, -0.1],
        )
        import re

        offsets = [float(m.group(1)) for m in re.finditer(r"offset=([\d.]+)", result)]
        assert len(offsets) == 2

    def test_empty_jitters_no_effect(self):
        """jitters=[] 等同于无 jitter。"""
        result_no, _ = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.5,
        )
        result_empty, _ = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "fade"],
            transition_duration=0.5,
            jitters=[],
        )
        assert result_no == result_empty


class TestEdgeCases:
    """边界情况测试。"""

    def test_single_clip_with_durations(self):
        """单片段传入 transition_durations 不报错。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[5.0],
            clip_video_labels=["v0"],
            transitions=["cut"],
            transition_durations=[0.5],
        )
        assert "copy" in result
        assert dur == 5.0

    def test_empty_clips(self):
        """空片段列表返回空字符串。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[],
            clip_video_labels=[],
            transitions=[],
            transition_durations=[],
            jitters=[],
        )
        assert result == ""
        assert dur == 0.0

    def test_all_cut_transitions(self):
        """全硬切场景（不进入 xfade，由调用方处理 concat）。"""
        result, dur = build_xfade_filter_chain(
            clip_durations=[5.0, 5.0],
            clip_video_labels=["v0", "v1"],
            transitions=["cut", "cut"],
            transition_durations=[0.0, 0.0],
        )
        # cut 转场仍然会生成 xfade 滤镜（因为底层不区分 cut）
        # 调用方（unified_render_service）负责检测全硬切并走 concat
        assert dur > 0