### Create Video Segments with Trimming and Speed Adjustments

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Demonstrates creating `VideoSegment` objects using both convenience and traditional constructors. It shows how to trim source media using `target_timerange` and `source_timerange`, and adjust playback speed using the `speed` parameter. Examples include automatic trimming and speed calculation based on specified ranges.

```python
import os
import pycapcut as cc
from pycapcut import trange, SEC

# Assume we already have a draft object `script` (see “Quick Start”), and create three tracks
for i in range(3, 0, -1): # reverse order
    script.add_track(cc.TrackType.video, "%d" % i)

# The following demonstrates creation of materials and segments
# Method 1: convenience constructor (recommended)
tutorial_asset_dir = os.path.join(os.path.dirname(__file__), 'readme_assets', 'tutorial')
video_path = os.path.join(tutorial_asset_dir, 'video.mp4')

# Pass the media path directly
seg1 = cc.VideoSegment(video_path, trange("0s", "4s"))  # Trim the first 4 seconds of the material

# Method 2: traditional constructor
mat = cc.VideoMaterial(video_path)  # Create the material instance first
seg2 = cc.VideoSegment(mat, trange("0s", "4s"))  # Then pass it to the constructor

# The video material length is 5s
print("Video material length: %f s" % (mat.duration / SEC))

# The following demonstrates source trimming and speed
# If source_timerange is not specified, the first segment of equal length is used automatically
seg11 = cc.VideoSegment(video_path, trange("0s", "4s"))              # Automatically trim first 4 seconds ("4s" means duration)
seg2  = cc.VideoSegment(video_path, trange("0s", "4s"), speed=1.25)  # Automatically trim the first 4*1.25=5 seconds
seg4  = cc.VideoSegment(video_path, trange("0s", "3s"), speed=3.0)   # Trim the first 3*3.0=9 seconds; will error if material is too short

# If source_timerange is specified, trim the specified range and auto-set speed
seg12 = cc.VideoSegment(video_path, trange("4s", "1s"),
                            source_timerange=trange(0, "4s"))     # Play 4s of material within 1s; speed auto-set to 5.0

# If both source_timerange and speed are specified, trim the specified range and override target duration by speed
seg3  = cc.VideoSegment(video_path, trange("1s", "66666h"),
                            source_timerange=trange(0, "5s"),
                            speed=2.0) # Play 5s of material at 2x speed; target duration becomes 2.5s

# Add segments to tracks
script.add_segment(seg11, "1").add_segment(seg12, "1")
script.add_segment(seg2, "2")
script.add_segment(seg3, "3")
```

--------------------------------

### Simulate Fade-Out Effect with Keyframes

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Provides an example of implementing a fade-out effect by adding opacity keyframes to a video segment. This involves specifying the time within the segment and the corresponding opacity value for each keyframe.

```python
import os
import pycapcut as cc
from pycapcut import KeyframeProperty, SEC

# Example assumes 'video_segment' and 'script' are already defined
# and that the segment has a duration that accommodates the keyframes.

# Add two keyframes to simulate a fade-out:
# 1. At the start of the segment (time 0), opacity is 1.0 (fully visible).
# 2. At the end of the segment (duration of segment), opacity is 0.0 (fully transparent).

# Assuming video_segment duration is known, let's say segment_duration = 5.0 * SEC

# script.add_keyframe(video_segment, 0, 1.0, KeyframeProperty.opacity)
# script.add_keyframe(video_segment, segment_duration, 0.0, KeyframeProperty.opacity)

# Note: The actual implementation would require knowing the segment's duration
# and potentially adding it to the script after keyframes are set.
```

--------------------------------

### Get Effect Enum Member by Name

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Illustrates how to retrieve an effect enum member by its name using the `from_name` method, which ignores case, spaces, and underscores.

```python
from pyJianYingDraft import VideoSceneEffectType

assert VideoSceneEffectType.from_name("__全息 扫描__") == VideoSceneEffectType.全息扫描

```

--------------------------------

### Apply Global Video Clip Settings

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Demonstrates how to apply global video adjustments such as opacity and flipping to a `VideoSegment` using the `clip_settings` parameter. This method allows for consistent adjustments across the entire segment, with the caveat that keyframes take precedence.

```python
from pycapcut import ClipSettings
video_segment = cc.VideoSegment(video_material,
                                   cc.Timerange(0, video_material.duration),      # Same length as the material
                                   clip_settings=ClipSettings(alpha=0.5,             # Opacity 0.5
                                                              flip_horizontal=True)  # Enable horizontal flip
                                    )
```

--------------------------------

### Add Video Track and Video Segment with Keyframes

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Demonstrates adding a video track to a script, creating a video segment from a material, and setting opacity keyframes for a fade-out effect. Supports keyframes for various properties like translation, rotation, and scale.

