animation.py

定义视频/文本动画相关类

1. 基础类 - Animation

功能: 定义动画效果的基础类,包含所有动画共有的属性和方法
主要属性:

  • name: 动画名称
  • effect_id: 剪映提供的动画ID
  • animation_type: 动画类型(in/out/group/loop)
  • resource_id: 资源ID
  • start: 动画开始时间(微秒)
  • duration: 动画持续时间(微秒)
  • is_video_animation: 是否为视频动画

主要方法:

  • __init__: 初始化动画,需要提供 animation_meta、start 和 duration
  • export_json: 导出动画为JSON格式

2. 视频动画类 - Video_animation

功能: 专门用于视频动画效果
动画类型:

  • 入场动画(in)
  • 出场动画(out)
  • 组合动画(group)

使用方法:

1
2
3
4
5
video_anim = Video_animation(
    animation_type=Intro_type.某个入场动画,  # 或 Outro_type/Group_animation_type
    start=0,  # 开始时间
    duration=1000000  # 持续时间(微秒)
)

3. 文本动画类 - Text_animation

功能: 专门用于文本动画效果
动画类型:

  • 入场动画(in)
  • 出场动画(out)
  • 循环动画(loop)

使用方法:

1
2
3
4
5
text_anim = Text_animation(
    animation_type=Text_intro.某个入场动画,  # 或 Text_outro/Text_loop_anim
    start=0,
    duration=1000000
)

4. 动画组类 - Segment_animations

功能: 管理附加在素材上的一系列动画
主要特性:

  • 自动生成唯一animation_id
  • 管理多个动画
  • 确保动画组合的合法性

主要方法:

  1. get_animation_trange: 获取指定类型动画的时间范围
  2. add_animation: 添加新动画(有多项限制规则)
  3. export_json: 导出整个动画组为JSON格式

使用限制:

  • 不能添加重复类型的动画
  • 组合动画不能与入场/出场动画共存
  • 循环动画需要在入场/出场动画之后添加

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
# 创建动画组
animations = Segment_animations()

# 添加文本入场动画
text_in = Text_animation(Text_intro.某个入场动画, start=0, duration=1000000)
animations.add_animation(text_in)

# 添加文本出场动画
text_out = Text_animation(Text_outro.某个出场动画, start=2000000, duration=1000000)
animations.add_animation(text_out)

# 导出JSON
json_data = animations.export_json()

注意事项:

  1. 时间单位统一使用微秒
  2. 视频动画和文本动画不能混用
  3. 添加动画时需要遵循特定的顺序和规则
  4. 动画类型之间有严格的互斥关系

这个模块主要用于创建和管理剪映中的动画效果，可以用于视频剪辑项目中添加各种动画效果。通过合理组合不同类型的动画，可以实现丰富的视觉效果。

audio_segment.py

定义音频片段及其相关类

1. 音频淡入淡出效果类 - Audio_fade

功能: 控制音频的淡入淡出效果
主要属性:

  • fade_id: 自动生成的唯一标识符
  • in_duration: 淡入时长(微秒)
  • out_duration: 淡出时长(微秒)

使用示例:

1
2
3
4
fade = Audio_fade(
    in_duration=1000000,  # 1秒淡入
    out_duration=2000000  # 2秒淡出
)

2. 音频特效类 - Audio_effect

功能: 管理音频特效
特效类型:

  • 场景音(sound_effect)
  • 音色(tone)
  • 声音成曲(speech_to_song)

主要属性:

  • name: 特效名称
  • effect_id: 自动生成的特效ID
  • resource_id: 剪映提供的资源ID
  • audio_adjust_params: 特效参数列表

使用示例:

1
2
3
4
effect = Audio_effect(
    effect_meta=Audio_scene_effect_type.某个场景音效果,
    params=[50, 80]  # 参数范围0-100
)

3. 音频片段类 - Audio_segment

功能: 管理轨道上的音频片段，继承自Media_segment
主要属性:

  • material_instance: 音频素材实例
  • fade: 淡入淡出效果
  • effects: 音频特效列表

主要方法:

  1. 初始化方法:
1
2
3
4
5
6
7
audio_seg = Audio_segment(
    material=音频素材,
    target_timerange=目标时间范围,
    source_timerange=源素材时间范围,  # 可选
    speed=播放速度,  # 可选，默认1.0
    volume=音量  # 可选，默认1.0
)
  1. 添加特效:
1
2
3
4
audio_seg.add_effect(
    effect_type=Audio_scene_effect_type.某个效果,
    params=[50, 80]  # 可选，参数列表
)
  1. 添加淡入淡出:
1
2
3
4
audio_seg.add_fade(
    in_duration="1s",  # 支持字符串时间格式
    out_duration=2000000  # 或直接使用微秒数
)
  1. 添加音量关键帧:
1
2
3
4
audio_seg.add_keyframe(
    time_offset=1000000,  # 时间偏移(微秒)
    volume=0.8  # 目标音量
)

使用限制和注意事项:

  1. 时间处理:

    • 所有时间单位统一使用微秒
    • 支持字符串格式的时间输入(如"1s", “500ms”)

  2. 特效限制:

    • 每种类型的特效只能添加一个
    • 特效参数值范围为0-100
    • "声音成曲"效果目前不能被剪映自动识别

  3. 淡入淡出限制:

    • 每个片段只能添加一个淡入淡出效果
    • 可以同时设置淡入和淡出时长

  4. 音量控制:

    • 通过关键帧可以实现音量的动态变化
    • 可以添加多个音量关键帧实现复杂的音量变化效果

实际应用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 创建一个音频片段
audio_segment = Audio_segment(
    material=audio_material,
    target_timerange=Timerange(0, 10000000),  # 10秒片段
    volume=0.8  # 初始音量0.8
)

# 添加淡入淡出
audio_segment.add_fade(
    in_duration="1s",
    out_duration="2s"
)

# 添加场景音效果
audio_segment.add_effect(
    Audio_scene_effect_type.回声,
    params=[70]  # 回声强度70%
)

