本项目与 PyJianYingDraft 同源，面向 CapCut 草稿。
⚠️ 0.1.0 版本预告：下一版本将与剪映侧统一轨道排序和引用方式，新增append_track(s)／insert_track(s)及TrackSpec／TrackRef，并删除add_track。依赖旧接口或轨道层级行为的脚本需要迁移，届时将提供迁移指南。需要沿用当前用法的用户可固定安装pip install pycapcut==0.0.4，并查阅该版本的文档和示例。
📢 欢迎加入Discord服务器进行用法或新功能的讨论
生成后请在 CapCut 中打开草稿，并通过应用手动导出视频。目前CapCut版暂不支持自动导出。
✅ 验证版本列为已确认的 CapCut 版本；“—”表示尚未记录版本。
| 功能名称 | 支持状态 | 验证版本 |
|---|---|---|
| 本地视频/图片素材与时间控制 | ✅ | 8.2.0 |
| 视频整体调节 | ✅ | 8.2.0 |
| 视频关键帧 | ✅ | — |
| 视频蒙版 | ✅ | 9.5.0.4050 |
| 视频色度抠图 | ✅ | 9.5.0.4050 |
| 视频混合模式 | ✅ | 9.5.0.4050 |
| 视频背景填充(示例代码) | ✅ | — |
| 带音轨视频的音频淡入淡出 | ✅ | — |
| 带音轨视频变速时改变音调 | ✅ | 9.5.0.4050 |
| 功能名称 | 支持状态 | 验证版本 |
|---|---|---|
| 根据元数据添加贴纸 | ✅ | — |
| 贴纸关键帧 | ✅ | — |
| 功能名称 | 支持状态 | 验证版本 |
|---|---|---|
| 本地音频素材与时间控制 | ✅ | 9.5.0.4050 |
| 音频淡入淡出、音量及关键帧 | ✅ | — |
| 变速时改变音调 | ✅ | 9.5.0.4050 |
| 场景音效果 | ✅ | — |
| 音色效果 | ✅ | 9.5.0.4050（花栗鼠） |
| 功能名称 | 支持状态 | 验证版本 |
|---|---|---|
| 添加轨道与添加片段 | ✅ | 8.2.0 |
| 轨道层级控制 | ✅ | 8.2.0（视频轨道） |
| 主轨磁吸开关 | ✅ | 8.2.0 |
| 功能名称 | 支持状态 | 验证版本 |
|---|---|---|
| 视频片段动画 | ✅ | — |
| 视频片段特效 | ✅ | — |
| 视频片段滤镜 | ✅ | — |
| 独立轨道特效和滤镜 | ✅ | — |
| 转场(示例代码) | ✅ | — |
| 功能名称 | 支持状态 | 验证版本 |
|---|---|---|
| 文本与样式 | ✅ | 8.2.0 |
| 字体 | ✅ | 9.5.0.4050 |
| 文本关键帧 | ✅ | — |
| 文本动画 | ✅ | — |
| 文字描边、背景和阴影 | ✅ | — |
| 文字气泡和花字(示例代码) | ✅ | 9.5.0.4050（花字） |
| 文本自动换行 | ✅ | — |
| 导入 SRT 字幕 | ✅ | — |
| 功能名称 | 支持状态 | 验证版本 |
|---|---|---|
| 加载明文草稿 | ✅ | 8.2.0 |
| 根据名称替换素材 | ✅ | — |
| 根据片段替换素材 | ✅ | — |
| 替换文本内容 | ✅ | — |
| 导入模板轨道 | ✅ | — |
| 提取素材元数据 | ✅ | — |
pyCapCut现已支持pip安装（不含demo）
pip install pycapcut
Windows、Linux 和 macOS 均可安装本库，用于生成和编辑草稿。生成的草稿请在 Windows 版 CapCut 中打开并手动导出视频。
例程demo.py将创建包含音视频素材和一行文本的CapCut草稿文件，并且添加了音频淡入、视频入场动画、转场效果、关键帧和文本气泡/花字。
这个例程的操作方法如下：
- 找到CapCut的草稿文件夹路径（类似
.../CapCut Drafts），用其替换代码中的<你的草稿文件夹> - 运行
demo.py（该例程会覆盖已有的同名demo草稿，运行前请确认无需保留） - 在CapCut中找到并打开新创建的
demo草稿（可能需要进入再退出某个已有草稿，或重启CapCut以刷新草稿列表），你应该看到类似如下的时间轴：
你可以调整素材、时间和效果设置，再次运行例程生成草稿。需要成片时，在 CapCut 中手动导出视频。
ℹ 文档部分推荐从功能清单一节中选取感兴趣的功能阅读，而非直接按顺序阅读
模板必须是可直接读取的明文 draft_content.json，加密或其他不可读格式暂不支持。
为了保留部分复杂特性（文本特效、复合片段...），可以加载一个已有的CapCut草稿作为模板，然后将其中内容导入到另一的草稿中，或直接替换其中部分片段的内容。
目前提供了三种替换功能：
除此之外，对于某些没有特定名称的特性（贴纸、花字等），提供了提取素材元数据的功能以提取其resource_id
ℹ 若出现模板内容丢失的情况，欢迎反馈
推荐使用DraftFolder来管理CapCut的草稿文件夹（可以在CapCut的全局设置-草稿位置中查询），这样能够方便地根据已有模板生成新草稿。
import pycapcut as cc
draft_folder = cc.DraftFolder("<CapCut草稿文件夹>") # 一般形如 ".../CapCut Drafts"
script = draft_folder.duplicate_as_template("模板草稿", "新草稿") # 复制为"新草稿"，返回可编辑的 ScriptFile 对象
# 对返回的ScriptFile对象进行编辑，如替换素材、添加轨道、片段等
script.save() # 保存你的"新草稿"为了最大限度地兼容模板中的复杂特性，导入的轨道与pycapcut创建的轨道是分离开的，具体地讲：
- 除下述替换功能外，不能在导入的轨道上添加片段、转场、淡入淡出、特效等
- 仍然可以创建新的轨道，并在其上添加片段等，就像非模板模式一样
对导入的ScriptFile对象，可以调用inspect_material方法提取部分素材的resource_id。
DraftFolder也有相应的方法来提取指定草稿的素材元数据。
import pycapcut as cc
draft_folder = cc.DraftFolder("<CapCut草稿文件夹>")
draft_folder.inspect_material("草稿名称")
# 或者
script = draft_folder.load_template("草稿名称")
script.inspect_material()上述代码的输出可能类似于
贴纸素材:
Resource id: 7405878923323641129 '秋日手绘-枫叶'
Resource id: 7429353555447893260 '电商购物促销/哇哦'
Resource id: 7437707455267671315 '冬日涂鸦winter雪花冬天vlog装饰文字'
Resource id: 7343931192204463401 '爱心'
文字气泡效果:
Effect id: 763870 ,Resource id: 6838834573413978631 '标题59'
花字效果:
Resource id: 7342020000812731658 '彩色手绘线条花字'
其中的元数据可用于添加相应素材（例如通过StickerSegment的resource_id参数）
这种方法将替换素材本身，而不对片段进行直接修改。
ℹ 由于素材有名称（默认是本地文件的名称），这种替换方式的定位比较方便
ℹ 由于不涉及时间范围的修改，这种替换方式尤其适合图像素材，且几乎不会产生兼容性的问题
以快速上手中的草稿为例，假如我们希望换用新的音频素材，可以：
new_material = cc.AudioMaterial("<新的音频素材路径>")
script.replace_material_by_name("audio.mp3", new_material) # 替换名称为"audio.mp3"的素材替换新素材后，片段所截取的部分仍是素材前5秒，且音量、淡入淡出、播放速度等仍保持不变。
这种方法将替换某个特定片段的素材，同时可以重新选取其引用的素材范围并根据新时长在时间轴上伸缩片段。
ℹ 由于片段没有名称，故通常需要依靠片段的下标来定位
此过程分为两步：选取轨道和替换素材，以上方音频素材的替换为例：
from pycapcut import trange_seconds, ShrinkMode, ExtendMode
audio_track = script.get_imported_track(
cc.TrackType.audio, # 选取导入的音频轨道
#name="audio", # 假如轨道有名称，最好利用名称来定位
index=0 # 也可用下标定位, 0表示最底层的同类型轨道
)
script.replace_material_by_seg(
audio_track, 0, new_material, # 选取audio_track中下标为0的片段，也即第一个片段
#source_timerange=None, # 若不指定，则默认使用整个素材
source_timerange=trange_seconds(0, duration=10), # 此处指定截取素材前10秒(注意原片段时长为5秒)
handle_shrink=ShrinkMode.cut_tail, # 片段若要缩短，则依靠前移终止点来实现
handle_extend=ExtendMode.push_tail # 片段若要延长，则依靠后移终止点来实现，必要时允许后移后续片段
)从例子中可见，此替换方法可能会造成片段的时长变化，故可以利用handle_shrink和handle_extend参数指定片段在缩短和延长时的处理方式。
ℹ 不显式指定
handle_shrink和handle_extend时，默认的处理方式如下：
- 新素材比原素材短，则前移片段终止点，使得片段长度与新素材长度一致
- 新素材比原素材长，则裁剪素材范围，保持片段原长不变
具体的处理方式列表可参见枚举类ShrinkMode和ExtendMode的定义。
ℹ 目前已知替换带有组合出入场动画的片段不会自动刷新动画时间
这种方法将替换某个特定文本片段的内容，但保留其所有格式。
此过程同样分为选取轨道和替换内容两个步骤：其中“选取轨道”可参考根据片段替换素材中的示例。
以下假定我们已经选取了合适的文本轨道text_track，则只需：
script.replace_text(
text_track, 0, # 选取text_track中下标为0的片段，也即第一个片段
"新文本内容" # 新的文本内容
)此功能会字面意义地复制模板草稿中的指定轨道到新草稿中, 适合用于拼接多个模板草稿。
ℹ 目前仅支持导入音视频/文本轨道
⚠️ 本方法会保留各片段及其素材的id, 因而不支持向同一草稿多次导入同一轨道
例如
source_script = draft_folder.load_template("<模板草稿名称>") # 加载模板草稿
target_script = draft_folder.create_draft("新草稿", 1920, 1080) # 创建新草稿
# 选取模板中的一个文本轨道
text_track = source_script.get_imported_track(
cc.TrackType.text, # 选取导入的文本轨道
#name="text", # 假如轨道有名称，最好利用名称来定位
index=0 # 也可用下标定位, 0表示最底层的同类型轨道
)
# 导入文本轨道到新草稿
target_script.import_track(
source_script, text_track,
offset=target_script.duration, # 导入的轨道将放在新草稿末尾
new_name="imported_text", # 可选的新轨道名
relative_index=1, # 相对于所有文本轨道的位置, 值越大越接近前景, 可以是负数
)CapCut（和本项目）内部均采用微秒为单位保存时间，但这不便于输入，故我们增加了一种“字符串形式”的时间，大部分时间参数均同时支持这两种形式：
- 微秒形式：用
int表达，适于计算 - 字符串形式：用
str表达，如"1.5s"、"1h3m12s"等，易于输入
如果你希望显式地将字符串形式转换为微秒形式，可以使用tim函数；trange函数则是支持字符串形式输入的Timerange便捷构造函数。
通常推荐用 trange_seconds(start, end=...) 或 trange_seconds(start, duration=...) 创建时间范围：参数均以秒为单位，end 和 duration 必须且只能提供一个。它会分别把起点和终点取整到微秒，再计算持续时长；原有 trange 仍按微秒数或时间字符串解释参数。
相同的秒数时长在不同起点处，取整后的微秒时长可能相差 1 微秒。连续片段建议使用 end 指定共同的绝对边界。
⚠️ 注意trange的第二个参数是持续时长，而不是结束时间
例如：
import pycapcut as cc
from pycapcut import SEC, tim, trange
# 1秒钟
assert 1000000 == SEC == tim("1s") == tim("0.01666667m")
# 0~1分钟
assert cc.Timerange(0, 60*SEC) == trange("0s", "1m") == trange("0s", "0.5m30s")
# 片段开始后2秒
seg = cc.TextSegment("示例", cc.trange_seconds(0, duration=4))
assert seg.target_timerange.start + 2*SEC == seg.target_timerange.start + tim("2s")
# 以秒数给出相邻片段的绝对边界
first = cc.trange_seconds(0, end=1.25)
second = cc.trange_seconds(1.25, end=2.5)
assert first.end == second.start截取和变速均在Segment创建时设置完成，具体是通过target_timerange、source_timerange和speed参数来共同实现的。
ℹ 目前暂不支持设置曲线变速
以下以VideoSegment为例，AudioSegment的用法相同，此二者支持两种构造方式：
- 便捷构造：直接传入素材路径字符串，自动构造素材实例
- 传统构造：先创建素材实例，再传入片段构造函数。若需要设置素材的图像裁剪属性请使用此方式
import os
import pycapcut as cc
from pycapcut import trange, trange_seconds, SEC
# 假定已有草稿文件script（参见“快速上手”），创建三个轨道
for i in range(3, 0, -1): # 倒序
script.add_track(cc.TrackType.video, "%d" % i)
# 以下部分讲解素材与片段的创建
# 方式一：便捷构造（推荐）
tutorial_asset_dir = os.path.join(os.path.dirname(__file__), 'readme_assets', 'tutorial')
video_path = os.path.join(tutorial_asset_dir, 'video.mp4')
# 直接传入素材路径
seg1 = cc.VideoSegment(video_path, trange_seconds(0, duration=4)) # 截取素材的前4秒
# 方式二：传统构造
mat = cc.VideoMaterial(video_path) # 先创建素材实例
seg2 = cc.VideoSegment(mat, trange_seconds(0, duration=4)) # 再传入片段构造函数
# 视频素材长度为 5s
print("Video material length: %f s" % (mat.duration / SEC))
# 以下部分讲解素材的时间截取与变速
# 不指定source_timerange，则自动从头截取素材等长片段
seg11 = cc.VideoSegment(video_path, trange_seconds(0, duration=4)) # 自动截取素材的前4秒
seg2 = cc.VideoSegment(video_path, trange_seconds(0, duration=4), speed=1.25) # 自动截取素材的前4*1.25=5秒
# seg4 = cc.VideoSegment(video_path, trange_seconds(0, duration=3), speed=3.0) # 截取前3*3.0=9秒，素材不够长故报错
# 指定source_timerange，则截取素材的指定片段，自动设置速度
seg12 = cc.VideoSegment(video_path, trange_seconds(4, duration=1),
source_timerange=trange_seconds(0, duration=4)) # 将素材在1s内放完，速度自动设置为4.0
# 同时指定source_timerange和speed，则截取素材的指定片段，并根据播放速度覆盖target_timerange的duration
# 保留"66666h"作为字符串形式的占位时长，实际时长会被speed覆盖
seg3 = cc.VideoSegment(video_path, trange("1s", "66666h"),
source_timerange=trange_seconds(0, duration=5),
speed=2.0) # 将长5s的素材按2倍速放完，target_timerange的duration自动设为2.5s
# 将片段加入轨道
script.add_segment(seg11, "1").add_segment(seg12, "1")
script.add_segment(seg2, "2")
script.add_segment(seg3, "3")AudioSegment 和带音轨的 VideoSegment 均可设置 change_pitch=True，使音调随播放速度改变；默认值为 False，保持变速时的原音调。无音轨的视频不会产生可听变化。
audio_path = os.path.join(tutorial_asset_dir, 'audio.mp3')
audio_segment = cc.AudioSegment(audio_path, trange_seconds(0, duration=2),
speed=2.0, change_pitch=True)创建草稿时可以通过 maintrack_adsorb 设置主轨磁吸；默认启用。
script = draft_folder.create_draft("新草稿", 1920, 1080, maintrack_adsorb=False)
script.save()目前ScriptFile.add_track方法已支持创建多个同类型轨道，并支持自定义其顺序：
script.add_track(cc.TrackType.video,
track_name="前景", # 轨道名
relative_index=2) # 在所有视频轨道中的相对位置
script.add_track(cc.TrackType.video,
track_name="背景",
relative_index=1) # 由于1<2，所以前景轨道位于更上方ℹ 对于相同index的轨道，默认后创建的轨道位于上方
一旦创建了多个同类轨道，则在添加片段时必须指定目标轨道，例如：
script.add_segment(video_segment, "背景")每个视频片段都可以单独设置旋转、翻转、缩放、透明度和位移，通过 VideoSegment 构造函数的 clip_settings 参数传入。素材裁剪通过 VideoMaterial 的 crop_settings 参数设置。
ℹ 关键帧的优先级高于整体调节，故前者会覆盖后者的相应设置
下方的例子将创建一个视频片段，并设置其不透明度为0.5、打开水平翻转：
from pycapcut import ClipSettings
video_segment = cc.VideoSegment(video_material,
cc.Timerange(0, video_material.duration), # 与素材等长
clip_settings=ClipSettings(alpha=0.5, # 不透明度为0.5
flip_horizontal=True) # 打开水平翻转
)更具体的参数说明可参见ClipSettings的构造函数。
关键帧是吸附在片段上的“时刻-数值”对，所以创建关键帧只需要在add_keyframe方法中指定相对片段头部的时刻、数值以及控制的属性即可。
ℹ 目前不支持设置特效或滤镜参数的关键帧
下方的例子尝试使用两个不透明度关键帧模拟视频的淡出效果：
import os
import pycapcut as cc
from pycapcut import KeyframeProperty, SEC
# 假定已有草稿文件script（参见“快速上手”），创建视频轨道
script.add_track(cc.TrackType.video)
tutorial_asset_dir = os.path.join(os.path.dirname(__file__), 'readme_assets', 'tutorial')
# 创建视频片段
video_material = cc.VideoMaterial(os.path.join(tutorial_asset_dir, 'video.mp4'))
video_segment = cc.VideoSegment(video_material,
cc.Timerange(0, video_material.duration)) # 与素材等长
# 添加两个不透明度关键帧形成1s的淡出效果
video_segment.add_keyframe(KeyframeProperty.alpha, video_segment.duration - SEC, 1.0) # 结束前1s完全不透明
video_segment.add_keyframe(KeyframeProperty.alpha, video_segment.duration, 0.0) # 片段结束时完全透明
# 添加片段到轨道
script.add_segment(video_segment)除了alpha外，KeyframeProperty中还有平移、旋转、缩放、音量、饱和度等属性，它们都可以设置关键帧。
文本和贴纸片段的关键帧也可以用相同方法进行设置，但注意它们只支持位置和大小相关的那些属性。
对音频片段，目前只能设置音量的关键帧，此时你不需要指定KeyframeProperty
audio_segment: cc.AudioSegment
audio_segment.add_keyframe("0s", 0.6) # 片段开始时的音量为60%对音频片段或带音轨的视频片段调用 add_fade(in_duration, out_duration)，分别设置音频淡入、淡出时长。时长可使用时间字符串或微秒数，每个片段只能设置一次。
audio_segment.add_fade("1s", "0.5s")
video_segment.add_fade("0.5s", "1s")通过片段构造函数的 volume 参数设置音量，1.0 表示原始音量；动态音量变化可使用关键帧。
蒙版的添加非常简单：调用VideoSegment的add_mask方法即可：
from pycapcut import MaskType
# 添加一个线性蒙版，中心点在素材的(100, 0)像素处，顺时针旋转45度
video_segment1.add_mask(MaskType.线性, center_x=100, rotation=45)
# 添加一个圆形蒙版，直径占素材的50%
video_segment2.add_mask(MaskType.圆形, size=0.5)其中：
MaskType保存了CapCut自带的蒙版类型center_x和center_y参数表示蒙版中心点的坐标，与CapCut中意义一致rotation、feather、round_corner分别表示旋转、羽化、圆角参数，与CapCut中意义一致size参数表示蒙版的“主要尺寸”（镜面的可视部分高度/圆形直径/爱心高度等）占素材的比例
更具体的参数说明请参见add_mask方法的注释。
目前支持的特效类型由以下枚举类定义：
- 音频：
AudioSceneEffectType（场景音）、ToneEffectType（音色） - 视频：
VideoSceneEffectType（画面特效）、VideoCharacterEffectType（人物特效）
目前支持的动画类型由以下枚举类定义：
- 视频：
IntroType（入场）,OutroType（出场）,GroupAnimationType（组合动画） - 文本：
TextIntro（入场）、TextOutro（出场）,TextLoopAnim（循环动画）
滤镜类型则保存在FilterType中，仅对视频片段有效。
上述枚举类中的成员（通常）直接以特效或滤镜的名字命名，并注释了相应参数，例如：
你也可以使用from_name方法来获取特定的成员，其忽略大小写、空格和下划线，例如：
from pycapcut import VideoSceneEffectType
assert VideoSceneEffectType.from_name("__全息 扫描__") == VideoSceneEffectType.全息扫描
⚠️ 并非所有在枚举类中的特效均可用，请确认能在CapCut窗口中找到该特效再使用
添加特效使用的方法是segment.add_effect()，它接受特效类型和一个参数数组，参数数组的顺序与特效类型注释中的参数顺序一致，但不一定与CapCut内的参数顺序一致。
下方的例子为视频片段添加一个全息扫描特效，并且指定其氛围参数为（CapCut中的）100，其余参数默认：
from pycapcut import VideoSceneEffectType
video_segment.add_effect(VideoSceneEffectType.全息扫描,
[None, None, 100.0]) # 不设置前两个参数, 第三个参数（氛围）为100，其余参数也不设置音频片段的特效添加方法与视频片段相似。“花栗鼠”音色可这样添加，两个参数依次为音调和音色，范围均为 0～100，默认均为 50：
from pycapcut import ToneEffectType
audio_segment.add_effect(ToneEffectType.花栗鼠, [50, 42])同一音频片段只能添加一个音色；音色与场景音可以同时添加。ToneEffectType 提供 11 种通过参数调节的音色，暂不支持需要 AI 处理的语音转换效果。部分资源需要 CapCut 会员，具体以应用内提示为准。
滤镜的添加方法与特效类似，其使用的是VideoSegment.add_filter()方法。
与特效不同的是，滤镜只支持一个“滤镜强度”参数。
from pycapcut import FilterType
video_segment1.add_filter(FilterType.冷蓝, 10) # 设置"冷蓝"强度为10
video_segment2.add_filter(FilterType.冷蓝, 50) # 设置"冷蓝"强度为50VideoSegment.set_mix_mode()用于设置叠放视频片段的混合模式。MixModeType 提供十种模式：正片叠底、颜色减淡、颜色加深、线性加深、柔光、强光、滤色、叠加、变亮、变暗。下层片段需从主轨道的 0 秒开始，上层片段应在更高的轨道上：
import pycapcut as cc
# 假定已有草稿文件 script，且两个视频文件均不少于 5 秒
script.add_track(cc.TrackType.video, "背景", relative_index=0)
script.add_track(cc.TrackType.video, "前景", relative_index=2)
script.add_segment(cc.VideoSegment("background.mp4", cc.trange_seconds(0, duration=5)), "背景")
foreground = cc.VideoSegment("foreground.mp4", cc.trange_seconds(0, duration=5))
foreground.set_mix_mode(cc.MixModeType.正片叠底)
script.add_segment(foreground, "前景")再次调用会以最后一次设置为准，片段只保留一个混合模式。效果需要上层片段与下层画面重叠才能看出。
对视频片段调用 add_chroma()。颜色使用 #RRGGBBAA；四个数值按 CapCut 界面上的 0–100 填写，依次对应强度、阴影、边缘羽化、边缘清除。默认值依次为 20、0、0、0。每个片段只能添加一次，并应在 script.add_segment() 之前调用。部分控件需要 CapCut 会员，具体以应用内提示为准。
import pycapcut as cc
script.add_track(cc.TrackType.video, "背景", relative_index=0)
script.add_track(cc.TrackType.video, "前景", relative_index=2)
script.add_segment(cc.VideoSegment("background.mp4", cc.trange_seconds(0, duration=4)), "背景")
foreground = cc.VideoSegment("green_screen.mp4", cc.trange_seconds(1, duration=2))
foreground.add_chroma("#00FE00FF", intensity=36, shadow=10, edge_smooth=3, spill=26)
script.add_segment(foreground, "前景")除了为视频片段添加特效和滤镜外，你还可以创建独立的特效轨道和滤镜轨道，并在其上添加特效和滤镜片段。
首先使用ScriptFile.add_track()方法创建特效轨道或滤镜轨道。若需要指定顺序请参考多轨道操作
script.add_track(cc.TrackType.effect, "my_effect") # 创建名为"my_effect"的特效轨道
script.add_track(cc.TrackType.filter, "my_filter") # 创建名为"my_filter"的滤镜轨道接下来便可使用add_effect和add_filter方法向这些轨道添加片段：
from pycapcut import VideoSceneEffectType, FilterType, trange, trange_seconds
# 在特效轨道上添加一个"胶片闪切"特效，持续5秒，并设置其参数
script.add_effect(VideoSceneEffectType.胶片闪切, trange_seconds(0, duration=5),
track_name="my_effect", # 当特效轨道只有一条时可省略
params=[50, None, 80]) # 设置速度为50，保持强度默认(100)，设置纹理为80
# 在滤镜轨道上添加一个"冷蓝"滤镜，持续整个视频，强度为70
# script.duration 是内部微秒值，直接使用 trange
script.add_filter(FilterType.冷蓝, trange(0, script.duration),
track_name="my_filter", # 当滤镜轨道只有一条时可省略
intensity=70)添加动画使用的方法是segment.add_animation()。不传时长时，文本入场和出场动画使用各自效果的默认时长；也可通过第二个参数指定时长。循环动画自动填满片段中其余无动画的部分。若需要添加多个动画，可对同一个片段调用多次该方法。
ℹ 为文本片段同时设置循环动画和入出场动画时, 请先添加出入场动画再添加循环动画
以下是为一个文本片段添加三种动画的例子：
from pycapcut import TextIntro, TextOutro, TextLoopAnim
text_seg.add_animation(TextIntro.复古打字机).add_animation(TextOutro.弹簧)
text_seg.add_animation(TextLoopAnim.色差故障) # 注意：循环动画必须在出入场动画之后添加添加文本与添加视频/音频片段类似，只需创建TextSegment对象并利用add_segment添加到ScriptFile中即可。
其字体、文字样式及图像调节设置可分别通过font, style和clip_settings参数设置。
例如：
import pycapcut as cc
from pycapcut import FontType, TextStyle, ClipSettings, trange_seconds
# 带下划线、位置及大小类似字幕的浅蓝色文本
seg1 = cc.TextSegment("Subtitle", trange_seconds(0, duration=10),
font=FontType.思源粗宋,
style=TextStyle(size=5.0, color=(0.7, 0.7, 1.0), underline=True, align=1),
clip_settings=ClipSettings(transform_y=-0.8))更具体的参数说明可参见TextStyle和ClipSettings的构造函数。
文本片段支持自动换行功能，可以通过TextStyle的auto_wrapping和max_line_width参数来控制：
# 启用自动换行，设置最大行宽为屏幕宽度的70%
seg2 = cc.TextSegment("这是一段很长的文本内容，当超过设定的最大行宽时会自动换行显示",
trange_seconds(0, duration=10),
font=FontType.思源粗宋,
style=TextStyle(size=5.0,
auto_wrapping=True, # 启用自动换行
max_line_width=0.7)) # 最大行宽占屏幕70%ℹ 目前只支持导入SRT格式的字幕文件
导入字幕本质上是根据每条字幕的时间戳及内容创建一系列文本，并添加到轨道中。这一过程通过ScriptFile.import_srt来实现。
导入的字幕默认启用自动换行功能。
例如：
import pycapcut as cc
# 假定已有草稿文件script（参见“快速上手”）
# 将字幕导入到名为"subtitle"的轨道中，若轨道不存在将自动创建
# 不指定style和clip_settings，则默认模拟CapCut导入字幕时的样式
script.import_srt("subtitle.srt", track_name="subtitle", time_offset="1.5s") # 字幕整体后移1.5秒以下示例是不同的用法，请按需选用，避免在同一轨道重复导入重叠字幕。
# 可以利用`text_style`和`clip_settings`参数对字幕的样式进行调整, 上述参数的意义与`TextSegment()`中的相同
script.import_srt("subtitle.srt", track_name="subtitle",
text_style=cc.TextStyle(size=10.0, color=(1.0, 0.0, 0.0)),
clip_settings=cc.ClipSettings(transform_y=0.8)) # 将字幕放置在屏幕上方# 如果需要更复杂的样式或希望为字幕应用动画，可以为`style_reference`参数传入一个`TextSegment`对象作为样式参考（忽略其文本和片段长度设置）
# 注意动画时间不会根据字幕片段长度进行调节，故当字幕片段过短时可能出现奇怪的效果
script.import_srt("subtitle.srt", track_name="subtitle", style_reference=seg1) # 以上一节“添加文本”中的文本作为参考# 默认不会采用`style_reference`片段中的`clip_settings`设置，如果需要的话请显式传入`clip_settings=None`
script.import_srt("subtitle.srt", track_name="subtitle", style_reference=seg1, clip_settings=None) # 相当于clip_settings=seg1.clip_settings