```python
import os
import pycapcut as cc

# Assume script object is already initialized
script = cc.ScriptFile()

# Add a video track
script.add_track(cc.TrackType.video)

tutorial_asset_dir = os.path.join(os.path.dirname(__file__), 'readme_assets', 'tutorial')

# Create a video segment
video_material = cc.VideoMaterial(os.path.join(tutorial_asset_dir, 'video.mp4'))
video_segment = cc.VideoSegment(video_material,
                                   cc.Timerange(0, video_material.duration)) # Same length as the material

# Add two opacity keyframes to make a 1s fade-out
video_segment.add_keyframe(cc.KeyframeProperty.alpha, video_segment.duration - 1.0, 1.0) # Fully opaque 1s before end
video_segment.add_keyframe(cc.KeyframeProperty.alpha, video_segment.duration, 0.0) # Fully transparent at end

# Add the segment to the track
script.add_segment(video_segment)

```

--------------------------------

### Create and Position Video Tracks

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Shows how to add multiple video tracks to a script and customize their order using `relative_index`. Tracks with lower indices are positioned below tracks with higher indices.

```python
script.add_track(cc.TrackType.video,
                 track_name="Foreground",       # Track name
                 relative_index=2)              # Relative position among all video tracks
script.add_track(cc.TrackType.video,
                 track_name="Background",
                 relative_index=1)              # Since 1 < 2, the background track is below the foreground
```

--------------------------------

### Build Complete Video from Scratch with PyCapCut

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Demonstrates building a complete video project from scratch using pyCapCut. This includes initializing a draft, adding audio and video tracks, incorporating background music with fades, adding video clips with animations and transitions, applying keyframe animations, adding title text with effects, importing subtitles from an SRT file, and saving the draft. It utilizes various classes and enums like AudioSegment, VideoSegment, TextSegment, FilterType, TransitionType, IntroType, FontType, TextStyle, ClipSettings, TextIntro, TextOutro, KeyframeProperty, and DraftFolder.

```python
import pycapcut as cc
from pycapcut import trange, tim, ClipSettings, TextStyle, FontType
from pycapcut import VideoSceneEffectType, FilterType, TransitionType
from pycapcut import IntroType, TextIntro, TextOutro, KeyframeProperty

# Initialize draft folder and create new draft
draft_folder = cc.DraftFolder(r"C:\\Users\\YourName\\Documents\\CapCut Drafts")
script = draft_folder.create_draft("automated_video", 1920, 1080, allow_replace=True)

# Add tracks
script.add_track(cc.TrackType.audio)
script.add_track(cc.TrackType.video)
script.add_track(cc.TrackType.text)

# Add background music with fade
audio = cc.AudioSegment("music.mp3", trange("0s", "20s"), volume=0.5)
audio.add_fade("2s", "3s")
script.add_segment(audio)

# Add first video clip with intro animation
video1 = cc.VideoSegment("clip1.mp4", trange("0s", "5s"))
video1.add_animation(IntroType.噪点拽入, duration="1s")
video1.add_filter(FilterType.冷蓝, intensity=60)
script.add_segment(video1)

# Add second video with transition
video2 = cc.VideoSegment("clip2.mp4", trange("5s", "5s"))
video1.add_transition(TransitionType.信号故障, duration="0.5s")
script.add_segment(video2)

# Add third video with keyframe animation
video3 = cc.VideoSegment("clip3.mp4", trange("10s", "5s"))
video3.add_keyframe(KeyframeProperty.scale, tim("10s"), 1.0)
video3.add_keyframe(KeyframeProperty.scale, tim("12.5s"), 1.3)
video3.add_keyframe(KeyframeProperty.scale, tim("15s"), 1.0)
script.add_segment(video3)

# Add title text
title = cc.TextSegment(
    "My Awesome Video",
    trange("0s", "3s"),
    font=FontType.悠然体,
    style=TextStyle(size=12.0, color=(1.0, 0.8, 0.0), align=1),
    clip_settings=ClipSettings(transform_y=0.5)
)
title.add_animation(TextIntro.复古打字机)
title.add_animation(TextOutro.弹簧)
script.add_segment(title)

# Add subtitles from SRT file
script.import_srt(
    "subtitles.srt",
    track_name="subs",
    text_style=TextStyle(size=6.0, align=1),
    clip_settings=ClipSettings(transform_y=-0.8)
)

# Save the draft
script.save()

print(f"Draft created successfully!")
print(f"Duration: {script.duration / 1000000:.2f} seconds")
print(f"Open '{script.save_path}' in CapCut to export the video")
```

--------------------------------

### Add Intro/Outro Animations and Keyframes for Video Segments

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Demonstrates how to add intro and outro animations to video segments and how to use keyframes to animate properties like position, opacity (alpha), and scale over time. It lists supported keyframe properties.