# 添加音量关键帧
audio_segment.add_keyframe(2000000, 1.0)  # 2秒处音量升至1.0
audio_segment.add_keyframe(8000000, 0.5)  # 8秒处音量降至0.5

这个模块主要用于处理剪映项目中的音频片段，可以实现音频的剪辑、特效添加、淡入淡出以及音量调节等功能。通过合理组合这些功能，可以实现复杂的音频处理效果。

Draft_folder.py

草稿文件夹管理器

Draft_folder 类

功能: 管理剪映草稿文件夹，提供草稿的基本操作功能
主要属性:

  • folder_path: 草稿文件夹的根路径

主要方法:

  1. 初始化方法:
1
2
3
draft_folder = Draft_folder(
    folder_path="D:/剪映草稿/Draft"  # 剪映草稿文件夹路径
)
  1. 列出所有草稿
1
drafts = draft_folder.list_drafts()  # 返回草稿名称列表

特点:

  • 只列出文件夹名称
  • 不检查文件夹是否为有效草稿
  1. 删除草稿 :
1
draft_folder.remove("草稿名称")

特点:

  • 完全删除草稿文件夹
  • 如果草稿不存在会抛出异常
  1. 检查素材 :
1
draft_folder.inspect_material("草稿名称")

特点:

  • 输出草稿中的贴纸素材元数据
  • 通过加载模板实现检查
  1. 加载模板:
1
script = draft_folder.load_template("草稿名称")

特点:

  • 以模板模式打开草稿
  • 返回 Script_file 对象供编辑
  1. 复制草稿 :
1
2
3
4
5
new_script = draft_folder.duplicate_as_template(
    template_name="原草稿名称",
    new_draft_name="新草稿名称",
    allow_replace=False  # 是否允许覆盖已存在的草稿
)

特点:

  • 复制现有草稿作为模板
  • 可选择是否覆盖同名草稿
  • 返回新草稿的 Script_file 对象

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 初始化草稿管理器
draft_folder = Draft_folder("D:/剪映草稿/Draft")

# 列出所有草稿
all_drafts = draft_folder.list_drafts()
print("现有草稿:", all_drafts)

# 复制草稿
new_script = draft_folder.duplicate_as_template(
    "模板草稿",
    "新草稿",
    allow_replace=True
)

# 检查新草稿的素材
draft_folder.inspect_material("新草稿")

# 删除不需要的草稿
draft_folder.remove("旧草稿")

注意事项:

  1. 路径处理:

    • 使用 os.path.join 确保跨平台兼容性
    • 所有路径操作都会检查文件/文件夹是否存在

  2. 异常处理:

    • FileNotFoundError: 操作不存在的草稿时抛出
    • FileExistsError: 复制草稿时遇到同名文件夹且不允许覆盖时抛出

  3. 模板模式:

    • 所有编辑操作都基于模板模式
    • 通过 Script_file 类处理具体的草稿内容

  4. 文件夹结构:

    • 每个草稿都是一个独立的文件夹
    • 草稿内容存储在 draft_content.json 文件中

这个模块主要用于管理剪映的草稿文件夹，提供了草稿的基本操作功能，包括列表、复制、删除等。它是连接文件系统和草稿内容编辑的桥梁，通过与 Script_file 类的配合，实现了完整的草稿管理功能。

effect_segment.py

定义特效/滤镜片段类

1. 特效片段类 - Effect_segment

功能: 管理放置在独立特效轨道上的特效片段，继承自 Base_segment
主要属性:

  • effect_inst: Video_effect 类型的特效实例

使用方法:

1
2
3
4
5
effect_seg = Effect_segment(
    effect_type=Video_scene_effect_type.某个场景特效,  # 或 Video_character_effect_type
    target_timerange=Timerange(0, 1000000),  # 特效作用时间范围
    params=[50, 80]  # 可选，特效参数列表
)

特点:

  • 支持场景特效和人物特效两种类型
  • 特效作用域为全局(apply_target_type=2)
  • 自动管理特效素材的添加

2. 滤镜片段类 - Filter_segment

功能: 管理放置在独立滤镜轨道上的滤镜片段，继承自 Base_segment
主要属性:

  • material: Filter 类型的滤镜实例

使用方法:

1
2
3
4
5
filter_seg = Filter_segment(
    meta=Filter_type.某个滤镜,  # 滤镜类型
    target_timerange=Timerange(0, 1000000),  # 滤镜作用时间范围
    intensity=0.5  # 滤镜强度(0~1)
)

特点:

  • 可以控制滤镜强度
  • 自动管理滤镜素材的添加

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 创建一个场景特效片段
scene_effect = Effect_segment(
    Video_scene_effect_type.模糊,
    Timerange(0, 2000000),  # 2秒
    params=[70]  # 模糊程度70%
)

# 创建一个人物特效片段
character_effect = Effect_segment(
    Video_character_effect_type.美颜,
    Timerange(2000000, 3000000),  # 3秒
    params=[50, 60]  # 美颜相关参数
)

# 创建一个滤镜片段
filter_seg = Filter_segment(
    Filter_type.怀旧,
    Timerange(0, 5000000),  # 5秒
    intensity=0.8  # 80%强度
)

注意事项:

  1. 继承关系:

    • 两个类都继承自 Base_segment
    • 继承了基础的时间范围管理功能

  2. 素材管理:

    • 特效和滤镜实例会在片段放入轨道时自动添加到素材列表
    • 使用全局唯一ID管理素材引用

  3. 参数设置:

    • 特效可以设置多个参数
    • 滤镜只能设置强度一个参数

  4. 时间处理:

    • 时间单位统一使用微秒
    • 通过 Timerange 类管理时间范围

这个模块主要用于管理剪映项目中的特效和滤镜片段，它们都是放置在独立的轨道上的。通过这两个类，可以实现视频特效和滤镜的添加、时间控制和参数调节等功能。

exceptions.py

自定义异常类

1. 轨道相关异常

  1. 轨道未找到
  • 继承自: NameError
  • 使用场景: 当查找特定轨道但未找到时抛出
