pycapcut 0.0.1__py3-none-any.whl

pycapcut/text_segment.py

@@ -0,0 +1,436 @@
+"""定义文本片段及其相关类"""
+
+import json
+import uuid
+from copy import deepcopy
+
+from typing import Dict, Tuple, Any
+from typing import Union, Optional, Literal
+
+from .time_util import Timerange, tim
+from .segment import ClipSettings, VisualSegment
+from .animation import SegmentAnimations, Text_animation
+
+from .metadata import FontType, EffectMeta
+from .metadata import TextIntro, TextOutro, TextLoopAnim
+
+class TextStyle:
+    """字体样式类"""
+
+    size: float
+    """字体大小"""
+
+    bold: bool
+    """是否加粗"""
+    italic: bool
+    """是否斜体"""
+    underline: bool
+    """是否加下划线"""
+
+    color: Tuple[float, float, float]
+    """字体颜色, RGB三元组, 取值范围为[0, 1]"""
+    alpha: float
+    """字体不透明度"""
+
+    align: Literal[0, 1, 2]
+    """对齐方式"""
+    vertical: bool
+    """是否为竖排文本"""
+
+    letter_spacing: int
+    """字符间距"""
+    line_spacing: int
+    """行间距"""
+
+    auto_wrapping: bool
+    """是否自动换行"""
+    max_line_width: float
+    """最大行宽, 取值范围为[0, 1]"""
+
+    def __init__(self, *, size: float = 8.0, bold: bool = False, italic: bool = False, underline: bool = False,
+                 color: Tuple[float, float, float] = (1.0, 1.0, 1.0), alpha: float = 1.0,
+                 align: Literal[0, 1, 2] = 0, vertical: bool = False,
+                 letter_spacing: int = 0, line_spacing: int = 0,
+                 auto_wrapping: bool = False, max_line_width: float = 0.82):
+        """
+        Args:
+            size (`float`, optional): 字体大小, 默认为8.0
+            bold (`bool`, optional): 是否加粗, 默认为否
+            italic (`bool`, optional): 是否斜体, 默认为否
+            underline (`bool`, optional): 是否加下划线, 默认为否
+            color (`Tuple[float, float, float]`, optional): 字体颜色, RGB三元组, 取值范围为[0, 1], 默认为白色
+            alpha (`float`, optional): 字体不透明度, 取值范围[0, 1], 默认不透明
+            align (`int`, optional): 对齐方式, 0: 左对齐, 1: 居中, 2: 右对齐, 默认为左对齐
+            vertical (`bool`, optional): 是否为竖排文本, 默认为否
+            letter_spacing (`int`, optional): 字符间距, 定义与剪映中一致, 默认为0
+            line_spacing (`int`, optional): 行间距, 定义与剪映中一致, 默认为0
+            auto_wrapping (`bool`, optional): 是否自动换行, 默认关闭
+            max_line_width (`float`, optional): 每行最大行宽占屏幕宽度比例, 取值范围为[0, 1], 默认为0.82
+        """
+        self.size = size
+        self.bold = bold
+        self.italic = italic
+        self.underline = underline
+
+        self.color = color
+        self.alpha = alpha
+
+        self.align = align
+        self.vertical = vertical
+
+        self.letter_spacing = letter_spacing
+        self.line_spacing = line_spacing
+
+        self.auto_wrapping = auto_wrapping
+        self.max_line_width = max_line_width
+
+class TextBorder:
+    """文本描边的参数"""
+
+    alpha: float
+    """描边不透明度"""
+    color: Tuple[float, float, float]
+    """描边颜色, RGB三元组, 取值范围为[0, 1]"""
+    width: float
+    """描边宽度"""
+
+    def __init__(self, *, alpha: float = 1.0, color: Tuple[float, float, float] = (0.0, 0.0, 0.0), width: float = 40.0):
+        """
+        Args:
+            alpha (`float`, optional): 描边不透明度, 取值范围[0, 1], 默认为1.0
+            color (`Tuple[float, float, float]`, optional): 描边颜色, RGB三元组, 取值范围为[0, 1], 默认为黑色
+            width (`float`, optional): 描边宽度, 与剪映中一致, 取值范围为[0, 100], 默认为40.0
+        """
+        self.alpha = alpha
+        self.color = color
+        self.width = width / 100.0 * 0.2  # 此映射可能不完全正确
+
+    def export_json(self) -> Dict[str, Any]:
+        """导出JSON数据, 放置在素材content的styles中"""
+        return {
+            "content": {
+                "solid": {
+                    "alpha": self.alpha,
+                    "color": list(self.color),
+                }
+            },
+            "width": self.width
+        }
+
+class TextBackground:
+    """文本背景参数"""
+
+    style: Literal[1, 2]
+    """背景样式"""
+
+    alpha: float
+    """背景不透明度"""
+    color: str
+    """背景颜色, 格式为'#RRGGBB'"""
+    round_radius: float
+    """背景圆角半径"""
+    height: float
+    """背景高度"""
+    width: float
+    """背景宽度"""
+    horizontal_offset: float
+    """背景水平偏移"""
+    vertical_offset: float
+    """背景竖直偏移"""
+
+    def __init__(self, *, color: str, style: Literal[1, 2] = 1, alpha: float = 1.0, round_radius: float = 0.0,
+                 height: float = 0.14, width: float = 0.14,
+                 horizontal_offset: float = 0.5, vertical_offset: float = 0.5):
+        """
+        Args:
+            color (`str`): 背景颜色, 格式为'#RRGGBB'
+            style (`int`, optional): 背景样式, 1和2分别对应剪映中的两种样式, 默认为1
+            alpha (`float`, optional): 背景不透明度, 与剪映中一致, 取值范围[0, 1], 默认为1.0
+            round_radius (`float`, optional): 背景圆角半径, 与剪映中一致, 取值范围[0, 1], 默认为0.0
+            height (`float`, optional): 背景高度, 与剪映中一致, 取值范围为[0, 1], 默认为0.14
+            width (`float`, optional): 背景宽度, 与剪映中一致, 取值范围为[0, 1], 默认为0.14
+            horizontal_offset (`float`, optional): 背景水平偏移, 与剪映中一致, 取值范围为[0, 1], 默认为0.5
+            vertical_offset (`float`, optional): 背景竖直偏移, 与剪映中一致, 取值范围为[0, 1], 默认为0.5
+        """
+        self.style = style
+
+        self.alpha = alpha
+        self.color = color
+        self.round_radius = round_radius
+        self.height = height
+        self.width = width
+        self.horizontal_offset = horizontal_offset * 2 - 1
+        self.vertical_offset = vertical_offset * 2 - 1
+
+    def export_json(self) -> Dict[str, Any]:
+        """生成子JSON数据, 在TextSegment导出时合并到其中"""
+        return {
+            "background_style": self.style,
+            "background_color": self.color,
+            "background_alpha": self.alpha,
+            "background_round_radius": self.round_radius,
+            "background_height": self.height,
+            "background_width": self.width,
+            "background_horizontal_offset": self.horizontal_offset,
+            "background_vertical_offset": self.vertical_offset,
+        }
+
+class TextBubble:
+    """文本气泡素材, 与滤镜素材本质上一致"""
+
+    global_id: str
+    """气泡全局id, 由程序自动生成"""
+
+    effect_id: str
+    resource_id: str
+
+    def __init__(self, effect_id: str, resource_id: str):
+        self.global_id = uuid.uuid4().hex
+        self.effect_id = effect_id
+        self.resource_id = resource_id
+
+    def export_json(self) -> Dict[str, Any]:
+        return {
+            "apply_target_type": 0,
+            "effect_id": self.effect_id,
+            "id": self.global_id,
+            "resource_id": self.resource_id,
+            "type": "text_shape",
+            "value": 1.0,
+            # 不导出path和request_id
+        }
+
+class TextEffect(TextBubble):
+    """文本花字素材, 与滤镜素材本质上也一致"""
+
+    def export_json(self) -> Dict[str, Any]:
+        ret = super().export_json()
+        ret["type"] = "text_effect"
+        ret["source_platform"] = 1
+        return ret
+
+class TextSegment(VisualSegment):
+    """文本片段类, 目前仅支持设置基本的字体样式"""
+
+    text: str
+    """文本内容"""
+    font: Optional[EffectMeta]
+    """字体类型"""
+    style: TextStyle
+    """字体样式"""
+
+    border: Optional[TextBorder]
+    """文本描边参数, None表示无描边"""
+    background: Optional[TextBackground]
+    """文本背景参数, None表示无背景"""
+
+    bubble: Optional[TextBubble]
+    """文本气泡效果, 在放入轨道时加入素材列表中"""
+    effect: Optional[TextEffect]
+    """文本花字效果, 在放入轨道时加入素材列表中, 目前仅支持一部分花字效果"""
+
+    def __init__(self, text: str, timerange: Timerange, *,
+                 font: Optional[FontType] = None,
+                 style: Optional[TextStyle] = None, clip_settings: Optional[ClipSettings] = None,
+                 border: Optional[TextBorder] = None, background: Optional[TextBackground] = None):
+        """创建文本片段, 并指定其时间信息、字体样式及图像调节设置
+
+        片段创建完成后, 可通过`ScriptFile.add_segment`方法将其添加到轨道中
+
+        Args:
+            text (`str`): 文本内容
+            timerange (`Timerange`): 片段在轨道上的时间范围
+            font (`Font_type`, optional): 字体类型, 默认为系统字体
+            style (`TextStyle`, optional): 字体样式, 包含大小/颜色/对齐/透明度等.
+            clip_settings (`ClipSettings`, optional): 图像调节设置, 默认不做任何变换
+            border (`TextBorder`, optional): 文本描边参数, 默认无描边
+            background (`TextBackground`, optional): 文本背景参数, 默认无背景
+        """
+        super().__init__(uuid.uuid4().hex, None, timerange, 1.0, 1.0, clip_settings=clip_settings)
+
+        self.text = text
+        self.font = font.value if font else None
+        self.style = style or TextStyle()
+        self.border = border
+        self.background = background
+
+        self.bubble = None
+        self.effect = None
+
+    @classmethod
+    def create_from_template(cls, text: str, timerange: Timerange, template: "TextSegment") -> "TextSegment":
+        """根据模板创建新的文本片段, 并指定其文本内容"""
+        new_segment = cls(text, timerange, style=deepcopy(template.style), clip_settings=deepcopy(template.clip_settings),
+                          border=deepcopy(template.border), background=deepcopy(template.background))
+        new_segment.font = deepcopy(template.font)
+
+        # 处理动画等
+        if template.animations_instance:
+            new_segment.animations_instance = deepcopy(template.animations_instance)
+            new_segment.animations_instance.animation_id = uuid.uuid4().hex
+            new_segment.extra_material_refs.append(new_segment.animations_instance.animation_id)
+        if template.bubble:
+            new_segment.add_bubble(template.bubble.effect_id, template.bubble.resource_id)
+        if template.effect:
+            new_segment.add_effect(template.effect.effect_id)
+
+        return new_segment
+
+    def add_animation(self, animation_type: Union[TextIntro, TextOutro, TextLoopAnim],
+                      duration: Union[str, float] = 500000) -> "TextSegment":
+        """将给定的入场/出场/循环动画添加到此片段的动画列表中, 出入场动画的持续时间可以自行设置, 循环动画则会自动填满其余无动画部分
+
+        注意: 若希望同时使用循环动画和入出场动画, 请**先添加出入场动画再添加循环动画**
+
+        Args:
+            animation_type (`TextIntro`, `TextOutro` or `TextLoopAnim`): 文本动画类型.
+            duration (`str` or `float`, optional): 动画持续时间, 单位为微秒, 仅对入场/出场动画有效.
+                若传入字符串则会调用`tim()`函数进行解析. 默认为0.5秒
+        """
+        duration = min(tim(duration), self.target_timerange.duration)
+
+        if isinstance(animation_type, TextIntro):
+            start = 0
+        elif isinstance(animation_type, TextOutro):
+            start = self.target_timerange.duration - duration
+        elif isinstance(animation_type, TextLoopAnim):
+            intro_trange = self.animations_instance and self.animations_instance.get_animation_trange("in")
+            outro_trange = self.animations_instance and self.animations_instance.get_animation_trange("out")
+            start = intro_trange.start if intro_trange else 0
+            duration = self.target_timerange.duration - start - (outro_trange.duration if outro_trange else 0)
+        else:
+            raise TypeError("Invalid animation type %s" % type(animation_type))
+
+        if self.animations_instance is None:
+            self.animations_instance = SegmentAnimations()
+            self.extra_material_refs.append(self.animations_instance.animation_id)
+
+        self.animations_instance.add_animation(Text_animation(animation_type, start, duration))
+
+        return self
+
+    def add_bubble(self, effect_id: str, resource_id: str) -> "TextSegment":
+        """根据素材信息添加气泡效果, 相应素材信息可通过`ScriptFile.inspect_material`从模板中获取
+
+        Args:
+            effect_id (`str`): 气泡效果的effect_id
+            resource_id (`str`): 气泡效果的resource_id
+        """
+        self.bubble = TextBubble(effect_id, resource_id)
+        self.extra_material_refs.append(self.bubble.global_id)
+        return self
+
+    def add_effect(self, effect_id: str) -> "TextSegment":
+        """根据素材信息添加花字效果, 相应素材信息可通过`ScriptFile.inspect_material`从模板中获取
+
+        Args:
+            effect_id (`str`): 花字效果的effect_id, 也同时是其resource_id
+        """
+        self.effect = TextEffect(effect_id, effect_id)
+        self.extra_material_refs.append(self.effect.global_id)
+        return self
+
+    def export_material(self) -> Dict[str, Any]:
+        """与此文本片段联系的素材, 以此不再单独定义Text_material类"""
+        # 叠加各类效果的flag
+        check_flag: int = 7
+        if self.border:
+            check_flag |= 8
+        if self.background:
+            check_flag |= 16
+
+        content_json = {
+            "styles": [
+                {
+                    "fill": {
+                        "alpha": 1.0,
+                        "content": {
+                            "render_type": "solid",
+                            "solid": {
+                                "alpha": 1.0,
+                                "color": list(self.style.color)
+                            }
+                        }
+                    },
+                    "range": [0, len(self.text)],
+                    "size": self.style.size,
+                    "bold": self.style.bold,
+                    "italic": self.style.italic,
+                    "underline": self.style.underline,
+                    "strokes": [self.border.export_json()] if self.border else []
+                }
+            ],
+            "text": self.text
+        }
+        if self.font:
+            content_json["styles"][0]["font"] = {
+                "id": self.font.resource_id,
+                "path": "C:/%s.ttf" % self.font.name  # 并不会真正在此处放置字体文件
+            }
+        if self.effect:
+            content_json["styles"][0]["effectStyle"] = {
+                "id": self.effect.effect_id,
+                "path": "C:"  # 并不会真正在此处放置素材文件
+            }
+
+        ret = {
+            "id": self.material_id,
+            "content": json.dumps(content_json, ensure_ascii=False),
+
+            "typesetting": int(self.style.vertical),
+            "alignment": self.style.align,
+            "letter_spacing": self.style.letter_spacing * 0.05,
+            "line_spacing": 0.02 + self.style.line_spacing * 0.05,
+
+            "line_feed": 1,
+            "line_max_width": self.style.max_line_width,
+            "force_apply_line_max_width": False,
+
+            "check_flag": check_flag,
+
+            "type": "subtitle" if self.style.auto_wrapping else "text",
+
+            # 混合 (+4)
+            "global_alpha": self.style.alpha,
+
+            # 发光 (+64)，属性由extra_material_refs记录
+
+            # 阴影 (+32)
+            # "has_shadow": False,
+            # "shadow_alpha": 0.9,
+            # "shadow_angle": -45.0,
+            # "shadow_color": "",
+            # "shadow_distance": 5.0,
+            # "shadow_point": {
+            #     "x": 0.6363961030678928,
+            #     "y": -0.6363961030678928
+            # },
+            # "shadow_smoothing": 0.45,
+
+            # 整体字体设置, 似乎会被content覆盖
+            # "font_category_id": "",
+            # "font_category_name": "",
+            # "font_id": "",
+            # "font_name": "",
+            # "font_path": "",
+            # "font_resource_id": "",
+            # "font_size": 15.0,
+            # "font_source_platform": 0,
+            # "font_team_id": "",
+            # "font_title": "none",
+            # "font_url": "",
+            # "fonts": [],
+
+            # 似乎会被content覆盖
+            # "text_alpha": 1.0,
+            # "text_color": "#FFFFFF",
+            # "text_curve": None,
+            # "text_preset_resource_id": "",
+            # "text_size": 30,
+            # "underline": False,
+        }
+
+        if self.background:
+            ret.update(self.background.export_json())
+
+        return ret