```python
import pycapcut as cc
from pycapcut import trange, tim, KeyframeProperty, IntroType, OutroType

# Video segment with intro/outro animations
video_seg = cc.VideoSegment("video.mp4", trange("0s", "5s"))
video_seg.add_animation(IntroType.噪点拽入, duration="1s")
video_seg.add_animation(OutroType.像素溶解, duration="0.8s")

# Add keyframes for position animation
video_seg.add_keyframe(KeyframeProperty.position_x, tim("0s"), -2.0)
video_seg.add_keyframe(KeyframeProperty.position_x, tim("0.5s"), 0.0)
video_seg.add_keyframe(KeyframeProperty.position_x, tim("4.5s"), 0.0)
video_seg.add_keyframe(KeyframeProperty.position_x, tim("5s"), 2.0)

# Add keyframes for opacity fade effect
video_seg.add_keyframe(KeyframeProperty.alpha, tim("0s"), 0.0)
video_seg.add_keyframe(KeyframeProperty.alpha, tim("0.5s"), 1.0)
video_seg.add_keyframe(KeyframeProperty.alpha, tim("4.5s"), 1.0)
video_seg.add_keyframe(KeyframeProperty.alpha, tim("5s"), 0.0)

# Add keyframes for scale animation
video_seg.add_keyframe(KeyframeProperty.scale, tim("1s"), 1.0)
video_seg.add_keyframe(KeyframeProperty.scale, tim("2s"), 1.5)
video_seg.add_keyframe(KeyframeProperty.scale, tim("3s"), 1.0)

# Supported keyframe properties:
# position_x, position_y, scale, scale_x, scale_y, rotation,
# alpha, volume, brightness, contrast, saturation, etc.

# script.add_segment(video_seg, "video")
```

--------------------------------

### Initialize and Manage CapCut Drafts with pyCapCut

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Demonstrates how to initialize a draft folder, create new video drafts with specified resolutions and frame rates, add audio, video, and text tracks, save drafts, and list existing drafts. It requires the 'pycapcut' library and specifies a local path for draft storage.

```python
import pycapcut as cc

# Initialize draft folder manager
draft_folder = cc.DraftFolder(r"C:\\Users\\YourName\\Documents\\CapCut Drafts")

# Create a new draft with 1920x1080 resolution at 30fps
script = draft_folder.create_draft("my_video", 1920, 1080, fps=30, allow_replace=True)

# Add tracks for different media types
script.add_track(cc.TrackType.audio)
script.add_track(cc.TrackType.video)
script.add_track(cc.TrackType.text)

# Save the draft to disk
script.save()

# List all drafts in the folder
print(draft_folder.list_drafts())  # ['my_video', 'template_1', ...]

# Check if a draft exists
if draft_folder.has_draft("my_video"):
    print("Draft exists")
```

--------------------------------

### Creating and Managing Drafts

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

This section covers initializing the draft folder manager, creating new drafts with specified resolutions and frame rates, adding different track types (audio, video, text), saving drafts, listing existing drafts, and checking for draft existence.

```APIDOC
## DraftFolder and Script Management

### Description
Provides methods for initializing a draft management environment, creating new video drafts, adding tracks, saving drafts, and managing existing drafts within a specified folder.

### Methods
- `DraftFolder(path)`: Initializes a draft folder manager at the given path.
- `create_draft(name, width, height, fps=30, allow_replace=False)`: Creates a new video draft with specified dimensions and frame rate. `allow_replace` determines if an existing draft with the same name can be overwritten.
- `add_track(track_type)`: Adds a new track of the specified type (e.g., `cc.TrackType.audio`) to the current script.
- `save()`: Saves the current draft script to disk.
- `list_drafts()`: Returns a list of all draft names within the managed folder.
- `has_draft(name)`: Checks if a draft with the given name exists.

### Request Example
```python
import pycapcut as cc

# Initialize draft folder manager
draft_folder = cc.DraftFolder(r"C:\Users\YourName\Documents\CapCut Drafts")

# Create a new draft
script = draft_folder.create_draft("my_video", 1920, 1080, fps=30, allow_replace=True)

# Add tracks
script.add_track(cc.TrackType.audio)
script.add_track(cc.TrackType.video)
script.add_track(cc.TrackType.text)

# Save the draft
script.save()

# List drafts
print(draft_folder.list_drafts())

# Check existence
if draft_folder.has_draft("my_video"):
    print("Draft exists")
```

### Response Example (Conceptual)
```json
{
  "message": "Draft created and saved successfully."
}
```
```

--------------------------------

### Create Effect and Filter Tracks

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Explains how to create dedicated effect and filter tracks within a script using `ScriptFile.add_track()`. These tracks can then hold effect or filter segments.

```python
import pycapcut as cc

# Assume script object is already initialized
script = cc.ScriptFile()

# Create an effect track named 'my_effect'
script.add_track(cc.TrackType.effect, "my_effect")

# Create a filter track named 'my_filter'
script.add_track(cc.TrackType.filter, "my_filter")

```

--------------------------------

### Create and Style Text Segments with Animations

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Demonstrates how to create a text segment with custom styling (font, size, color, style, alignment, spacing) and apply intro, outro, and loop animations. It also shows how to import subtitles from an SRT file with a specified time offset and style.