1
raise TrackNotFound("未找到视频轨道1")
  1. 轨道不唯一
  • 继承自: ValueError
  • 使用场景: 当查找轨道时找到多个匹配项
1
raise AmbiguousTrack("找到多个名为'视频轨道'的轨道")
  1. 片段重叠
  • 继承自: ValueError
  • 使用场景: 当向轨道添加的新片段与现有片段时间重叠
1
raise SegmentOverlap("新片段与轨道上已有片段时间重叠")

2. 素材相关异常

  1. 素材未找到
  • 继承自: NameError
  • 使用场景: 当查找特定素材但未找到时抛出
1
raise MaterialNotFound("未找到名为'背景音乐'的素材")
  1. 素材不唯一
  • 继承自: ValueError
  • 使用场景: 当查找素材时找到多个匹配项
1
raise AmbiguousMaterial("找到多个名为'标题'的素材")
  1. 延伸失败
  • 继承自: ValueError
  • 使用场景: 当替换素材并需要延伸片段时失败
1
raise ExtensionFailed("新素材时长不足，无法延伸片段")

3. 草稿和操作相关异常

  1. 草稿未找到
  • 继承自: NameError
  • 使用场景: 当操作不存在的草稿时抛出
1
raise DraftNotFound("未找到草稿'项目1'")
  1. 自动化错误
  • 继承自: Exception
  • 使用场景: 当自动化操作失败时抛出
1
raise AutomationError("自动导出操作失败")
  1. 导出超时
  • 继承自: Exception
  • 使用场景: 当导出操作超时时抛出
1
raise ExportTimeout("导出操作超过预设时间限制")

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
try:
    # 尝试查找轨道
    track = script.find_track("视频轨道1")
except TrackNotFound:
    print("轨道不存在")
except AmbiguousTrack:
    print("存在多个同名轨道")

try:
    # 尝试添加片段
    track.add_segment(new_segment)
except SegmentOverlap:
    print("片段时间冲突")

try:
    # 尝试查找素材
    material = script.find_material("背景音乐")
except MaterialNotFound:
    print("素材不存在")
except AmbiguousMaterial:
    print("存在多个同名素材")

这些异常类的设计使得程序可以更好地处理各种错误情况，提供了清晰的错误类型区分和具体的错误信息。在使用时，可以根据具体的错误类型进行相应的异常处理。

jianying_controller.py

剪映自动化控制，主要与自动导出有关

1. 枚举类定义

  1. 导出分辨率
1
2
3
4
5
6
7
# 支持的分辨率选项
Export_resolution.RES_8K     # 8K
Export_resolution.RES_4K     # 4K
Export_resolution.RES_2K     # 2K
Export_resolution.RES_1080P  # 1080P
Export_resolution.RES_720P   # 720P
Export_resolution.RES_480P   # 480P
  1. 导出帧率
1
2
3
4
5
6
# 支持的帧率选项
Export_framerate.FR_24  # 24fps
Export_framerate.FR_25  # 25fps
Export_framerate.FR_30  # 30fps
Export_framerate.FR_50  # 50fps
Export_framerate.FR_60  # 60fps

2. 控件查找器 - ControlFinder

功能: 封装UI自动化控件查找逻辑
主要方法:

  1. desc_matcher: 根据控件描述查找
  2. class_name_matcher: 根据类名查找

3. 剪映控制器 - Jianying_controller

主要功能: 自动化控制剪映软件，特别是导出功能

主要方法:

  1. 导出草稿:
1
2
3
4
5
6
7
8
controller = Jianying_controller()
controller.export_draft(
    draft_name="我的视频",  # 草稿名称
    output_path="D:/输出/视频.mp4",  # 可选，输出路径
    resolution=Export_resolution.RES_1080P,  # 可选，导出分辨率
    framerate=Export_framerate.FR_60,  # 可选，导出帧率
    timeout=1800  # 可选，超时时间(秒)
)
  1. 切换到主页 :
1
controller.switch_to_home()  # 从编辑页面返回主页
  1. 获取窗口 :
1
controller.get_window()  # 查找并激活剪映窗口

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 初始化控制器
controller = Jianying_controller()

# 导出1080P 60fps的视频
controller.export_draft(
    "我的视频",
    "D:/输出/成品.mp4",
    resolution=Export_resolution.RES_1080P,
    framerate=Export_framerate.FR_60
)

# 导出4K视频（使用默认帧率）
controller.export_draft(
    "另一个视频",
    "D:/输出/4K版本.mp4",
    resolution=Export_resolution.RES_4K
)

注意事项:

  1. 版本兼容性:

    • 仅支持剪映6及以下版本
    • 更高版本可能需要适配新的UI结构

  2. 权限要求:

    • 需要确保有导出权限
    • 使用VIP功能时需要已开通VIP

  3. 操作限制:

    • 初始化时需要在剪映主页
    • 只支持从编辑页面返回主页

  4. 超时处理:

    • 默认导出超时时间为20分钟
    • 可以通过timeout参数调整

  5. UI自动化:

    • 使用uiautomation库实现
    • 操作过程中不要干扰剪映窗口
    • 所有点击操作都禁用了鼠标移动模拟

这个模块主要用于自动化剪映的导出功能，可以批量导出不同配置的视频，节省手动操作时间。通过UI自动化技术，模拟用户操作完成导出过程。

keyframe.py

管理剪映中的动画效果

1. 关键帧类 - Keyframe

功能: 定义单个关键帧的属性和行为
主要属性:

  • kf_id: 自动生成的唯一标识符
  • time_offset: 相对素材起始点的时间偏移(微秒)
  • values: 关键帧的值列表(通常只有一个值)

使用示例:

1
2
3
4
keyframe = Keyframe(
    time_offset=1000000,  # 1秒
    value=0.5  # 关键帧值
)

2. 关键帧属性枚举 - Keyframe_property

功能: 定义可以使用关键帧控制的属性类型

