pycapcut 0.0.1__py3-none-any.whl

pyJianYingDraft/audio_segment.py

@@ -0,0 +1,225 @@
+"""定义音频片段及其相关类
+
+包含淡入淡出效果、音频特效等相关类
+"""
+
+import uuid
+from copy import deepcopy
+
+from typing import Optional, Literal, Union
+from typing import Dict, List, Any
+
+from .time_util import tim, Timerange
+from .segment import MediaSegment
+from .local_materials import AudioMaterial
+from .keyframe import KeyframeProperty, KeyframeList
+
+from .metadata import EffectParamInstance
+from .metadata import AudioSceneEffectType, ToneEffectType, SpeechToSongType
+
+class AudioFade:
+    """音频淡入淡出效果"""
+
+    fade_id: str
+    """淡入淡出效果的全局id, 自动生成"""
+
+    in_duration: int
+    """淡入时长, 单位为微秒"""
+    out_duration: int
+    """淡出时长, 单位为微秒"""
+
+    def __init__(self, in_duration: int, out_duration: int):
+        """根据给定的淡入/淡出时长构造一个淡入淡出效果"""
+
+        self.fade_id = uuid.uuid4().hex
+        self.in_duration = in_duration
+        self.out_duration = out_duration
+
+    def export_json(self) -> Dict[str, Any]:
+        return {
+            "id": self.fade_id,
+            "fade_in_duration": self.in_duration,
+            "fade_out_duration": self.out_duration,
+            "fade_type": 0,
+            "type": "audio_fade"
+        }
+
+class AudioEffect:
+    """音频特效对象"""
+
+    name: str
+    """特效名称"""
+    effect_id: str
+    """特效全局id, 由程序自动生成"""
+    resource_id: str
+    """资源id, 由剪映本身提供"""
+
+    category_id: Literal["sound_effect", "tone", "speech_to_song"]
+    category_name: Literal["场景音", "音色", "声音成曲"]
+    category_index: Literal[1, 2, 3]
+
+    audio_adjust_params: List[EffectParamInstance]
+
+    def __init__(self, effect_meta: Union[AudioSceneEffectType, ToneEffectType, SpeechToSongType],
+                 params: Optional[List[Optional[float]]] = None):
+        """根据给定的音效元数据及参数列表构造一个音频特效对象, params的范围是0~100"""
+
+        self.name = effect_meta.value.name
+        self.effect_id = uuid.uuid4().hex
+        self.resource_id = effect_meta.value.resource_id
+        self.audio_adjust_params = []
+
+        if isinstance(effect_meta, AudioSceneEffectType):
+            self.category_id = "sound_effect"
+            self.category_name = "场景音"
+            self.category_index = 1
+        elif isinstance(effect_meta, ToneEffectType):
+            self.category_id = "tone"
+            self.category_name = "音色"
+            self.category_index = 2
+        elif isinstance(effect_meta, SpeechToSongType):
+            self.category_id = "speech_to_song"
+            self.category_name = "声音成曲"
+            self.category_index = 3
+        else:
+            raise TypeError("不支持的元数据类型 %s" % type(effect_meta))
+
+        self.audio_adjust_params = effect_meta.value.parse_params(params)
+
+    def export_json(self) -> Dict[str, Any]:
+        return {
+            "audio_adjust_params": [param.export_json() for param in self.audio_adjust_params],
+            "category_id": self.category_id,
+            "category_name": self.category_name,
+            "id": self.effect_id,
+            "is_ugc": False,
+            "name": self.name,
+            "production_path": "",
+            "resource_id": self.resource_id,
+            "speaker_id": "",
+            "sub_type": self.category_index,
+            "time_range": {"duration": 0, "start": 0},  # 似乎并未用到
+            "type": "audio_effect"
+            # 不导出path和constant_material_id
+        }
+
+class AudioSegment(MediaSegment):
+    """安放在轨道上的一个音频片段"""
+
+    material_instance: AudioMaterial
+    """音频素材实例"""
+
+    fade: Optional[AudioFade]
+    """音频淡入淡出效果, 可能为空
+
+    在放入轨道时自动添加到素材列表中
+    """
+
+    effects: List[AudioEffect]
+    """音频特效列表
+
+    在放入轨道时自动添加到素材列表中
+    """
+
+    def __init__(self, material: Union[AudioMaterial, str], target_timerange: Timerange, *,
+                 source_timerange: Optional[Timerange] = None, speed: Optional[float] = None, volume: float = 1.0):
+        """利用给定的音频素材构建一个轨道片段, 并指定其时间信息及播放速度/音量
+
+        Args:
+            material (`AudioMaterial` or `str`): 素材实例或素材路径, 若为路径则自动构造素材实例
+            target_timerange (`Timerange`): 片段在轨道上的目标时间范围
+            source_timerange (`Timerange`, optional): 截取的素材片段的时间范围, 默认从开头根据`speed`截取与`target_timerange`等长的一部分
+            speed (`float`, optional): 播放速度, 默认为1.0. 此项与`source_timerange`同时指定时, 将覆盖`target_timerange`中的时长
+            volume (`float`, optional): 音量, 默认为1.0
+
+        Raises:
+            `ValueError`: 指定的或计算出的`source_timerange`超出了素材的时长范围
+        """
+        if isinstance(material, str):
+            material = AudioMaterial(material)
+
+        if source_timerange is not None and speed is not None:
+            target_timerange = Timerange(target_timerange.start, round(source_timerange.duration / speed))
+        elif source_timerange is not None and speed is None:
+            speed = source_timerange.duration / target_timerange.duration
+        else:  # source_timerange is None
+            speed = speed if speed is not None else 1.0
+            source_timerange = Timerange(0, round(target_timerange.duration * speed))
+
+        if source_timerange.end > material.duration:
+            raise ValueError(f"截取的素材时间范围 {source_timerange} 超出了素材时长({material.duration})")
+
+        super().__init__(material.material_id, source_timerange, target_timerange, speed, volume)
+
+        self.material_instance = deepcopy(material)
+        self.fade = None
+        self.effects = []
+
+    def add_effect(self, effect_type: Union[AudioSceneEffectType, ToneEffectType, SpeechToSongType],
+                   params: Optional[List[Optional[float]]] = None) -> "AudioSegment":
+        """为音频片段添加一个作用于整个片段的音频效果, 目前"声音成曲"效果不能自动被剪映所识别
+
+        Args:
+            effect_type (`AudioSceneEffectType` | `ToneEffectType` | `SpeechToSongType`): 音效类型, 一类音效只能添加一个.
+            params (`List[Optional[float]]`, optional): 音效参数列表, 参数列表中未提供或为None的项使用默认值.
+                参数取值范围(0~100)与剪映中一致. 某个特效类型有何参数以及具体参数顺序以枚举类成员的annotation为准.
+
+        Raises:
+            `ValueError`: 试图添加一个已经存在的音效类型、提供的参数数量超过了该音效类型的参数数量, 或参数值超出范围.
+        """
+        if params is not None and len(params) > len(effect_type.value.params):
+            raise ValueError("为音频效果 %s 传入了过多的参数" % effect_type.value.name)
+
+        effect_inst = AudioEffect(effect_type, params)
+        if effect_inst.category_id in [eff.category_id for eff in self.effects]:
+            raise ValueError("当前音频片段已经有此类型 (%s) 的音效了" % effect_inst.category_name)
+        self.effects.append(effect_inst)
+        self.extra_material_refs.append(effect_inst.effect_id)
+
+        return self
+
+    def add_fade(self, in_duration: Union[str, int], out_duration: Union[str, int]) -> "AudioSegment":
+        """为音频片段添加淡入淡出效果
+
+        Args:
+            in_duration (`int` or `str`): 音频淡入时长, 单位为微秒, 若为字符串则会调用`tim()`函数进行解析
+            out_duration (`int` or `str`): 音频淡出时长, 单位为微秒, 若为字符串则会调用`tim()`函数进行解析
+
+        Raises:
+            `ValueError`: 当前片段已存在淡入淡出效果
+        """
+        if self.fade is not None:
+            raise ValueError("当前片段已存在淡入淡出效果")
+
+        if isinstance(in_duration, str): in_duration = tim(in_duration)
+        if isinstance(out_duration, str): out_duration = tim(out_duration)
+
+        self.fade = AudioFade(in_duration, out_duration)
+        self.extra_material_refs.append(self.fade.fade_id)
+
+        return self
+
+    def add_keyframe(self, time_offset: int, volume: float) -> "AudioSegment":
+        """为音频片段创建一个*控制音量*的关键帧, 并自动加入到关键帧列表中
+
+        Args:
+            time_offset (`int`): 关键帧的时间偏移量, 单位为微秒
+            volume (`float`): 音量在`time_offset`处的值
+        """
+        _property = KeyframeProperty.volume
+        for kf_list in self.common_keyframes:
+            if kf_list.keyframe_property == _property:
+                kf_list.add_keyframe(time_offset, volume)
+                return self
+        kf_list = KeyframeList(_property)
+        kf_list.add_keyframe(time_offset, volume)
+        self.common_keyframes.append(kf_list)
+        return self
+
+    def export_json(self) -> Dict[str, Any]:
+        json_dict = super().export_json()
+        json_dict.update({
+            "clip": None,
+            "hdr_settings": None
+        })
+        return json_dict