```python
import pycapcut as cc
from pycapcut import trange, TextStyle, ClipSettings, FontType, TextIntro, TextOutro, TextLoopAnim

# Create styled text segment
text_seg = cc.TextSegment(
    "Hello World",
    trange("0s", "5s"),
    font=FontType.悠然体,
    style=TextStyle(
        size=10.0,
        color=(1.0, 1.0, 0.0),      # Yellow (RGB 0-1 range)
        alpha=1.0,                  # Fully opaque
        bold=True,
        italic=False,
        underline=True,
        align=1,                    # 0=left, 1=center, 2=right
        letter_spacing=5,
        line_spacing=10,
        auto_wrapping=True,         # Enable auto line wrapping
        max_line_width=0.7          # 70% of screen width
    ),
    clip_settings=ClipSettings(
        transform_y=-0.8            # Position at bottom (subtitle area)
    )
)

# Add text animations
text_seg.add_animation(TextIntro.复古打字机)
text_seg.add_animation(TextOutro.弹簧)
text_seg.add_animation(TextLoopAnim.色差故障)  # Add loop animation last

# Import subtitles from SRT file
# script.import_srt(
#     "subtitles.srt",
#     track_name="subtitle_track",
#     time_offset="1.5s",             # Shift all subtitles by 1.5s
#     text_style=TextStyle(
#         size=8.0,
#         color=(1.0, 1.0, 1.0),
#         align=1
#     ),
#     clip_settings=ClipSettings(transform_y=-0.8)
# )

# script.add_segment(text_seg, "text")
```

--------------------------------

### Work with Time Ranges and Time Conversions in pyCapCut

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Illustrates creating time ranges using convenience functions like `trange` and converting time strings to microseconds using `tim`. It also shows how to use the `SEC` constant for microsecond calculations and access properties of time ranges.

```python
from pycapcut import trange, tim, SEC

# Create time ranges using convenience functions
t1 = trange("0s", "5s")           # Start at 0s, duration 5s
t2 = trange("1m30s", "2m")        # Start at 1:30, duration 2 minutes
t3 = trange("0.5s", "0.25s")      # Start at 0.5s, duration 0.25s

# Convert string time to microseconds
duration_us = tim("1.5s")         # Returns 1500000 microseconds
offset = tim("2m30s")             # Returns 150000000 microseconds

# Use SEC constant for seconds
assert SEC == 1000000             # 1 second = 1,000,000 microseconds
three_seconds = 3 * SEC

# Access time range properties
print(t1.start)                   # 0
print(t1.duration)                # 5000000
print(t1.end)                     # 5000000 (start + duration)
```

--------------------------------

### Time Formatting and Conversion in PyCapCut

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Demonstrates PyCapCut's time handling, which uses microseconds internally. It supports convenient string inputs like "1.5s" or "1h3m12s" for time parameters. Utility functions like `tim` for string-to-microseconds conversion and `trange` for creating time ranges are provided.

```python
import pycapcut as cc
from pycapcut import SEC, tim, trange

# 1 second
assert 1000000 == SEC == tim("1s") == tim("0.01666667m")

# 0~1 minute
assert cc.Timerange(0, 60*SEC) == trange("0s", "1m") == trange("0s", "0.5m30s")

# 2 seconds after a segment starts
seg: cc.VideoSegment
assert seg.target_timerange.start + 2*SEC == seg.target_timerange.start + tim("2s")
```

--------------------------------

### Load CapCut Draft as Template using DraftFolder

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Loads a CapCut draft as a template and creates a new editable draft from it. This method is recommended for managing CapCut drafts and their associated folders, facilitating the reuse of complex template features. It returns a ScriptFile object for further editing.

```python
import pycapcut as cc

draft_folder = cc.DraftFolder("<CapCut Drafts folder>")  # Usually like ".../CapCut Drafts"
script = draft_folder.duplicate_as_template("Template Draft", "New Draft")  # Copy "Template Draft" to a new draft named "New Draft" and open it for editing

# Edit the returned ScriptFile object, e.g., replace media, add tracks and segments

script.save()  # Save your "New Draft"
```

--------------------------------

### Apply Linear and Circular Masks to Video Segments

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Demonstrates how to add linear and circular masks to video segments using `VideoSegment.add_mask`. Parameters control position, rotation, size, and feathering.

```python
from pycapcut import MaskType

# Assume video_segment1 and video_segment2 are initialized VideoSegment objects
video_segment1: cc.VideoSegment
video_segment2: cc.VideoSegment

# Add a linear mask centered at (100, 0) pixels on the material, rotated 45 degrees clockwise
video_segment1.add_mask(MaskType.线性, center_x=100, rotation=45)

# Add a circular mask with diameter 50% of the material
video_segment2.add_mask(MaskType.圆形, size=0.5)

```

--------------------------------