主要属性类型:

  1. 位置控制:
  • position_x: X轴位置(右移为正)
  • position_y: Y轴位置(上移为正)
  • rotation: 旋转角度(顺时针为正)
  1. 缩放控制:
  • scale_x: X轴缩放比例
  • scale_y: Y轴缩放比例
  • uniform_scale: 统一缩放比例
  1. 视觉效果:
  • alpha: 不透明度(0~1)
  • saturation: 饱和度(-1~1)
  • contrast: 对比度(-1~1)
  • brightness: 亮度(-1~1)
  1. 音频控制:
  • volume: 音量(1.0为原始音量)

3. 关键帧列表类 - Keyframe_list

功能: 管理同一属性的多个关键帧
主要属性:

  • list_id: 自动生成的唯一标识符
  • keyframe_property: 关键帧控制的属性类型
  • keyframes: 关键帧列表

主要方法:

  1. add_keyframe: 添加新关键帧
  2. export_json: 导出为JSON格式

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
# 创建音量关键帧列表
volume_keyframes = Keyframe_list(Keyframe_property.volume)

# 添加关键帧
volume_keyframes.add_keyframe(0, 1.0)         # 开始时原始音量
volume_keyframes.add_keyframe(1000000, 0.5)   # 1秒处降至一半
volume_keyframes.add_keyframe(2000000, 0.0)   # 2秒处静音

# 创建位置动画
position_keyframes = Keyframe_list(Keyframe_property.position_x)
position_keyframes.add_keyframe(0, 0.0)       # 开始时居中
position_keyframes.add_keyframe(1000000, 0.5)  # 1秒处向右移动到一半位置

注意事项:

  1. 时间处理:

    • 时间单位统一使用微秒
    • 关键帧按时间自动排序

  2. 属性限制:

    • 某些属性只对特定类型的片段有效
    • 缩放属性中统一缩放和单轴缩放互斥

  3. 值范围:

    • 不同属性有不同的值范围
    • 需要注意单位和坐标系统

  4. 插值方式:

    • 目前只支持线性插值
    • 关键帧之间的值自动计算

这个模块主要用于管理剪映中的动画效果，通过关键帧可以实现视频片段的移动、缩放、旋转等动画效果，以及音频的淡入淡出等效果。每个关键帧列表控制一个特定的属性，通过添加多个关键帧可以创建复杂的动画效果。

local_materials.py

管理剪映项目中使用的本地素材

1. 裁剪设置类 - Crop_settings

功能: 定义素材的裁剪区域
主要属性:

  • 四个角的坐标(x,y)，范围均为0-1
  • 坐标原点在左上角

使用示例:

1
2
3
4
5
6
crop = Crop_settings(
    upper_left_x=0.1, upper_left_y=0.1,    # 左上角
    upper_right_x=0.9, upper_right_y=0.1,  # 右上角
    lower_left_x=0.1, lower_left_y=0.9,    # 左下角
    lower_right_x=0.9, lower_right_y=0.9   # 右下角
)

2. 视频素材类 - Video_material

功能: 管理视频或图片素材
主要属性:

  • material_id: 自动生成的唯一标识符
  • material_name: 素材名称
  • path: 素材文件路径
  • duration: 素材时长(微秒)
  • height/width: 素材尺寸
  • crop_settings: 裁剪设置
  • material_type: “video"或"photo”

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 加载视频
video = Video_material(
    path="D:/videos/sample.mp4",
    material_name="示例视频",  # 可选
    crop_settings=Crop_settings()  # 可选
)

# 加载图片
image = Video_material(
    path="D:/images/photo.jpg"
    # 图片会被设置为3小时长度
)

# 加载GIF
gif = Video_material(
    path="D:/images/animation.gif"
    # GIF会被当作视频处理
)

3. 音频素材类 - Audio_material

功能: 管理音频素材
主要属性:

  • material_id: 自动生成的唯一标识符
  • material_name: 素材名称
  • path: 素材文件路径
  • duration: 音频时长(微秒)

使用示例:

1
2
3
4
5
# 加载音频文件
audio = Audio_material(
    path="D:/music/bgm.mp3",
    material_name="背景音乐"  # 可选
)

注意事项:

  1. 素材类型限制:

    • 视频素材支持常见视频格式(mp4/mov/avi等)和图片格式(jpg/png等)
    • 音频素材支持常见音频格式(mp3/wav等)
    • 音频素材不能包含视频轨道

  2. 素材ID生成:

    • 使用UUID3基于素材名称生成
    • 同名素材会得到相同的ID

  3. 时长处理:

    • 视频/音频：使用实际时长
    • 图片：默认3小时(10800000000微秒)
    • GIF：计算实际播放时长

  4. 素材解析:

    • 使用pymediainfo库解析媒体信息
    • GIF额外使用imageio库解析

  5. 导出格式:

    • 两种素材类型有不同的JSON导出格式
    • 包含剪映所需的所有元数据

使用场景:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 创建带裁剪的视频素材
crop = Crop_settings(
    upper_left_x=0.1, upper_left_y=0.1,
    upper_right_x=0.9, upper_right_y=0.1,
    lower_left_x=0.1, lower_left_y=0.9,
    lower_right_x=0.9, lower_right_y=0.9
)

video = Video_material(
    "D:/videos/source.mp4",
    "裁剪后的视频",
    crop
)

# 创建音频素材
bgm = Audio_material(
    "D:/music/background.mp3",
    "背景音乐"
)

# 导出为剪映格式
video_json = video.export_json()
audio_json = bgm.export_json()

这个模块主要用于管理剪映项目中使用的本地素材，包括视频、图片和音频。它提供了素材的加载、裁剪和导出功能，是连接本地文件系统和剪映项目的重要桥梁。

script_file.py

完整的剪映草稿文件管理功能，可以实现视频剪辑、特效添加、字幕导入等

1. 素材管理类 - Script_material

功能: 管理草稿中的所有素材
主要属性:

  • 媒体素材: audios, videos, stickers, texts
  • 效果素材: audio_effects, audio_fades, animations, video_effects
  • 其他素材: speeds, masks, transitions, filters

2. 草稿文件类 - Script_file

主要功能:

  1. 基础属性管理:
