pycapcut 0.0.1__py3-none-any.whl

pyJianYingDraft/segment.py

@@ -0,0 +1,256 @@
+"""定义片段基类及部分比较通用的属性类"""
+
+import uuid
+from typing import Optional, Dict, List, Any, Union
+
+from .animation import SegmentAnimations
+from .time_util import Timerange, tim
+from .keyframe import KeyframeList, KeyframeProperty
+
+class BaseSegment:
+    """片段基类"""
+
+    segment_id: str
+    """片段全局id, 由程序自动生成"""
+    material_id: str
+    """使用的素材id"""
+    target_timerange: Timerange
+    """片段在轨道上的时间范围"""
+
+    common_keyframes: List[KeyframeList]
+    """各属性的关键帧列表"""
+
+    def __init__(self, material_id: str, target_timerange: Timerange):
+        self.segment_id = uuid.uuid4().hex
+        self.material_id = material_id
+        self.target_timerange = target_timerange
+
+        self.common_keyframes = []
+
+    @property
+    def start(self) -> int:
+        """片段开始时间, 单位为微秒"""
+        return self.target_timerange.start
+    @start.setter
+    def start(self, value: int):
+        self.target_timerange.start = value
+
+    @property
+    def duration(self) -> int:
+        """片段持续时间, 单位为微秒"""
+        return self.target_timerange.duration
+    @duration.setter
+    def duration(self, value: int):
+        self.target_timerange.duration = value
+
+    @property
+    def end(self) -> int:
+        """片段结束时间, 单位为微秒"""
+        return self.target_timerange.end
+
+    def overlaps(self, other: "BaseSegment") -> bool:
+        """判断是否与另一个片段有重叠"""
+        return self.target_timerange.overlaps(other.target_timerange)
+
+    def export_json(self) -> Dict[str, Any]:
+        """返回通用于各种片段的属性"""
+        return {
+            "enable_adjust": True,
+            "enable_color_correct_adjust": False,
+            "enable_color_curves": True,
+            "enable_color_match_adjust": False,
+            "enable_color_wheels": True,
+            "enable_lut": True,
+            "enable_smart_color_adjust": False,
+            "last_nonzero_volume": 1.0,
+            "reverse": False,
+            "track_attribute": 0,
+            "track_render_index": 0,
+            "visible": True,
+            # 写入自定义字段
+            "id": self.segment_id,
+            "material_id": self.material_id,
+            "target_timerange": self.target_timerange.export_json(),
+
+            "common_keyframes": [kf_list.export_json() for kf_list in self.common_keyframes],
+            "keyframe_refs": [],  # 意义不明
+        }
+
+class Speed:
+    """播放速度对象, 目前只支持固定速度"""
+
+    global_id: str
+    """全局id, 由程序自动生成"""
+    speed: float
+    """播放速度"""
+
+    def __init__(self, speed: float):
+        self.global_id = uuid.uuid4().hex
+        self.speed = speed
+
+    def export_json(self) -> Dict[str, Any]:
+        return {
+            "curve_speed": None,
+            "id": self.global_id,
+            "mode": 0,
+            "speed": self.speed,
+            "type": "speed"
+        }
+
+class ClipSettings:
+    """素材片段的图像调节设置"""
+
+    alpha: float
+    """图像不透明度, 0-1"""
+    flip_horizontal: bool
+    """是否水平翻转"""
+    flip_vertical: bool
+    """是否垂直翻转"""
+    rotation: float
+    """顺时针旋转的**角度**, 可正可负"""
+    scale_x: float
+    """水平缩放比例"""
+    scale_y: float
+    """垂直缩放比例"""
+    transform_x: float
+    """水平位移, 单位为半个画布宽"""
+    transform_y: float
+    """垂直位移, 单位为半个画布高"""
+
+    def __init__(self, *, alpha: float = 1.0,
+                 flip_horizontal: bool = False, flip_vertical: bool = False,
+                 rotation: float = 0.0,
+                 scale_x: float = 1.0, scale_y: float = 1.0,
+                 transform_x: float = 0.0, transform_y: float = 0.0):
+        """初始化图像调节设置, 默认不作任何图像变换
+
+        Args:
+            alpha (float, optional): 图像不透明度, 0-1. 默认为1.0.
+            flip_horizontal (bool, optional): 是否水平翻转. 默认为False.
+            flip_vertical (bool, optional): 是否垂直翻转. 默认为False.
+            rotation (float, optional): 顺时针旋转的**角度**, 可正可负. 默认为0.0.
+            scale_x (float, optional): 水平缩放比例. 默认为1.0.
+            scale_y (float, optional): 垂直缩放比例. 默认为1.0.
+            transform_x (float, optional): 水平位移, 单位为半个画布宽. 默认为0.0.
+            transform_y (float, optional): 垂直位移, 单位为半个画布高. 默认为0.0.
+                参考: 剪映导入的字幕似乎取此值为-0.8
+        """
+        self.alpha = alpha
+        self.flip_horizontal, self.flip_vertical = flip_horizontal, flip_vertical
+        self.rotation = rotation
+        self.scale_x, self.scale_y = scale_x, scale_y
+        self.transform_x, self.transform_y = transform_x, transform_y
+
+    def export_json(self) -> Dict[str, Any]:
+        clip_settings_json = {
+            "alpha": self.alpha,
+            "flip": {"horizontal": self.flip_horizontal, "vertical": self.flip_vertical},
+            "rotation": self.rotation,
+            "scale": {"x": self.scale_x, "y": self.scale_y},
+            "transform": {"x": self.transform_x, "y": self.transform_y}
+        }
+        return clip_settings_json
+
+class MediaSegment(BaseSegment):
+    """媒体片段基类"""
+
+    source_timerange: Optional[Timerange]
+    """截取的素材片段的时间范围, 对贴纸而言不存在"""
+    speed: Speed
+    """播放速度设置"""
+    volume: float
+    """音量"""
+
+    extra_material_refs: List[str]
+    """附加的素材id列表, 用于链接动画/特效等"""
+
+    def __init__(self, material_id: str, source_timerange: Optional[Timerange], target_timerange: Timerange, speed: float, volume: float):
+        super().__init__(material_id, target_timerange)
+
+        self.source_timerange = source_timerange
+        self.speed = Speed(speed)
+        self.volume = volume
+
+        self.extra_material_refs = [self.speed.global_id]
+
+    def export_json(self) -> Dict[str, Any]:
+        """返回通用于音频和视频片段的默认属性"""
+        ret = super().export_json()
+        ret.update({
+            "source_timerange": self.source_timerange.export_json() if self.source_timerange else None,
+            "speed": self.speed.speed,
+            "volume": self.volume,
+            "extra_material_refs": self.extra_material_refs,
+        })
+        return ret
+
+class VisualSegment(MediaSegment):
+    """视觉片段基类，用于处理所有可见片段（视频、贴纸、文本）的共同属性和行为"""
+
+    clip_settings: ClipSettings
+    """图像调节设置, 其效果可被关键帧覆盖"""
+
+    uniform_scale: bool
+    """是否锁定XY轴缩放比例"""
+
+    animations_instance: Optional[SegmentAnimations]
+    """动画实例, 可能为空
+
+    在放入轨道时自动添加到素材列表中
+    """
+
+    def __init__(self, material_id: str, source_timerange: Optional[Timerange], target_timerange: Timerange,
+                 speed: float, volume: float, *, clip_settings: Optional[ClipSettings]):
+        """初始化视觉片段基类
+
+        Args:
+            material_id (`str`): 素材id
+            source_timerange (`Timerange`, optional): 截取的素材片段的时间范围
+            target_timerange (`Timerange`): 片段在轨道上的目标时间范围
+            speed (`float`): 播放速度
+            volume (`float`): 音量
+            clip_settings (`ClipSettings`, optional): 图像调节设置, 默认不作任何变换
+        """
+        super().__init__(material_id, source_timerange, target_timerange, speed, volume)
+
+        self.clip_settings = clip_settings if clip_settings is not None else ClipSettings()
+        self.uniform_scale = True
+        self.animations_instance = None
+
+    def add_keyframe(self, _property: KeyframeProperty, time_offset: Union[int, str], value: float) -> "VisualSegment":
+        """为给定属性创建一个关键帧, 并自动加入到关键帧列表中
+
+        Args:
+            _property (`KeyframeProperty`): 要控制的属性
+            time_offset (`int` or `str`): 关键帧的时间偏移量, 单位为微秒. 若传入字符串则会调用`tim()`函数进行解析.
+            value (`float`): 属性在`time_offset`处的值
+
+        Raises:
+            `ValueError`: 试图同时设置`uniform_scale`以及`scale_x`或`scale_y`其中一者
+        """
+        if (_property == KeyframeProperty.scale_x or _property == KeyframeProperty.scale_y) and self.uniform_scale:
+            self.uniform_scale = False
+        elif _property == KeyframeProperty.uniform_scale:
+            if not self.uniform_scale:
+                raise ValueError("已设置 scale_x 或 scale_y 时, 不能再设置 uniform_scale")
+            _property = KeyframeProperty.scale_x
+
+        if isinstance(time_offset, str): time_offset = tim(time_offset)
+
+        for kf_list in self.common_keyframes:
+            if kf_list.keyframe_property == _property:
+                kf_list.add_keyframe(time_offset, value)
+                return self
+        kf_list = KeyframeList(_property)
+        kf_list.add_keyframe(time_offset, value)
+        self.common_keyframes.append(kf_list)
+        return self
+
+    def export_json(self) -> Dict[str, Any]:
+        """导出通用于所有视觉片段的JSON数据"""
+        json_dict = super().export_json()
+        json_dict.update({
+            "clip": self.clip_settings.export_json(),
+            "uniform_scale": {"on": self.uniform_scale, "value": 1.0},
+        })
+        return json_dict