pyJianYingDraft/draft_content_template.json

@@ -0,0 +1,119 @@
+{
+    "canvas_config": {
+        "height": 1080,
+        "ratio": "original",
+        "width": 1920
+    },
+    "color_space": 0,
+    "config": {
+        "adjust_max_index": 1,
+        "attachment_info": [],
+        "combination_max_index": 1,
+        "export_range": null,
+        "extract_audio_last_index": 1,
+        "lyrics_recognition_id": "",
+        "lyrics_sync": true,
+        "lyrics_taskinfo": [],
+        "maintrack_adsorb": true,
+        "material_save_mode": 0,
+        "multi_language_current": "none",
+        "multi_language_list": [],
+        "multi_language_main": "none",
+        "multi_language_mode": "none",
+        "original_sound_last_index": 1,
+        "record_audio_last_index": 1,
+        "sticker_max_index": 1,
+        "subtitle_keywords_config": null,
+        "subtitle_recognition_id": "",
+        "subtitle_sync": true,
+        "subtitle_taskinfo": [],
+        "system_font_list": [],
+        "video_mute": false,
+        "zoom_info_params": null
+    },
+    "cover": null,
+    "create_time": 0,
+    "duration": 0,
+    "extra_info": null,
+    "fps": 30.0,
+    "free_render_index_mode_on": false,
+    "group_container": null,
+    "id": "91E08AC5-22FB-47e2-9AA0-7DC300FAEA2B",
+    "keyframe_graph_list": [],
+    "keyframes": {
+        "adjusts": [],
+        "audios": [],
+        "effects": [],
+        "filters": [],
+        "handwrites": [],
+        "stickers": [],
+        "texts": [],
+        "videos": []
+    },
+    "last_modified_platform": {
+        "app_id": 3704,
+        "app_source": "lv",
+        "app_version": "5.9.0",
+        "os": "windows"
+    },
+    "materials": {
+        "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": [],
+        "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": []
+    },
+    "mutable_config": null,
+    "name": "",
+    "new_version": "110.0.0",
+    "relationships": [],
+    "render_index_track_mode_on": false,
+    "retouch_cover": null,
+    "source": "default",
+    "static_cover_image_path": "",
+    "time_marks": null,
+    "tracks": [
+    ],
+    "update_time": 0,
+    "version": 360000
+}