1
2
3
4
5
script = Script_file(
    width=1920,    # 视频宽度
    height=1080,   # 视频高度
    fps=30         # 帧率
)
  1. 轨道管理:
1
2
3
4
5
6
7
# 添加轨道
script.add_track(
    Track_type.video,      # 轨道类型
    "主视频轨道",          # 轨道名称
    mute=False,           # 是否静音
    relative_index=0      # 相对层级
)
  1. 片段管理:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 添加视频片段
script.add_segment(
    video_segment,        # 视频片段
    "主视频轨道"          # 轨道名称
)

# 添加特效
script.add_effect(
    Video_scene_effect_type.模糊,  # 特效类型
    Timerange(0, 1000000),        # 时间范围
    params=[50]                    # 特效参数
)

# 添加滤镜
script.add_filter(
    Filter_type.怀旧,             # 滤镜类型
    Timerange(0, 1000000),       # 时间范围
    intensity=80                  # 强度
)
  1. 字幕导入:
1
2
3
4
5
6
script.import_srt(
    "字幕.srt",           # SRT文件路径
    "字幕轨道",           # 轨道名称
    time_offset="1s",     # 时间偏移
    text_style=Text_style(size=5)  # 文字样式
)
  1. 素材替换:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 按名称替换
script.replace_material_by_name(
    "原视频",             # 原素材名称
    new_video_material    # 新素材
)

# 按片段替换
script.replace_material_by_seg(
    video_track,          # 视频轨道
    0,                    # 片段索引
    new_video_material    # 新素材
)

# 替换文本
script.replace_text(
    text_track,           # 文本轨道
    0,                    # 片段索引
    "新文本内容"          # 新文本
)
  1. 导出功能:
1
2
3
4
5
6
7
8
# 导出为JSON字符串
json_str = script.dumps()

# 保存到文件
script.dump("draft_content.json")

# 在模板模式下保存
script.save()

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 创建新草稿
script = Script_file(1920, 1080, 30)

# 添加主视频轨道
script.add_track(Track_type.video, "主视频")

# 添加视频片段
video_material = Video_material("video.mp4")
video_segment = Video_segment(video_material, Timerange(0, 5000000))
script.add_segment(video_segment, "主视频")

# 添加字幕轨道并导入SRT
script.add_track(Track_type.text, "字幕")
script.import_srt("subtitle.srt", "字幕")

# 添加特效轨道和特效
script.add_track(Track_type.effect, "特效")
script.add_effect(
    Video_scene_effect_type.模糊,
    Timerange(1000000, 2000000),  # 1-3秒
    params=[70]  # 模糊程度70%
)

# 保存草稿
script.dump("draft.json")

注意事项:

  1. 轨道管理:

    • 主视频轨道的片段必须从0秒开始
    • 同类型轨道需要指定不同名称
    • 轨道层级影响最终效果

  2. 素材管理:

    • 素材会自动添加到素材列表
    • 支持素材的替换和修改
    • 素材ID自动生成和管理

  3. 时间处理:

    • 统一使用微秒作为时间单位
    • 支持多种时间格式输入

  4. 模板功能:

    • 支持从模板创建草稿
    • 支持保存为模板
    • 支持素材和文本的替换

这个模块提供了完整的剪映草稿文件管理功能，可以实现视频剪辑、特效添加、字幕导入等各种操作，是整个项目的核心组件。

segment.py

定义片段基类及部分比较通用的属性类

1. 基础片段类 - Base_segment

功能: 所有片段类型的基类
主要属性:

  • segment_id: 自动生成的唯一标识符
  • material_id: 使用的素材ID
  • target_timerange: 片段在轨道上的时间范围
  • common_keyframes: 关键帧列表

主要方法:

1
2
3
4
5
6
7
# 时间属性访问
segment.start      # 开始时间
segment.duration   # 持续时间
segment.end        # 结束时间

# 判断重叠
segment.overlaps(other_segment)

2. 速度控制类 - Speed

功能: 控制片段的播放速度

1
speed = Speed(2.0)  # 2倍速播放

3. 图像调节设置类 - Clip_settings

功能: 控制视觉片段的图像属性
主要属性:

  • 透明度: alpha (0-1)
  • 翻转: flip_horizontal, flip_vertical
  • 旋转: rotation (角度)
  • 缩放: scale_x, scale_y
  • 位移: transform_x, transform_y

使用示例:

1
2
3
4
5
6
settings = Clip_settings(
    alpha=0.8,           # 80%不透明度
    rotation=45.0,       # 顺时针旋转45度
    scale_x=1.5,        # 水平放大1.5倍
    transform_x=0.5     # 向右移动半个画布宽度
)

4. 媒体片段基类 - Media_segment

功能: 音视频片段的基类
主要属性:

  • source_timerange: 素材截取范围
  • speed: 播放速度
  • volume: 音量
  • extra_material_refs: 附加素材引用

5. 视觉片段基类 - Visual_segment

功能: 所有可见片段的基类(视频、贴纸、文本)
主要特性:

  • 支持图像调节设置
  • 支持关键帧动画
  • 支持统一缩放控制

关键帧添加示例:

1
2
3
4
5
6
7
8
9
segment.add_keyframe(
    Keyframe_property.alpha,    # 控制透明度
    "1s",                      # 在1秒处
    0.5                        # 设置为50%透明
)

# 缩放动画
segment.add_keyframe(Keyframe_property.uniform_scale, "0s", 1.0)  # 开始正常大小
segment.add_keyframe(Keyframe_property.uniform_scale, "2s", 2.0)  # 2秒处放大2倍

继承关系:

1
2
3
4
5
6
Base_segment
    └── Media_segment
        └── Visual_segment
            ├── Video_segment
            ├── Sticker_segment
            └── Text_segment

注意事项:

  1. 时间处理:

    • 统一使用微秒作为时间单位
    • 支持字符串形式的时间输入(如"1s", “500ms”)

  2. 缩放控制:

    • uniform_scale和单独的scale_x/y互斥
    • 设置单轴缩放会自动关闭统一缩放

  3. 关键帧动画:

    • 支持多种属性的关键帧控制
    • 关键帧效果会覆盖静态设置

  4. ID管理:

    • 片段ID和速度ID都自动生成
    • 使用UUID确保唯一性