### Add Effects, Filters, and Transitions to Video Segments

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Shows how to apply video effects (e.g., '全息扫描'), filters (e.g., '冰雪世界'), and transitions (e.g., '信号故障') to video segments. It also covers adding global effects and filters that span specific time ranges or the entire video duration.

```python
import pycapcut as cc
from pycapcut import trange, VideoSceneEffectType, FilterType, TransitionType

# Add effect to video segment
video_seg = cc.VideoSegment("video.mp4", trange("0s", "5s"))
video_seg.add_effect(
    VideoSceneEffectType.全息扫描,
    params=[None, None, 100.0]      # Parameters match enum annotation order
)

# Add filter to video segment
video_seg.add_filter(FilterType.冰雪世界, intensity=70)

# Add transition between segments (add to the first segment)
video_seg.add_transition(TransitionType.信号故障, duration="0.5s")

# Create standalone effect/filter tracks
# script.add_track(cc.TrackType.effect, "global_effect")
# script.add_track(cc.TrackType.filter, "global_filter")

# Add effect spanning specific time range
# script.add_effect(
#     VideoSceneEffectType.胶片闪切,
#     trange("2s", "3s"),
#     track_name="global_effect",
#     params=[50, None, 80]
# )

# Add filter spanning entire video
# script.add_filter(
#     FilterType.冷蓝,
#     trange(0, script.duration),
#     track_name="global_filter",
#     intensity=80
# )

# script.add_segment(video_seg, "video")
```

--------------------------------

### Add Filter to Video Segment

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Demonstrates adding filters to video segments using `VideoSegment.add_filter()`. Filters typically support a single 'intensity' parameter.

```python
from pyJianYingDraft import FilterType

# Assume video_segment1 and video_segment2 are initialized VideoSegment objects
video_segment1: cc.VideoSegment
video_segment2: cc.VideoSegment

# Add the '原生肤' filter with intensity 10
video_segment1.add_filter(FilterType.原生肤, 10)

# Add the '冰雪世界' filter with intensity 50
video_segment2.add_filter(FilterType.冰雪世界, 50)

```

--------------------------------

### Import Tracks from Template Draft in PyCapCut

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Copies specified tracks from a template draft into a new draft. This is useful for combining multiple templates. It supports audio, video, and text tracks and preserves segment and material IDs. Ensure not to import the same track twice.

```python
source_script = draft_folder.load_template("<Template Draft Name>")     # Load the template draft
target_script = draft_folder.create_draft("New Draft", 1920, 1080)  # Create a new draft

# Select a text track from the template
text_track = source_script.get_imported_track(
    cc.TrackType.text,                # Select imported text track
    #name="text",                        # If the track has a name, prefer using it
    index=0                              # Or locate by index; 0 means the bottom-most track of the same type
)

# Import the text track into the new draft
target_script.import_track(
    source_script, text_track,
    offset=target_script.duration,  # Place the imported track at the end of the new draft
    new_name="imported_text",       # Optional new track name
    relative_index=1,               # Relative order among all text tracks; larger values are closer to the foreground; can be negative
)
```

--------------------------------

### Add Volume Keyframes to Audio Segment

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Shows how to add volume keyframes to an audio segment. Currently, only volume keyframes are supported for audio segments, and the KeyframeProperty enum is not needed.

```python
import pycapcut as cc

audio_segment: cc.AudioSegment
audio_segment.add_keyframe("0s", 0.6) # Volume is 60% at the start of the segment

```

--------------------------------

### Adding Video Segments

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

This section explains how to add video segments to a draft, including specifying the source file, timeline placement, source trimming, speed control, and applying various clip settings like transformations, scaling, rotation, and opacity.

```APIDOC
## VideoSegment

### Description
Represents a video clip to be added to the video track. Allows for precise control over its placement on the timeline, source media usage, playback speed, and visual appearance.

### Class
`cc.VideoSegment(path, timerange, source_timerange=None, speed=1.0, clip_settings=None, volume=1.0)`

### Parameters
- **path** (str) - Path to the video file.
- **timerange** (`trange` object) - Specifies where the segment is placed on the timeline.
- **source_timerange** (`trange` object, optional) - Defines which portion of the source video to use.
- **speed** (float, optional) - Playback speed multiplier. Default is 1.0.
- **clip_settings** (`ClipSettings` object, optional) - Visual adjustments for the clip.
- **volume** (float, optional) - Audio volume of the video clip (0.0 to 1.0). Default is 1.0.

### `ClipSettings` Parameters
- **alpha** (float) - Opacity (0.0 to 1.0).
- **transform_x** (float) - Horizontal translation (-1 to 1, where 0 is center, -1 is left, 1 is right).
- **transform_y** (float) - Vertical translation (-1 to 1, where 0 is center, -1 is bottom, 1 is top).
- **scale_x** (float) - Horizontal scaling (1.0 is original size).
- **scale_y** (float) - Vertical scaling (1.0 is original size).
- **rotation** (float) - Rotation angle in degrees.
- **flip_horizontal** (bool) - Whether to flip horizontally.
- **flip_vertical** (bool) - Whether to flip vertically.

### Request Example
```python
import pycapcut as cc
from pycapcut import trange, ClipSettings