pyJianYingDraft/draft_folder.py

@@ -0,0 +1,153 @@
+"""草稿文件夹管理器"""
+
+import os
+import shutil
+
+from typing import List
+
+from . import assets
+from .script_file import ScriptFile
+
+class DraftFolder:
+    """管理一个文件夹及其内的一系列草稿"""
+
+    folder_path: str
+    """根路径"""
+
+    def __init__(self, folder_path: str):
+        """初始化草稿文件夹管理器
+
+        Args:
+            folder_path (`str`): 包含若干草稿的文件夹, 一般取剪映保存草稿的位置即可
+
+        Raises:
+            `FileNotFoundError`: 路径不存在
+        """
+        self.folder_path = folder_path
+
+        if not os.path.exists(self.folder_path):
+            raise FileNotFoundError(f"根文件夹 {self.folder_path} 不存在")
+
+    def list_drafts(self) -> List[str]:
+        """列出文件夹中所有草稿的名称
+
+        注意: 本函数只是如实地列出子文件夹的名称, 并不检查它们是否符合草稿的格式
+        """
+        return [f for f in os.listdir(self.folder_path) if os.path.isdir(os.path.join(self.folder_path, f))]
+
+    def has_draft(self, draft_name: str) -> bool:
+        """检查文件夹中是否存在指定名称的草稿
+
+        注意: 本函数只检查文件夹是否存在, 并不检查草稿是否符合剪映的格式
+
+        Args:
+            draft_name (`str`): 草稿名称, 即相应文件夹名称
+        """
+        return draft_name in self.list_drafts()
+
+    def remove(self, draft_name: str) -> None:
+        """删除指定名称的草稿
+
+        Args:
+            draft_name (`str`): 草稿名称, 即相应文件夹名称
+
+        Raises:
+            `FileNotFoundError`: 对应的草稿不存在
+        """
+        draft_path = os.path.join(self.folder_path, draft_name)
+        if not os.path.exists(draft_path):
+            raise FileNotFoundError(f"草稿文件夹 {draft_name} 不存在")
+
+        shutil.rmtree(draft_path)
+
+    def create_draft(self, draft_name: str, width: int, height: int, fps: int = 30, *,
+                     allow_replace: bool = False) -> ScriptFile:
+        """创建一个新草稿并开始编辑, 编辑完成后使用`ScriptFile.save()`保存即可
+
+        Args:
+            draft_name (`str`): 草稿名称, 即相应文件夹名称
+            width (`int`): 视频宽度, 单位为像素
+            height (`int`): 视频高度, 单位为像素
+            fps (`int`, optional): 视频帧率. 默认为30.
+            allow_replace (`bool`, optional): 是否允许覆盖与`draft_name`重名的草稿. 默认为否.
+
+        Raises:
+            `FileExistsError`: 已存在与`draft_name`重名的草稿, 但不允许覆盖.
+        """
+        draft_path = os.path.join(self.folder_path, draft_name)
+        if os.path.exists(draft_path):
+            if not allow_replace:
+                raise FileExistsError(f"草稿文件夹 {draft_name} 已存在且不允许覆盖")
+            shutil.rmtree(draft_path)
+
+        # 创建草稿文件夹
+        os.makedirs(draft_path)
+        shutil.copy(assets.get_asset_path("DRAFT_META_TEMPLATE"), os.path.join(draft_path, "draft_meta_info.json"))
+
+        # 创建草稿文件
+        script_file = ScriptFile(width, height, fps)
+        script_file.save_path = os.path.join(draft_path, "draft_content.json")
+
+        return script_file
+
+    def inspect_material(self, draft_name: str) -> None:
+        """输出指定名称草稿中的贴纸素材元数据
+
+        Args:
+            draft_name (`str`): 草稿名称, 即相应文件夹名称
+
+        Raises:
+            `FileNotFoundError`: 对应的草稿不存在
+        """
+        draft_path = os.path.join(self.folder_path, draft_name)
+        if not os.path.exists(draft_path):
+            raise FileNotFoundError(f"草稿文件夹 {draft_name} 不存在")
+
+        script_file = self.load_template(draft_name)
+        script_file.inspect_material()
+
+    def load_template(self, draft_name: str) -> ScriptFile:
+        """在文件夹中打开一个草稿作为模板, 并在其上进行编辑
+
+        Args:
+            draft_name (`str`): 草稿名称, 即相应文件夹名称
+
+        Returns:
+            `ScriptFile`: 以模板模式打开的草稿对象
+
+        Raises:
+            `FileNotFoundError`: 对应的草稿不存在
+        """
+        draft_path = os.path.join(self.folder_path, draft_name)
+        if not os.path.exists(draft_path):
+            raise FileNotFoundError(f"草稿文件夹 {draft_name} 不存在")
+
+        return ScriptFile.load_template(os.path.join(draft_path, "draft_content.json"))
+
+    def duplicate_as_template(self, template_name: str, new_draft_name: str, allow_replace: bool = False) -> ScriptFile:
+        """复制一份给定的草稿, 并在复制出的新草稿上进行编辑
+
+        Args:
+            template_name (`str`): 原草稿名称
+            new_draft_name (`str`): 新草稿名称
+            allow_replace (`bool`, optional): 是否允许覆盖与`new_draft_name`重名的草稿. 默认为否.
+
+        Returns:
+            `ScriptFile`: 以模板模式打开的**复制后的**草稿对象
+
+        Raises:
+            `FileNotFoundError`: 原始草稿不存在
+            `FileExistsError`: 已存在与`new_draft_name`重名的草稿, 但不允许覆盖.
+        """
+        template_path = os.path.join(self.folder_path, template_name)
+        new_draft_path = os.path.join(self.folder_path, new_draft_name)
+        if not os.path.exists(template_path):
+            raise FileNotFoundError(f"模板草稿 {template_name} 不存在")
+        if os.path.exists(new_draft_path) and not allow_replace:
+            raise FileExistsError(f"新草稿 {new_draft_name} 已存在且不允许覆盖")
+
+        # 复制草稿文件夹
+        shutil.copytree(template_path, new_draft_path, dirs_exist_ok=allow_replace)
+
+        # 打开草稿
+        return self.load_template(new_draft_name)