pycapcut/time_util.py

@@ -0,0 +1,99 @@
+"""定义时间范围类以及与时间相关的辅助函数"""
+
+from typing import Union
+from typing import Dict
+
+SEC = 1000000
+"""一秒=1e6微秒"""
+
+def tim(inp: Union[str, float]) -> int:
+    """将输入的字符串转换为微秒, 也可直接输入微秒数
+
+    支持类似 "1h52m3s" 或 "0.15s" 这样的格式, 可包含负号以表示负偏移
+    """
+    if isinstance(inp, (int, float)):
+        return int(round(inp))
+
+    sign: int = 1
+    inp = inp.strip().lower()
+    if inp.startswith("-"):
+        sign = -1
+        inp = inp[1:]
+
+    last_index: int = 0
+    total_time: float = 0
+    for unit, factor in zip(["h", "m", "s"], [3600*SEC, 60*SEC, SEC]):
+        unit_index = inp.find(unit)
+        if unit_index == -1: continue
+
+        total_time += float(inp[last_index:unit_index]) * factor
+        last_index = unit_index + 1
+
+    return int(round(total_time) * sign)
+
+class Timerange:
+    """记录了起始时间及持续长度的时间范围"""
+    start: int
+    """起始时间, 单位为微秒"""
+    duration: int
+    """持续长度, 单位为微秒"""
+
+    def __init__(self, start: int, duration: int):
+        """构造一个时间范围
+
+        Args:
+            start (int): 起始时间, 单位为微秒
+            duration (int): 持续长度, 单位为微秒
+        """
+
+        self.start = start
+        self.duration = duration
+
+    @classmethod
+    def import_json(cls, json_obj: Dict[str, str]) -> "Timerange":
+        """从json对象中恢复Timerange"""
+        return cls(int(json_obj["start"]), int(json_obj["duration"]))
+
+    @property
+    def end(self) -> int:
+        """结束时间, 单位为微秒"""
+        return self.start + self.duration
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Timerange):
+            return False
+        return self.start == other.start and self.duration == other.duration
+
+    def overlaps(self, other: "Timerange") -> bool:
+        """判断两个时间范围是否有重叠"""
+        return not (self.end <= other.start or other.end <= self.start)
+
+    def __repr__(self) -> str:
+        return f"Timerange(start={self.start}, duration={self.duration})"
+
+    def __str__(self) -> str:
+        return f"[start={self.start}, end={self.end}]"
+
+    def export_json(self) -> Dict[str, int]:
+        return {"start": self.start, "duration": self.duration}
+
+def trange(start: Union[str, float], duration: Union[str, float]) -> Timerange:
+    """Timerange的简便构造函数, 接受字符串或微秒数作为参数
+
+    支持类似 "1h52m3s" 或 "0.15s" 这样的格式
+
+    Args:
+        start (Union[str, float]): 起始时间
+        duration (Union[str, float]): 持续长度, 注意**不是结束时间**
+    """
+    return Timerange(tim(start), tim(duration))
+
+def srt_tstamp(srt_tstamp: str) -> int:
+    """解析srt中的时间戳字符串, 返回微秒数"""
+    sec_str, ms_str = srt_tstamp.split(",")
+    parts = sec_str.split(":") + [ms_str]
+
+    total_time = 0
+    for value, factor in zip(parts, [3600*SEC, 60*SEC, SEC, 1000]):
+        total_time += int(value) * factor
+    return total_time