# Simple video segment
video_seg = cc.VideoSegment(
    "path/to/video.mp4",
    trange("0s", "5s")
)

# Video with source trimming and speed control
video_seg2 = cc.VideoSegment(
    "path/to/video.mp4",
    trange("5s", "10s"),            # Timeline position: 5-15s
    source_timerange=trange("2s", "20s"),  # Use seconds 2-22 from source
    speed=2.0
)

# Video with clip settings
video_seg3 = cc.VideoSegment(
    "path/to/video.mp4",
    trange("0s", "8s"),
    clip_settings=ClipSettings(
        alpha=0.8,
        transform_x=0.5,
        transform_y=-0.3,
        scale_x=1.5,
        scale_y=1.5,
        rotation=15.0,
        flip_horizontal=False,
        flip_vertical=False
    ),
    volume=0.7
)

# Add segments to the video track (assuming 'script' is an initialized draft object)
# script.add_segment(video_seg)
# script.add_segment(video_seg2)
# script.add_segment(video_seg3)
```

### Response Example (Conceptual)
```json
{
  "status": "Video segment added successfully."
}
```
```

--------------------------------

### Multi-Track Operations with PyCapCut

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Shows how to manage multiple video and text tracks within a PyCapCut script. This includes creating tracks with custom ordering, adding segments to specific tracks, and creating text tracks for titles and subtitles.

```python
import pycapcut as cc
from pycapcut import trange

# Create multiple video tracks with custom ordering
script.add_track(cc.TrackType.video, "background", relative_index=1)
script.add_track(cc.TrackType.video, "foreground", relative_index=2)
script.add_track(cc.TrackType.video, "overlay", relative_index=3)

# Add segments to specific tracks
bg_video = cc.VideoSegment("background.mp4", trange("0s", "10s"))
fg_video = cc.VideoSegment("foreground.mp4", trange("0s", "10s"))
overlay = cc.VideoSegment("overlay.png", trange("2s", "5s"))

script.add_segment(bg_video, "background")
script.add_segment(fg_video, "foreground")
script.add_segment(overlay, "overlay")

# Create multiple text tracks
script.add_track(cc.TrackType.text, "titles", relative_index=1)
script.add_track(cc.TrackType.text, "subtitles", relative_index=2)

title = cc.TextSegment("Title", trange("0s", "3s"))
subtitle = cc.TextSegment("Subtitle", trange("3s", "7s"))

script.add_segment(title, "titles")
script.add_segment(subtitle, "subtitles")
```

--------------------------------

### Add Segments to Specific Tracks

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Illustrates how to add a video segment to a designated track when multiple tracks of the same type exist. This ensures segments are placed on the correct layer in the video composition.

```python
script.add_segment(video_segment, "Background")
```

--------------------------------

### Replace Media by Name in CapCut Script

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Replaces a media asset (e.g., audio, video, image) within a CapCut script by its name. This method is suitable for media with clear names and is particularly useful for image media as it typically avoids compatibility issues. Properties like trim points, volume, and playback speed of existing segments referencing the media remain unchanged.

```python
import pycapcut as cc

new_material = cc.AudioMaterial("<path to new audio file>")
script.replace_material_by_name("audio.mp3", new_material)  # Replace the material named "audio.mp3"
```

--------------------------------

### Template Mode: Load, Modify, and Replace Materials

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Illustrates template mode in PyCapCut for loading, duplicating, and modifying existing drafts. It covers replacing audio and video materials by name or segment, including options for handling segment shrinkage and extension, and replacing text content while preserving formatting.

```python
import pycapcut as cc
from pycapcut import trange, ShrinkMode, ExtendMode

# Load existing draft as template
draft_folder = cc.DraftFolder(r"C:\Users\YourName\Documents\CapCut Drafts")
script = draft_folder.load_template("Template Draft")

# Or duplicate a draft and edit the copy
script = draft_folder.duplicate_as_template(
    "Original Draft",
    "Modified Draft",
    allow_replace=True
)

# Replace material by name
new_audio = cc.AudioMaterial("new_audio.mp3")
script.replace_material_by_name("old_audio.mp3", new_audio)

# Replace material by segment with more control
audio_track = script.get_imported_track(
    cc.TrackType.audio,
    index=0                         # 0 = bottom-most audio track
)

script.replace_material_by_seg(
    audio_track,
    0,                              # First segment in track
    new_audio,
    source_timerange=trange("0s", "15s"),  # Use first 15s of new audio
    handle_shrink=ShrinkMode.cut_tail,     # Trim end if shorter
    handle_extend=ExtendMode.push_tail     # Extend and push following segments
)

# Replace text content while preserving formatting
text_track = script.get_imported_track(cc.TrackType.text, name="subtitles")
script.replace_text(text_track, 0, "New text content")

script.save()
```