这个模块是整个项目的基础，定义了各种片段的共同属性和行为，为视频编辑提供了统一的接口和数据结构。

template_mode.py

与模板模式相关的类及函数等

1. 素材处理模式枚举

  1. 缩短处理模式
1
2
3
4
5
# 四种处理方式
Shrink_mode.cut_head        # 裁剪头部
Shrink_mode.cut_tail        # 裁剪尾部
Shrink_mode.cut_tail_align  # 裁剪尾部并对齐后续片段
Shrink_mode.shrink         # 两端向中间收缩
  1. **延长处理模式 **
1
2
3
4
5
# 四种处理方式
Extend_mode.cut_material_tail  # 裁剪素材尾部
Extend_mode.extend_head       # 向前延伸
Extend_mode.extend_tail       # 向后延伸
Extend_mode.push_tail         # 向后延伸并推动后续片段

2. 导入的片段和轨道类

  1. 媒体片段
1
2
3
segment = Imported_media_segment(json_data)
print(segment.source_timerange)  # 素材时间范围
print(segment.target_timerange)  # 目标时间范围
  1. 基础轨道
1
2
3
track = Imported_track(json_data)
print(track.track_type)    # 轨道类型
print(track.name)          # 轨道名称
  1. **可编辑轨道 **
  • 基类，用于标识可编辑的轨道类型
  1. 文本轨道
1
2
text_track = Imported_text_track(json_data)
print(len(text_track))     # 片段数量
  1. 媒体轨道

主要功能:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
media_track = Imported_media_track(json_data)

# 时间属性
print(media_track.start_time)  # 起始时间
print(media_track.end_time)    # 结束时间

# 素材类型检查
media_track.check_material_type(video_material)  # 检查素材类型是否匹配

# 处理时间范围变更
media_track.process_timerange(
    0,                              # 片段索引
    Timerange(0, 1000000),         # 新的源时间范围
    Shrink_mode.cut_tail,          # 缩短处理方式
    [Extend_mode.extend_tail]      # 延长处理方式列表
)

3. 轨道导入函数

1
2
# 根据JSON数据导入对应类型的轨道
track = import_track(track_json)

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 1. 导入轨道
track = import_track(track_json_data)

# 2. 处理素材替换
if isinstance(track, Imported_media_track):
    # 检查素材类型
    if track.check_material_type(new_material):
        # 处理时间范围变更
        track.process_timerange(
            0,  # 第一个片段
            new_material.duration,
            Shrink_mode.cut_tail_align,  # 缩短时裁剪尾部并对齐
            [
                Extend_mode.extend_tail,  # 先尝试向后延伸
                Extend_mode.push_tail     # 不行就推动后续片段
            ]
        )

# 3. 导出JSON
json_data = track.export_json()

注意事项:

  1. 时间处理:

    • 所有时间单位为微秒
    • 需要考虑片段间的间隙和重叠

  2. 素材替换:

    • 需要先检查素材类型匹配
    • 可以组合多种延长处理方式
    • 某些处理方式可能失败

  3. 轨道类型:

    • 不同类型轨道有不同的处理逻辑
    • 部分轨道类型不允许修改

  4. JSON处理:

    • 保留原始JSON数据
    • 导出时合并修改内容

这个模块主要用于处理剪映模板的导入和编辑，特别是处理素材替换时的各种情况，提供了灵活的时间范围处理方式。

text_segment.py

定义文本片段及其相关类

1. 文本样式类 - Text_style

功能: 控制文本的基本样式

1
2
3
4
5
6
7
8
9
10
style = Text_style(
    size=10.0,                          # 字体大小
    color=(1.0, 0.0, 0.0),             # 红色
    alpha=0.8,                          # 80%不透明度
    bold=True,                          # 加粗
    align=1,                            # 居中对齐
    vertical=True,                      # 竖排文本
    letter_spacing=2,                   # 字间距
    line_spacing=1                      # 行间距
)

2. 文本边框类 - Text_border

功能: 控制文本描边效果

1
2
3
4
5
border = Text_border(
    alpha=0.8,                          # 描边透明度
    color=(0.0, 0.0, 0.0),             # 黑色描边
    width=60.0                          # 描边宽度
)

3. 文本背景类 - Text_background

功能: 控制文本背景效果

1
2
3
4
5
6
7
8
9
10
background = Text_background(
    color="#000000",                    # 黑色背景
    style=1,                            # 背景样式1
    alpha=0.5,                          # 50%透明度
    round_radius=0.2,                   # 圆角半径
    width=0.2,                          # 背景宽度
    height=0.2,                         # 背景高度
    horizontal_offset=0.5,              # 水平居中
    vertical_offset=0.5                 # 垂直居中
)

4. 文本特效类

  1. 气泡效果 TextBubble
  2. 花字效果 TextEffect

5. 文本片段类 - Text_segment

主要功能:

  1. 创建文本片段:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 基本创建
text = Text_segment(
    "Hello World",                      # 文本内容
    Timerange(0, 1000000),             # 时间范围(1秒)
    font=Font_type.黑体,                # 字体
    style=Text_style(size=10.0),        # 样式
    border=Text_border(),               # 描边
    background=Text_background()        # 背景
)

# 从模板创建
new_text = Text_segment.create_from_template(
    "新文本",
    Timerange(0, 1000000),
    template_text
)
  1. 添加动画:
1
2
3
4
5
6
7
8
9
text.add_animation(
    Text_intro.淡入,                    # 入场动画
    "500ms"                            # 持续时间
).add_animation(
    Text_outro.淡出,                    # 出场动画
    "500ms"                            # 持续时间
).add_animation(
    Text_loop_anim.上下浮动             # 循环动画
)
  1. 添加特效:
1
2
3
4
5
# 添加气泡
text.add_bubble("bubble_effect_id", "bubble_resource_id")

# 添加花字
text.add_effect("flower_effect_id")