pycapcut/track.py

@@ -0,0 +1,138 @@
+"""轨道类及其元数据"""
+
+import uuid
+
+from enum import Enum
+from typing import TypeVar, Generic, Type
+from typing import Dict, List, Any, Union
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+
+from .exceptions import SegmentOverlap
+from .segment import BaseSegment
+from .video_segment import VideoSegment, StickerSegment
+from .audio_segment import AudioSegment
+from .text_segment import TextSegment
+from .effect_segment import EffectSegment, FilterSegment
+
+@dataclass
+class Track_meta:
+    """与轨道类型关联的轨道元数据"""
+
+    segment_type: Union[Type[VideoSegment], Type[AudioSegment],
+                        Type[EffectSegment], Type[FilterSegment],
+                        Type[TextSegment], Type[StickerSegment], None]
+    """与轨道关联的片段类型"""
+    render_index: int
+    """默认渲染顺序, 值越大越接近前景"""
+    allow_modify: bool
+    """当被导入时, 是否允许修改"""
+
+class TrackType(Enum):
+    """轨道类型枚举
+
+    变量名对应type属性, 值表示相应的轨道元数据
+    """
+
+    video = Track_meta(VideoSegment, 0, True)
+    audio = Track_meta(AudioSegment, 0, True)
+    effect = Track_meta(EffectSegment, 10000, False)
+    filter = Track_meta(FilterSegment, 11000, False)
+    sticker = Track_meta(StickerSegment, 14000, False)
+    text = Track_meta(TextSegment, 15000, True)  # 原本是14000, 避免与sticker冲突改为15000
+
+    adjust = Track_meta(None, 0, False)
+    """仅供导入时使用, 不要尝试新建此类型的轨道"""
+
+    @staticmethod
+    def from_name(name: str) -> "TrackType":
+        """根据名称获取轨道类型枚举"""
+        for t in TrackType:
+            if t.name == name:
+                return t
+        raise ValueError("Invalid track type: %s" % name)
+
+
+class BaseTrack(ABC):
+    """轨道基类"""
+
+    track_type: TrackType
+    """轨道类型"""
+    name: str
+    """轨道名称"""
+    track_id: str
+    """轨道全局ID"""
+    render_index: int
+    """渲染顺序, 值越大越接近前景"""
+
+    @abstractmethod
+    def export_json(self) -> Dict[str, Any]: ...
+
+Seg_type = TypeVar("Seg_type", bound=BaseSegment)
+class Track(BaseTrack, Generic[Seg_type]):
+    """非模板模式下的轨道"""
+
+    mute: bool
+    """是否静音"""
+
+    segments: List[Seg_type]
+    """该轨道包含的片段列表"""
+
+    def __init__(self, track_type: TrackType, name: str, render_index: int, mute: bool):
+        self.track_type = track_type
+        self.name = name
+        self.track_id = uuid.uuid4().hex
+        self.render_index = render_index
+
+        self.mute = mute
+        self.segments = []
+
+    @property
+    def end_time(self) -> int:
+        """轨道结束时间, 微秒"""
+        if len(self.segments) == 0:
+            return 0
+        return self.segments[-1].target_timerange.end
+
+    @property
+    def accept_segment_type(self) -> Type[Seg_type]:
+        """返回该轨道允许的片段类型"""
+        return self.track_type.value.segment_type  # type: ignore
+
+    def add_segment(self, segment: Seg_type) -> "Track[Seg_type]":
+        """向轨道中添加一个片段, 添加的片段必须匹配轨道类型且不与现有片段重叠
+
+        Args:
+            segment (Seg_type): 要添加的片段
+
+        Raises:
+            `TypeError`: 新片段类型与轨道类型不匹配
+            `SegmentOverlap`: 新片段与现有片段重叠
+        """
+        if not isinstance(segment, self.accept_segment_type):
+            raise TypeError("New segment (%s) is not of the same type as the track (%s)" % (type(segment), self.accept_segment_type))
+
+        # 检查片段是否重叠
+        for seg in self.segments:
+            if seg.overlaps(segment):
+                raise SegmentOverlap("New segment overlaps with existing segment [start: {}, end: {}]"
+                                     .format(segment.target_timerange.start, segment.target_timerange.end))
+
+        self.segments.append(segment)
+        return self
+
+    def export_json(self) -> Dict[str, Any]:
+        # 为每个片段写入render_index
+        segment_exports = [seg.export_json() for seg in self.segments]
+        for seg in segment_exports:
+            seg["render_index"] = self.render_index
+
+        return {
+            "attribute": int(self.mute),
+            "flag": 0,
+            "id": self.track_id,
+            "is_default_name": len(self.name) == 0,
+            "name": self.name,
+            "segments": segment_exports,
+            "type": self.track_type.name
+        }