--------------------------------

### Add Scene Effect to Video Segment

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Shows how to add a scene effect to a video segment using `segment.add_effect()`. The parameter order matches the effect type's annotations, which may differ from the CapCut UI.

```python
from pyJianYingDraft import VideoSceneEffectType

# Assume video_segment is an initialized VideoSegment object
video_segment: cc.VideoSegment

# Add the '全息扫描' effect, setting the '氛围' parameter to 100.0
video_segment.add_effect(VideoSceneEffectType.全息扫描,
                         [None, None, 100.0]) # Leave first two params unset; third param (氛围) is 100; others unset

```

--------------------------------

### Apply Masks to Video Segments

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Illustrates how to add various types of masks (circular, linear, rectangular) to video segments. It details parameters for mask shape, position, size, feathering, rotation, and corner rounding.

```python
import pycapcut as cc
from pycapcut import trange, MaskType

# Add circular mask
video_seg1 = cc.VideoSegment("video.mp4", trange("0s", "5s"))
video_seg1.add_mask(
    MaskType.圆形,
    center_x=0.0,                   # Center X in pixels from center
    center_y=0.0,                   # Center Y in pixels from center
    size=0.6,                       # Diameter as proportion of height
    feather=20.0,                   # Feathering (0-100)
    invert=False
)

# Add linear mask with rotation
video_seg2 = cc.VideoSegment("video2.mp4", trange("5s", "5s"))
video_seg2.add_mask(
    MaskType.线性,
    center_x=100,                   # 100 pixels right of center
    center_y=-50,                   # 50 pixels above center
    size=0.8,
    rotation=45.0                   # Rotate 45 degrees clockwise
)

# Add rectangular mask
video_seg3 = cc.VideoSegment("video3.mp4", trange("10s", "5s"))
video_seg3.add_mask(
    MaskType.矩形,
    size=0.5,                       # Height as proportion
    rect_width=0.7,                 # Width as proportion
    round_corner=30.0,              # Corner rounding (0-100)
    feather=10.0
)
```

--------------------------------

### Add Audio Segments with Effects and Keyframes using pyCapCut

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Demonstrates adding audio segments to a CapCut draft, including volume control, fade in/out effects, and dynamic volume adjustments using keyframes. It also shows how to apply audio scene effects like echo.

```python
import pycapcut as cc
from pycapcut import trange, tim
from pycapcut import AudioSceneEffectType

# Create audio segment with volume control
audio_seg = cc.AudioSegment(
    "path/to/audio.mp3",
    trange("0s", "10s"),
    volume=0.6                      # 60% volume
)

# Add fade in and fade out effects
audio_seg.add_fade("1s", "2s")      # 1s fade in, 2s fade out

# Add volume keyframes for dynamic volume changes
audio_seg.add_keyframe(tim("0s"), 0.3)      # 30% volume at start
audio_seg.add_keyframe(tim("5s"), 1.0)      # 100% volume at 5s
audio_seg.add_keyframe(tim("9s"), 0.5)      # 50% volume at 9s

# Add audio scene effects
audio_seg.add_effect(
    AudioSceneEffectType.回声,  # Echo effect
    params=[50, None, 75]           # Set parameters (see enum annotations)
)

# Add to audio track
# Assuming 'script' is an initialized Draft object
# script.add_segment(audio_seg)
```

--------------------------------

### Replace Media by Segment in PyCapCut

Source: https://github.com/guanyixuan/pycapcut/blob/main/english_readme.md

Replaces a specific segment's media in a track. Allows reselecting the source range and adjusting segment duration using ShrinkMode and ExtendMode. It requires specifying the track, segment index, new material, and optionally the source time range and handling modes.

```python
from pycapcut import trange, ShrinkMode, ExtendMode

audio_track = script.get_imported_track(
    cc.TrackType.audio,                # Select the imported audio track
    #name="audio",                         # If the track has a name, prefer using it
    index=0                                # Or locate by index; 0 means the bottom-most track of the same type
)

script.replace_material_by_seg(
    audio_track, 0, new_material,          # Select the 0-th segment in audio_track (i.e., the first segment)
    #source_timerange=None,                # If not specified, default to use the entire material
    source_timerange=trange("0s", "10s"),  # Here we select the first 10 seconds of the material (note original segment length is 5s)
    handle_shrink=ShrinkMode.cut_tail,     # If the segment shortens, move its end earlier
    handle_extend=ExtendMode.push_tail     # If the segment extends, move its end later; push following segments if needed
)
```

--------------------------------

### Adding Audio Segments

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

This section details how to add audio segments to the audio track, including volume control, fade in/out effects, audio keyframes for dynamic volume adjustments, and applying audio scene effects.

