DOCSEARCHbyAlgolia
Submit Docs

pyJianYingDraft

repository·main·Indexed 25 days ago

https://github.com/guanyixuan/pyjianyingdraft

A lightweight Python tool for generating and exporting CapCut (Jianying) drafts to automate video editing and remixing pipelines. It supports draft generation, template mode for replacing assets and modifying text, and SRT subtitle imports. Automatic export via JianyingController is available for Windows users on CapCut versions 6.8 and below.

Tokens
1.9K
Snippets
1
Records
14
Agent score
88%

What's inside pyJianYingDraft

  1. Platform compatibility for pyJianYingDraft

    main

    The library's capabilities vary depending on your operating system:

    • Windows: Supports all features, including draft generation, template mode, and automatic export (subject to CapCut version limitations).
    • Linux/MacOS: Supports draft generation and template mode. Automatic export is NOT supported. Note that drafts generated on these platforms must still be opened and exported using the Windows version of CapCut.

  2. Quickstart with demo.py

    main

    The demo.py script creates a CapCut draft containing audio/video assets, a line of text, audio fade-in, video entrance animations, transitions, and text bubbles/effects.

    To use the demo:

    1. Locate your CapCut draft folder path (e.g., .../JianyingPro Drafts).
    2. Replace <你的草稿文件夹> in demo.py with your actual path.
    3. Run demo.py.
    4. Open CapCut and find the newly created demo draft. (You may need to enter/exit an existing draft or restart CapCut to refresh the list).

  4. Use Template Mode to generate new drafts

    main

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

    Loading a Template

    Use DraftFolder.duplicate_as_template(template_name, new_name) to create a new draft based on an existing one. This returns a ScriptFile object that you can edit.

    Replacement Options

    • Replace by Name: Replaces the material itself (e.g., an audio file). This affects all clips referencing that material but does not change the clip's timing or properties. Best for images.
    • Replace by Segment: Replaces the material of a specific segment and allows you to redefine the source time range and how the segment scales on the timeline (using ShrinkMode and ExtendMode).
    • Replace Text Content: Replaces the text within a segment while preserving all formatting.

    Extracting Material Metadata

    To find resource_ids for stickers or text effects to use in new segments, use inspect_material() on a ScriptFile or DraftFolder.

  5. Configure Video Segment Properties (Masks, Chroma, Mix Modes)

    main

    Masks

    Use VideoSegment.add_mask(mask_type, ...) to apply linear or circular masks.

    • center_x, center_y: Coordinates of the center.
    • size: The primary dimension (e.g., diameter for circles) as a ratio of the material.

    Chroma Key (Green Screen)

    Use VideoSegment.add_chroma(color, intensity, shadow, edge_smooth, spill) to remove a specific color. color must be in #RRGGBBAA format.

    Mix Modes

    Control how a video segment blends with the layer below using set_mix_mode(mix_mode_type). This requires at least two video tracks (a base and an overlay).

    Supported MixModeType values include: 正片叠底, 颜色减淡, 颜色加深, 线性加深, 柔光, 强光, 滤色, 叠加, 变亮, 变暗.

  6. Create and Configure Video and Audio Segments

    main

    Segments (Video/Audio) are created by specifying a material and a Timerange.

    Construction Methods

    1. Convenience: Pass a file path string directly to VideoSegment or AudioSegment.
    2. Traditional: Create a VideoMaterial or AudioMaterial instance first, then pass it to the segment constructor. Use this method if you need to set specific image cropping properties.

    Timing and Speed

    • trange(start, duration): A helper to create a Timerange. Note that the second argument is the duration, not the end time.
    • source_timerange: Defines which part of the original material is used.
    • speed: Sets the playback speed. If source_timerange is provided, the speed is automatically adjusted to fit the material into the target duration unless speed is also explicitly set.

  7. Apply Video Effects, Filters, and Animations

    main

    You can apply effects and filters either directly to a segment or via independent effect/filter tracks.

    Segment Effects and Filters

    • add_effect(effect_type, params): Adds an effect to a segment. params is a list where the order must match the effect's definition. Use None for default values.
    • add_filter(filter_type, intensity): Adds a filter. intensity is typically an integer (0-100).
    • add_animation(animation_type): Adds an animation (Intro, Outro, or Loop). For text, add Intro/Outro animations before Loop animations.

    Independent Tracks

    Create dedicated tracks using TrackSpec(TrackType.effect, name) or TrackSpec(TrackType.filter, name), then use script.add_effect or script.add_filter specifying the track_name.

  8. Use Template Mode with newer JianYing versions

    main
    In newer versions of JianYing (e.g., 10.8), the draft_content.json file is often not a plain-text JSON that can be read directly. To use the 'Load Template' capabilities (such as replacing media, modifying text, or importing tracks from a template), you must use DraftFolder with a fallback_loader to provide an additional reader.

  9. Batch Export Drafts via JianyingController

    main

    The project provides a way to automate the export process using JianyingController.

    Requirements & Limitations:

    • OS: Windows only.
    • Jianying Version: Supports Jianying 6 and below (Version 7+ hides controls used by this tool).
    • Dependencies: Requires the uiautomation library.
    • Permissions: Ensure you have export permissions (not restricted by VIP).
    • Behavior: The controller will bring the Jianying window to the foreground and control the cursor. It is recommended to run this during idle/night hours.

    Note: The video file is renamed to the target path only after the export process completes.

  10. Use template mode with fallback_loader for newer CapCut versions

    main

    In newer versions of CapCut (e.g., 10.8), the draft_content.json file is often not a plain-text JSON. To use template-related features like loading a draft as a template, replacing assets, or modifying text, you must use DraftFolder(..., fallback_loader=...) to connect an additional reader.

    Template mode features include:

    • Loading draft_content.json as a template.
    • Replacing audio/video assets by name.
    • Modifying text content in text clips.
    • Importing entire audio/video/text tracks from a template draft into another draft.
    • Extracting metadata for stickers, bubbles, and text effects.

  11. Automatic export limitations

    main

    Automatic export functionality depends on CapCut's visible controls.

    • CapCut 6.8 and below: Supports controlling CapCut to open specific drafts, exporting drafts to specified locations, and adjusting export resolution/frame rate.
    • CapCut 7 and above (including 10.8): Automatic export is NOT supported.

  12. Automatic Export compatibility

    main

    Automatic export functionality relies on visible controls in older versions of JianYing.

    • JianYing 5.9: Fully supports controlling JianYing to open drafts, exporting to specific locations, and adjusting resolution/frame rate.
    • JianYing 6.8 and below: Supports automatic export.
    • JianYing 10.8 (and 7+): Does NOT support automatic export (opening drafts, exporting to specific locations, or adjusting resolution/frame rate).