注意事项:

  1. 动画顺序:

    • 先添加入场/出场动画
    • 再添加循环动画
    • 动画时间不能超过片段时长

  2. 样式优先级:

    • content中的样式优先级最高
    • 背景和描边通过flag控制开启

  3. 特效ID:

    • 需要从模板中获取
    • 使用Script_file.inspect_material查看

  4. 时间处理:

    • 支持字符串时间格式(如"1s", “500ms”)
    • 内部统一使用微秒单位

  5. 字体文件:

    • 不需要实际放置字体文件
    • 仅记录字体信息即可

这个模块提供了完整的文本片段处理功能，可以控制文本的样式、动画和特效，是剪映项目中处理字幕和文本的核心组件。

time_util.py

定义时间范围类以及与时间相关的辅助函数

1. 时间转换函数 - tim

功能: 将各种时间格式转换为微秒

1
2
3
4
5
# 支持多种输入格式
tim("1h30m")          # 1小时30分钟
tim("1.5s")           # 1.5秒
tim("-30s")           # 负30秒
tim(1000000)          # 直接输入微秒数

2. 时间范围类 - Timerange

主要功能:

  1. 基本操作:
1
2
3
4
5
6
7
8
9
10
11
12
# 创建时间范围
tr = Timerange(0, 1000000)  # 从0开始持续1秒

# 获取属性
print(tr.start)      # 开始时间
print(tr.duration)   # 持续时间
print(tr.end)        # 结束时间

# 判断重叠
tr1 = Timerange(0, 1000000)
tr2 = Timerange(500000, 1000000)
print(tr1.overlaps(tr2))  # True
  1. JSON转换:
1
2
3
4
5
6
7
8
9
# 导出JSON
json_data = tr.export_json()
# {'start': 0, 'duration': 1000000}

# 从JSON导入
tr = Timerange.import_json({
    'start': '0',
    'duration': '1000000'
})

3. 便捷构造函数 - trange

功能: Timerange的简便构造方法

1
2
3
# 使用字符串创建时间范围
tr = trange("1m", "30s")     # 从1分钟开始，持续30秒
tr = trange("1.5s", "0.5s")  # 从1.5秒开始，持续0.5秒

4. SRT时间戳解析 - srt_tstamp

功能: 解析SRT字幕文件中的时间戳

1
2
# 解析SRT格式时间戳
time = srt_tstamp("00:01:30,500")  # 1分30秒500毫秒

注意事项:

  1. 时间单位:

    • 内部统一使用微秒
    • 1秒 = 1,000,000微秒
    • 负时间值表示偏移量

  2. 时间格式:

    • 支持小时(h)、分钟(m)、秒(s)
    • 支持小数形式的秒
    • 支持负号表示负偏移

  3. 时间范围:

    • 使用start和duration定义
    • duration通常为正值
    • 可以判断时间范围重叠

  4. SRT格式:

    • 格式为"HH:MM:SS,mmm"
    • 支持毫秒精度

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 创建时间范围
tr1 = trange("1m", "30s")      # 使用便捷函数
tr2 = Timerange(0, 1000000)    # 直接使用微秒

# 2. 检查重叠
if tr1.overlaps(tr2):
    print("时间范围有重叠")

# 3. 处理SRT时间戳
srt_time = srt_tstamp("00:01:30,500")
tr3 = Timerange(srt_time, tim("2s"))

# 4. 导出JSON
json_data = tr3.export_json()

这个模块提供了项目中所有时间相关操作的基础支持，特别是在处理视频片段、字幕时间等场景下非常有用。

track.py

轨道类及其元数据

1. 轨道元数据类 - Track_meta

功能: 定义轨道的基本属性

  • segment_type: 轨道允许的片段类型
  • render_index: 渲染顺序(值越大越靠前)
  • allow_modify: 是否允许修改

2. 轨道类型枚举 - Track_type

支持的轨道类型:

1
2
3
4
5
6
7
8
9
10
# 可编辑轨道
Track_type.video    # 视频轨道 (渲染索引: 0)
Track_type.audio    # 音频轨道 (渲染索引: 0)
Track_type.text     # 文本轨道 (渲染索引: 15000)

# 不可编辑轨道
Track_type.effect   # 特效轨道 (渲染索引: 10000)
Track_type.filter   # 滤镜轨道 (渲染索引: 11000)
Track_type.sticker  # 贴纸轨道 (渲染索引: 14000)
Track_type.adjust   # 调节轨道 (仅用于导入)

3. 基础轨道类 - Base_track

主要属性:

  • track_type: 轨道类型
  • name: 轨道名称
  • track_id: 轨道唯一标识符
  • render_index: 渲染顺序

4. 通用轨道类 - Track

主要功能:

  1. 创建轨道:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 创建视频轨道
video_track = Track(
    Track_type.video,    # 轨道类型
    "主视频",            # 轨道名称
    0,                   # 渲染索引
    False               # 是否静音
)

# 创建文本轨道
text_track = Track(
    Track_type.text,
    "字幕轨道",
    15000,
    False
)
  1. 添加片段:
1
2
3
4
5
# 添加视频片段
video_track.add_segment(video_segment)

# 添加文本片段
text_track.add_segment(text_segment)
  1. 获取轨道信息:
1
2
3
4
5
# 获取结束时间
end_time = track.end_time

# 获取允许的片段类型
segment_type = track.accept_segment_type

注意事项:

  1. 片段类型检查:

    • 每个轨道只接受特定类型的片段
    • 添加不匹配的片段会抛出TypeError

  2. 片段重叠检查:

    • 同一轨道的片段不能重叠
    • 重叠会抛出SegmentOverlap异常

  3. 渲染顺序:

    • 数值越大越靠近前景
    • 文本和贴纸通常在最上层
    • 视频和音频在最下层

  4. 轨道修改限制:

    • 部分轨道类型不允许修改
    • adjust轨道仅用于导入

使用示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1. 创建轨道
video_track = Track(Track_type.video, "主视频", 0, False)
text_track = Track(Track_type.text, "字幕", 15000, False)