pyJianYingDraft/effect_segment.py

@@ -0,0 +1,36 @@
+"""定义特效/滤镜片段类"""
+
+from typing import Union, Optional, List
+
+from .time_util import Timerange
+from .segment import BaseSegment
+from .video_segment import VideoEffect, Filter
+
+from .metadata import VideoSceneEffectType, VideoCharacterEffectType, FilterType
+
+class EffectSegment(BaseSegment):
+    """放置在独立特效轨道上的特效片段"""
+
+    effect_inst: VideoEffect
+    """相应的特效素材
+
+    在放入轨道时自动添加到素材列表中
+    """
+
+    def __init__(self, effect_type: Union[VideoSceneEffectType, VideoCharacterEffectType],
+                 target_timerange: Timerange, params: Optional[List[Optional[float]]] = None):
+        self.effect_inst = VideoEffect(effect_type, params, apply_target_type=2)  # 作用域为全局
+        super().__init__(self.effect_inst.global_id, target_timerange)
+
+class FilterSegment(BaseSegment):
+    """放置在独立滤镜轨道上的滤镜片段"""
+
+    material: Filter
+    """相应的滤镜素材
+
+    在放入轨道时自动添加到素材列表中
+    """
+
+    def __init__(self, meta: FilterType, target_timerange: Timerange, intensity: float):
+        self.material = Filter(meta.value, intensity)
+        super().__init__(self.material.global_id, target_timerange)

pyJianYingDraft/exceptions.py

@@ -0,0 +1,23 @@
+"""自定义异常类"""
+
+class TrackNotFound(NameError):
+    """未找到满足条件的轨道"""
+class AmbiguousTrack(ValueError):
+    """找到多个满足条件的轨道"""
+class SegmentOverlap(ValueError):
+    """新片段与已有的轨道片段重叠"""
+
+class MaterialNotFound(NameError):
+    """未找到满足条件的素材"""
+class AmbiguousMaterial(ValueError):
+    """找到多个满足条件的素材"""
+
+class ExtensionFailed(ValueError):
+    """替换素材时延伸片段失败"""
+
+class DraftNotFound(NameError):
+    """未找到草稿"""
+class AutomationError(Exception):
+    """自动化操作失败"""
+class ExportTimeout(Exception):
+    """导出超时"""