pyJianYingDraft/template_mode.py

@@ -0,0 +1,221 @@
+"""与模板模式相关的类及函数等"""
+
+from enum import Enum
+from copy import deepcopy
+
+from . import util
+from . import exceptions
+from .time_util import Timerange
+from .segment import BaseSegment
+from .track import BaseTrack, TrackType
+from .local_materials import VideoMaterial, AudioMaterial
+
+from typing import List, Dict, Any
+
+class ShrinkMode(Enum):
+    """处理替换素材时素材变短情况的方法"""
+
+    cut_head = "cut_head"
+    """裁剪头部, 即后移片段起始点"""
+    cut_tail = "cut_tail"
+    """裁剪尾部, 即前移片段终止点"""
+
+    cut_tail_align = "cut_tail_align"
+    """裁剪尾部并消除间隙, 即前移片段终止点, 后续片段也依次前移"""
+
+    shrink = "shrink"
+    """保持中间点不变, 两端点向中间靠拢"""
+
+class ExtendMode(Enum):
+    """处理替换素材时素材变长情况的方法"""
+
+    cut_material_tail = "cut_material_tail"
+    """裁剪素材尾部(覆盖`source_timerange`参数), 使得片段维持原长不变, 此方法总是成功"""
+
+    extend_head = "extend_head"
+    """延伸头部, 即尝试前移片段起始点, 与前续片段重合时失败"""
+    extend_tail = "extend_tail"
+    """延伸尾部, 即尝试后移片段终止点, 与后续片段重合时失败"""
+
+    push_tail = "push_tail"
+    """延伸尾部, 若有必要则依次后移后续片段, 此方法总是成功"""
+
+class ImportedSegment(BaseSegment):
+    """导入的片段"""
+
+    raw_data: Dict[str, Any]
+    """原始json数据"""
+
+    __DATA_ATTRS = ["material_id", "target_timerange"]
+    def __init__(self, json_data: Dict[str, Any]):
+        self.raw_data = deepcopy(json_data)
+
+        util.assign_attr_with_json(self, self.__DATA_ATTRS, json_data)
+
+    def export_json(self) -> Dict[str, Any]:
+        json_data = deepcopy(self.raw_data)
+        json_data.update(util.export_attr_to_json(self, self.__DATA_ATTRS))
+        return json_data
+
+class ImportedMediaSegment(ImportedSegment):
+    """导入的视频/音频片段"""
+
+    source_timerange: Timerange
+    """片段取用的素材时间范围"""
+
+    __DATA_ATTRS = ["source_timerange"]
+    def __init__(self, json_data: Dict[str, Any]):
+        super().__init__(json_data)
+
+        util.assign_attr_with_json(self, self.__DATA_ATTRS, json_data)
+
+    def export_json(self) -> Dict[str, Any]:
+        json_data = super().export_json()
+        json_data.update(util.export_attr_to_json(self, self.__DATA_ATTRS))
+        return json_data
+
+
+class ImportedTrack(BaseTrack):
+    """模板模式下导入的轨道"""
+
+    raw_data: Dict[str, Any]
+    """原始轨道数据"""
+
+    def __init__(self, json_data: Dict[str, Any]):
+        self.track_type = TrackType.from_name(json_data["type"])
+        self.name = json_data["name"]
+        self.track_id = json_data["id"]
+        self.render_index = max([int(seg["render_index"]) for seg in json_data["segments"]], default=0)
+
+        self.raw_data = deepcopy(json_data)
+
+    def export_json(self) -> Dict[str, Any]:
+        ret = deepcopy(self.raw_data)
+        ret.update({
+            "name": self.name,
+            "id": self.track_id
+        })
+        return ret
+
+class EditableTrack(ImportedTrack):
+    """模板模式下导入且可修改的轨道(音视频及文本轨道)"""
+
+    segments: List[ImportedSegment]
+    """该轨道包含的片段列表"""
+
+    def __len__(self):
+        return len(self.segments)
+
+    @property
+    def start_time(self) -> int:
+        """轨道起始时间, 微秒"""
+        if len(self.segments) == 0:
+            return 0
+        return self.segments[0].target_timerange.start
+
+    @property
+    def end_time(self) -> int:
+        """轨道结束时间, 微秒"""
+        if len(self.segments) == 0:
+            return 0
+        return self.segments[-1].target_timerange.end
+
+    def export_json(self) -> Dict[str, Any]:
+        ret = super().export_json()
+        # 为每个片段写入render_index
+        segment_exports = [seg.export_json() for seg in self.segments]
+        for seg in segment_exports:
+            seg["render_index"] = self.render_index
+        ret["segments"] = segment_exports
+        return ret
+
+class ImportedTextTrack(EditableTrack):
+    """模板模式下导入的文本轨道"""
+
+    def __init__(self, json_data: Dict[str, Any]):
+        super().__init__(json_data)
+        self.segments = [ImportedSegment(seg) for seg in json_data["segments"]]
+
+class ImportedMediaTrack(EditableTrack):
+    """模板模式下导入的音频/视频轨道"""
+
+    segments: List[ImportedMediaSegment]
+    """该轨道包含的片段列表"""
+
+    def __init__(self, json_data: Dict[str, Any]):
+        super().__init__(json_data)
+        self.segments = [ImportedMediaSegment(seg) for seg in json_data["segments"]]
+
+    def check_material_type(self, material: object) -> bool:
+        """检查素材类型是否与轨道类型匹配"""
+        if self.track_type == TrackType.video and isinstance(material, VideoMaterial):
+            return True
+        if self.track_type == TrackType.audio and isinstance(material, AudioMaterial):
+            return True
+        return False
+
+    def process_timerange(self, seg_index: int, src_timerange: Timerange,
+                          shrink: ShrinkMode, extend: List[ExtendMode]) -> None:
+        """处理素材替换的时间范围变更"""
+        seg = self.segments[seg_index]
+        new_duration = src_timerange.duration
+
+        # 时长变短
+        delta_duration = abs(new_duration - seg.duration)
+        if new_duration < seg.duration:
+            if shrink == ShrinkMode.cut_head:
+                seg.start += delta_duration
+            elif shrink == ShrinkMode.cut_tail:
+                seg.duration -= delta_duration
+            elif shrink == ShrinkMode.cut_tail_align:
+                seg.duration -= delta_duration
+                for i in range(seg_index+1, len(self.segments)):  # 后续片段也依次前移相应值（保持间隙）
+                    self.segments[i].start -= delta_duration
+            elif shrink == ShrinkMode.shrink:
+                seg.duration -= delta_duration
+                seg.start += delta_duration // 2
+            else:
+                raise ValueError(f"Unsupported shrink mode: {shrink}")
+        # 时长变长
+        elif new_duration > seg.duration:
+            success_flag = False
+            prev_seg_end = int(0) if seg_index == 0 else self.segments[seg_index-1].target_timerange.end
+            next_seg_start = int(1e15) if seg_index == len(self.segments)-1 else self.segments[seg_index+1].start
+            for mode in extend:
+                if mode == ExtendMode.extend_head:
+                    if seg.start - delta_duration >= prev_seg_end:
+                        seg.start -= delta_duration
+                        success_flag = True
+                elif mode == ExtendMode.extend_tail:
+                    if seg.target_timerange.end + delta_duration <= next_seg_start:
+                        seg.duration += delta_duration
+                        success_flag = True
+                elif mode == ExtendMode.push_tail:
+                    shift_duration = max(0, seg.target_timerange.end + delta_duration - next_seg_start)
+                    seg.duration += delta_duration
+                    if shift_duration > 0:  # 有必要时后移后续片段
+                        for i in range(seg_index+1, len(self.segments)):
+                            self.segments[i].start += shift_duration
+                    success_flag = True
+                elif mode == ExtendMode.cut_material_tail:
+                    src_timerange.duration = seg.duration
+                    success_flag = True
+                else:
+                    raise ValueError(f"Unsupported extend mode: {mode}")
+
+                if success_flag:
+                    break
+            if not success_flag:
+                raise exceptions.ExtensionFailed(f"未能将片段延长至 {new_duration}μs, 尝试过以下方法: {extend}")
+
+        # 写入素材时间范围
+        seg.source_timerange = src_timerange
+
+def import_track(json_data: Dict[str, Any]) -> ImportedTrack:
+    """导入轨道"""
+    track_type = TrackType.from_name(json_data["type"])
+    if not track_type.value.allow_modify:
+        return ImportedTrack(json_data)
+    if track_type == TrackType.text:
+        return ImportedTextTrack(json_data)
+    return ImportedMediaTrack(json_data)