```APIDOC
## AudioSegment

### Description
Represents an audio clip to be added to the audio track. Supports volume control, fade effects, dynamic volume changes via keyframes, and audio scene effects.

### Class
`cc.AudioSegment(path, timerange, volume=1.0)`

### Parameters
- **path** (str) - Path to the audio file.
- **timerange** (`trange` object) - Specifies where the segment is placed on the timeline.
- **volume** (float, optional) - Volume level of the audio clip (0.0 to 1.0). Default is 1.0.

### Methods
- `add_fade(fade_in_duration, fade_out_duration)`: Adds fade in and/or fade out effects.
- `add_keyframe(time_us, volume)`: Adds a volume keyframe at a specific time (in microseconds) with a specified volume level.
- `add_effect(effect_type, params)`: Applies an audio scene effect.

### `AudioSceneEffectType` Enum Values
(Example: `回声`, `混响`, etc. - actual values depend on library implementation)

### Request Example
```python
import pycapcut as cc
from pycapcut import trange, tim
from pycapcut import AudioSceneEffectType

# Create audio segment
audio_seg = cc.AudioSegment(
    "path/to/audio.mp3",
    trange("0s", "10s"),
    volume=0.6
)

# Add fade effects
audio_seg.add_fade("1s", "2s")      # 1s fade in, 2s fade out

# Add volume keyframes
audio_seg.add_keyframe(tim("0s"), 0.3)      # 30% volume at start
audio_seg.add_keyframe(tim("5s"), 1.0)      # 100% volume at 5s
audio_seg.add_keyframe(tim("9s"), 0.5)      # 50% volume at 9s

# Add audio scene effect (e.g., Echo)
audio_seg.add_effect(
    AudioSceneEffectType.回声,
    params=[50, None, 75]  # Example parameters
)

# Add to audio track (assuming 'script' is an initialized draft object)
# script.add_segment(audio_seg)
```

### Response Example (Conceptual)
```json
{
  "status": "Audio segment added successfully."
}
```
```

--------------------------------

### Template Mode: Importing Tracks Between Drafts

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Explains how to import tracks from one CapCut draft to another using PyCapCut. This process involves loading a source draft as a template and then importing specific tracks (video, audio, text) into a new or existing draft, with options for offsetting, renaming, and setting layer order.

```python
import pycapcut as cc

draft_folder = cc.DraftFolder(r"C:\Users\YourName\Documents\CapCut Drafts")

# Load template to extract tracks from
template = draft_folder.load_template("Source Draft")

# Create new draft to import into
new_draft = draft_folder.create_draft("Combined Draft", 1920, 1080)

# Get specific track from template
text_track = template.get_imported_track(
    cc.TrackType.text,
    name="credits",                 # Find by name (preferred)
    index=0                         # Or by index (0 = bottom track)
)

# Import track into new draft
new_draft.import_track(
    template,
    text_track,
    offset="5s",                    # Start track 5 seconds into timeline
    new_name="imported_credits",    # Rename the imported track
    relative_index=2                # Set layer order
)

# Import multiple tracks
video_track = template.get_imported_track(cc.TrackType.video, index=0)
new_draft.import_track(template, video_track, offset="0s")

audio_track = template.get_imported_track(cc.TrackType.audio, index=0)
new_draft.import_track(template, audio_track, offset="0s")

new_draft.save()
```

--------------------------------

### Add Video Segments to CapCut Drafts with pyCapCut

Source: https://context7.com/guanyixuan/pycapcut/llms.txt

Shows how to add video segments to a CapCut draft using `VideoSegment`. It covers simple segment placement, using source trimming (`source_timerange`), speed control, and applying visual adjustments via `ClipSettings` like opacity, transformations, scaling, rotation, and volume.

```python
import pycapcut as cc
from pycapcut import trange, ClipSettings

# Simple video segment from file path
video_seg = cc.VideoSegment(
    "path/to/video.mp4",
    trange("0s", "5s")              # Place on timeline at 0-5s
)

# Video with source trimming and speed control
video_seg2 = cc.VideoSegment(
    "path/to/video.mp4",
    trange("5s", "10s"),            # Timeline position: 5-15s
    source_timerange=trange("2s", "20s"),  # Use seconds 2-22 from source
    speed=2.0                       # Play at 2x speed (10s of source in 5s)
)

# Video with clip settings (transforms and adjustments)
video_seg3 = cc.VideoSegment(
    "path/to/video.mp4",
    trange("0s", "8s"),
    clip_settings=ClipSettings(
        alpha=0.8,                  # 80% opacity
        transform_x=0.5,            # Move right (range: -1 to 1)
        transform_y=-0.3,           # Move up
        scale_x=1.5,                # Scale width 150%
        scale_y=1.5,                # Scale height 150%
        rotation=15.0,              # Rotate 15 degrees
        flip_horizontal=False,
        flip_vertical=False
    ),
    volume=0.7                      # 70% audio volume
)

# Add segments to the video track
# Assuming 'script' is an initialized Draft object
# script.add_segment(video_seg)
# script.add_segment(video_seg2)
# script.add_segment(video_seg3)
```