pyCapCut

pyCapCut is a lightweight and flexible Python tool for generating and exporting CapCut drafts, designed to build automated video editing/mashup pipelines.

Key feature areas include:

• Template Mode: Loading unencrypted draft_content.json files, replacing assets by name, modifying text, importing specific tracks, and extracting metadata for stickers/bubbles.
• Batch Export: Controlling CapCut to open specific drafts, exporting to designated locations, and adjusting resolution/frame rate.
• Video & Images: Adding local assets, customizing duration/speed, audio fades, rotation/scaling/brightness, keyframes, entrance/exit animations, masks, effects, filters, and background filling.
• Audio: Adding local audio, customizing duration/speed, volume/fade keyframes, and scene sound effects.
• Tracks: Adding tracks, adding clips to specific tracks, and managing layer hierarchies for video/filters/effects.
• Effects, Filters & Transitions: Applying effects/filters/animations to clips or independent tracks, and adding transitions with custom durations.
• Text & Subtitles: Adding text with font/style/position/rotation, keyframes, animations, strokes, backgrounds, shadows, bubbles, and automatic line wrapping. Supports importing .srt files for batch subtitle generation.

There are two ways to replace media depending on whether you want to affect all segments or just one.

Replace media by name

Replaces the media file itself. This is best for images and affects every segment that references that material. It does not change the source range.

new_material = cc.AudioMaterial("<path to new audio file>")
script.replace_material_by_name("audio.mp3", new_material)

Replace media by segment

Replaces the media for a specific segment at a specific index. This allows you to reselect the source_timerange and control how the timeline reacts to changes in length using handle_shrink and handle_extend.

Parameters:

• handle_shrink: Controls behavior if the new media is shorter (e.g., ShrinkMode.cut_tail).
• handle_extend: Controls behavior if the new media is longer (e.g., ExtendMode.push_tail).

Default behavior (if not specified):

• If shorter: Move segment end earlier to match new length.
• If longer: Crop source range to keep segment duration unchanged.

from pycapcut import trange, ShrinkMode, ExtendMode

audio_track = script.get_imported_track(cc.TrackType.audio, index=0)

script.replace_material_by_seg(
    audio_track, 0, new_material, 
    source_timerange=trange("0s", "10s"),
    handle_shrink=ShrinkMode.cut_tail, 
    handle_extend=ExtendMode.push_tail
)

To preserve complex features like text effects or composite clips, you can load an existing CapCut draft as a template and either import its content into a new draft or replace specific parts of it.

Loading a Template

Use DraftFolder to manage your CapCut draft directory. You can duplicate a template draft to create a new editable ScriptFile.

Replacement Strategies

1. Replace material by name: Replaces the underlying material itself. This affects all clips referencing that material. It is highly recommended for image materials as it doesn't change time ranges.
2. Replace material by segment: Replaces the material for a specific clip and allows you to redefine the source time range and how the clip handles duration changes (shrinking or extending).
3. Replace text content: Replaces the text string of a specific text segment while preserving all existing formatting (font, style, etc.).

Extracting Material Metadata

If you need to use specific stickers or text effects from a template, use inspect_material() on a ScriptFile or DraftFolder to retrieve their resource_id or effect_id.

import pycapcut as cc

draft_folder = cc.DraftFolder("<CapCut草稿文件夹>")
# Duplicate template and open for editing
script = draft_folder.duplicate_as_template("模板草稿", "新草稿")

# Example: Replace material by name
new_material = cc.AudioMaterial("<新的音频素材路径>")
script.replace_material_by_name("audio.mp3", new_material)

script.save()

To preserve complex features like text effects or compound clips, you can use an existing CapCut draft as a template. This allows you to load a draft, replace specific media or text, or import tracks from it into a new draft.

Workflow

1. Load Template: Use DraftFolder to manage and duplicate existing drafts.
2. Replace Content: Use one of three methods:
   • Replace media by name: Replaces the media file itself (affects all segments using it).
   • Replace media by segment: Replaces media for a specific segment, allowing you to redefine the source_timerange and handle timeline stretching/shrinking.
   • Replace text content: Replaces text while preserving all formatting.
3. Extract Metadata: Use inspect_material to find resource_ids for stickers or fancy text to use them in new segments.
4. Import Tracks: Copy specific tracks (audio, video, or text) from a template draft into a new draft using import_track.

import pycapcut as cc

draft_folder = cc.DraftFolder("<CapCut Drafts folder>")
script = draft_folder.duplicate_as_template("Template Draft", "New Draft")

# Edit the script (replace media, add tracks, etc.)
script.save()

Segments (Video or Audio) can be created with specific source trimming and playback speed.

Construction Styles:

1. Convenience: Pass a file path string directly. The material is created automatically.
2. Traditional: Create a Material instance first, then pass it to the Segment constructor. Use this if you need to set specific crop/clip properties on the material.

Key Parameters:

• target_timerange: The duration the segment occupies on the timeline.
• source_timerange: The specific part of the media to play.
• speed: The playback speed (e.g., 2.0 for 2x speed). If source_timerange and speed are both provided, the target_timerange is overridden by the speed calculation.

import pycapcut as cc
from pycapcut import trange

# Method 1: Convenience (Trim first 4s, play at 1.25x speed)
seg1 = cc.VideoSegment("video.mp4", trange("0s", "4s"), speed=1.25)

# Method 2: Traditional (Play 5s of material at 2x speed, resulting in 2.5s on timeline)
mat = cc.VideoMaterial("video.mp4")
seg2 = cc.VideoSegment(mat, trange("1s", "66666h"), 
                        source_timerange=trange("0s", "5s"), 
                        speed=2.0)

Adding Text

Create a TextSegment and add it to a track. You can customize fonts, styles (size, color, underline, alignment), and position via ClipSettings.

Auto-wrapping: Enable auto_wrapping=True in TextStyle and set max_line_width (as a proportion of screen width) to handle long text.

Importing Subtitles (SRT)

Use script.import_srt(file_path, track_name, ...) to automatically create text segments from an SRT file.

Options:

• time_offset: Shift all subtitles by a specific time (e.g., "1.5s").
• text_style: Apply a specific TextStyle to all subtitles.
• style_reference: Use an existing TextSegment as a template for style and clip_settings. If you want to adopt the reference's clip_settings, pass clip_settings=None.

# Text with auto-wrapping
seg = cc.TextSegment("Long text...", trange("0s", "10s"),
                     style=cc.TextStyle(auto_wrapping=True, max_line_width=0.7))

# Import SRT
script.import_srt("subtitle.srt", track_name="subtitle", time_offset="1.5s")