# 2. 添加片段
try:
    video_track.add_segment(video_segment)
    text_track.add_segment(text_segment)
except SegmentOverlap as e:
    print("片段重叠:", e)
except TypeError as e:
    print("片段类型不匹配:", e)

# 3. 导出JSON
track_json = video_track.export_json()

这个模块是整个项目的核心组件之一，负责管理不同类型的轨道及其包含的片段，确保片段的正确放置和渲染顺序。

util.py

辅助函数，主要与模板模式有关

1. JSON导出类型定义

1
JsonExportable = Union[int, float, bool, str, List["JsonExportable"], Dict[str, "JsonExportable"]]

定义了可以导出为JSON的数据类型，包括基本类型和嵌套的列表/字典。

2. 构造函数默认值提供器

功能: 为类的构造函数提供默认参数值

1
2
3
# 使用示例
defaults = provide_ctor_defaults(MyClass)
instance = MyClass(**defaults)

支持的类型:

  • int: 默认值为 0
  • float: 默认值为 0
  • str: 默认值为 “”
  • bool: 默认值为 False

3. JSON数据属性赋值器

功能: 从JSON数据中读取并赋值给对象属性

1
2
3
4
5
6
7
8
9
10
# 使用示例
assign_attr_with_json(
    obj=my_object,
    attrs=["name", "age", "settings"],
    json_data={
        "name": "测试",
        "age": 20,
        "settings": {"key": "value"}
    }
)

特点:

  • 自动处理类型转换
  • 支持复杂对象的import_json方法
  • 使用类型注解进行类型检查

4. 对象属性JSON导出器

功能: 将对象属性导出为JSON格式

1
2
3
4
5
# 使用示例
json_data = export_attr_to_json(
    obj=my_object,
    attrs=["name", "age", "settings"]
)

特点:

  • 自动调用对象的export_json方法
  • 处理基本类型直接导出
  • 返回可序列化的字典

使用场景示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 1. 创建对象时提供默认值
class MyClass:
    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age

defaults = provide_ctor_defaults(MyClass)
obj = MyClass(**defaults)  # name="", age=0

# 2. 从JSON导入数据
json_data = {
    "name": "测试",
    "age": 25
}
assign_attr_with_json(obj, ["name", "age"], json_data)

# 3. 导出为JSON
result = export_attr_to_json(obj, ["name", "age"])

注意事项:

  1. 类型支持:

    • 只支持基本类型的默认值生成
    • 复杂类型需要实现import_json/export_json方法

  2. 类型注解:

    • 必须为属性提供类型注解
    • 支持继承类的类型注解

  3. 错误处理:

    • 不支持的类型会抛出ValueError
    • 类型转换失败会抛出相应异常

  4. JSON兼容性:

    • 确保导出的数据是JSON可序列化的
    • 复杂对象需要正确实现序列化方法

这个模块主要用于简化模板模式下的对象序列化和反序列化操作，提供了一套统一的接口来处理对象与JSON数据之间的转换。

video_segment.py

定义视频片段及其相关类

1. 蒙版类 - Mask

功能: 定义视频蒙版效果

1
2
3
4
5
6
7
8
9
10
mask = Mask(
    mask_meta=Mask_type.圆形.value,
    cx=0.5, cy=0.5,           # 中心点位置
    w=0.5, h=0.5,            # 宽高
    ratio=1.0,               # 宽高比
    rot=45,                  # 旋转角度
    inv=False,               # 是否反转
    feather=0.5,            # 羽化程度
    round_corner=0.0         # 圆角(矩形专用)
)

2. 视频特效类 - Video_effect

功能: 定义视频特效

1
2
3
4
5
effect = Video_effect(
    Video_scene_effect_type.模糊,    # 特效类型
    params=[50.0],                   # 特效参数
    apply_target_type=0              # 0:片段, 2:全局
)

3. 滤镜类 - Filter

功能: 定义视频滤镜

1
2
3
4
5
filter = Filter(
    Filter_type.怀旧.value,          # 滤镜类型
    intensity=0.8,                   # 强度(0-1)
    apply_target_type=0              # 0:片段, 2:全局
)

4. 转场类 - Transition

功能: 定义视频转场效果

1
2
3
4
transition = Transition(
    Transition_type.淡入淡出,         # 转场类型
    duration=1000000                 # 持续时间(微秒)
)

5. 视频片段类 - Video_segment

主要功能:

  1. 创建视频片段:
1
2
3
4
5
6
7
segment = Video_segment(
    material=video_material,          # 视频素材
    target_timerange=trange("0s", "5s"),  # 目标时间范围
    source_timerange=trange("1s", "5s"),  # 源素材时间范围
    speed=1.5,                        # 播放速度
    volume=0.8                        # 音量
)
  1. 添加效果:
1
2
3
4
5
segment.add_animation(Intro_type.淡入, "500ms")  # 添加入场动画
segment.add_effect(Video_scene_effect_type.模糊)  # 添加特效
segment.add_filter(Filter_type.怀旧)             # 添加滤镜
segment.add_mask(Mask_type.圆形)                 # 添加蒙版
segment.add_transition(Transition_type.淡入淡出)  # 添加转场

6. 贴纸片段类 - Sticker_segment

功能: 定义贴纸片段

1
2
3
4
sticker = Sticker_segment(
    resource_id="sticker_001",        # 贴纸资源ID
    target_timerange=trange("0s", "5s")  # 显示时间范围
)

注意事项:

  1. 时间处理:

    • 所有时间均使用微秒为单位
    • 支持字符串时间格式(如"1s", “500ms”)

  2. 效果叠加:

    • 一个片段可以添加多个特效和滤镜
    • 蒙版和转场只能添加一个

  3. 参数范围:

    • 滤镜强度: 0-100
    • 蒙版羽化: 0-100
    • 蒙版圆角: 0-100

  4. 素材兼容:

    • 支持视频和图片素材
    • 贴纸使用独立的片段类型

这个模块是整个项目的核心组件之一，提供了丰富的视频编辑功能，包括基本的剪辑、特效、滤镜、转场等，能够满足大多数视频编辑需求。