DOCSEARCHbyAlgolia
Submit Docs

JianYing-Api

repository·main·Indexed 42 days ago

https://github.com/jianying-automation/jianyingapi

A Python-based automation wrapper for JianYing (CapCut) Pro that uses the uiautomation library to programmatically manage video drafts. It enables developers to create projects, import media, manage tracks, apply video effects, and manipulate draft_content.json and draft_meta_info.json files.

Tokens
2.7K
Snippets
9
Records
13
Agent score
4%

What's inside JianYing-Api

  1. Automate JianYing Pro using JianYing-Api

    main

    JianYing-Api is a third-party automation tool for JianYing (CapCut) Pro that uses the uiautomation library to perform operations. It allows developers to programmatically create drafts, import media, add tracks, apply effects, and save projects.

    Note: The project is highly dependent on the version of the JianYing app. Rapid app updates may cause existing automation logic to break. Users are encouraged to build upon the existing codebase to maintain compatibility.

  2. Understand Jianying Draft File Structure

    main

    A Jianying draft consists of two primary files that work together:

    1. draft_content.json: Contains most operations performed on the timeline.
    2. draft_meta_info.json: Contains an overview of the project and resources within the media library.

    Note: Jianying uses a media library system. Local media and official resource calls are handled differently than in traditional editors like Premiere Pro or DaVinci Resolve.

  4. Configure Proxy Settings

    main

    To enable proxy usage, create a file named draft_agency_config.json in your project directory with the following structure:

    ```json
{
    "marterials": null,
    "use_converter": true, 
    "video_resolution": 540 
}

    Keys:

    • marterials: Set to null or specific materials.
    • use_converter: Boolean indicating whether to use a proxy.
    • video_resolution: Proxy resolution (e.g., 540 or 720).

  5. Create a new draft and manage tracks

    main

    To start a new automation task, use Drafts.Create_New_Drafts(path) to initialize a project at a specific directory. Once the draft object is created, you can use the d.Content.NewTrack(TrackType=...) method to create new tracks.

    Supported TrackType values include:

    • video
    • effect
    import Drafts

# Create a new project at the specified path
d = Drafts.Create_New_Drafts(r"E:\SB\JianyingPro Drafts/PulpFiction")

# Create a video track
video_track = d.Content.NewTrack(TrackType="video")

# Create an effect track
efect_track = d.Content.NewTrack(TrackType="effect")

  6. Add video effects to a track

    main

    To add effects, you must first add the effect as a material using d.Content.AddMaterial with Mtype="video_effects", then place it on an effect track using d.Content.Add2Track.

    Required keys for AddMaterial (video effects):

    • apply_target_type: The target type for the effect (e.g., 2).
    • effect_id: The specific ID of the effect.
    • effect_resource_id: The resource ID for the effect.
    • type: Set to "video_effect".

    Required keys for Add2Track (effects):

    • render_index: The rendering order/layer.
    • target_timerange: Defines the duration and start position of the effect on the timeline.
    import uuid

effect_name = "蓝色丝印"
effect_resource_id = "7131985730791805448"
effect_id = "4097661"

effect_material_id = str(uuid.uuid3(namespace=uuid.NAMESPACE_DNS, name=effect_name + "_material"))
effect_track_id = str(uuid.uuid3(namespace=uuid.NAMESPACE_DNS, name=effect_name + "_track"))

# 1. Add effect material
d.Content.AddMaterial(Mtype="video_effects", Content={
    "apply_target_type": 2,
    "effect_id": effect_id,
    "id": effect_material_id,
    "name": effect_name,
    "render_index": 0,
    "effect_resource_id": effect_resource_id,
    "type": "video_effect",
    "value": 1
})

# 2. Add effect to track
d.Content.Add2Track(Track_id=efect_track["id"], Content={
    "id": effect_track_id,
    "material_id": effect_material_id,
    "render_index": 11000,
    "speed": 1,
    "target_timerange": {
        "duration": 500600000,
        "start": 0
    },
    "visible": True,
    "volume": 1
})

  7. Generate IDs for Draft Elements

    main

    IDs act as the skeleton connecting all parts of the draft. When creating new elements, it is recommended to use UUIDs. You can generate two types of IDs using Python:

    1. Time-based IDs: Use uuid.uuid1().
    2. File-based IDs: Use uuid.uuid3(namespace=uuid.namespace, name="xxx").

    As long as the relationships between these IDs are maintained correctly, the system will function without error.

    import uuid

# Time-based ID
time_id = uuid.uuid1()

# File-based ID
file_id = uuid.uuid3(uuid.NAMESPACE_DNS, "xxx")

  8. Import and add video material to a track

    main

    Adding video material involves three steps:

    1. Import to Library: Use d.Meta.Import2Lib(path=..., metetype="video") to register the file in the JianYing library.
    2. Add Material: Use d.Content.AddMaterial(Mtype="videos", Content={...}) to define the material metadata (ID, name, path, etc.).
    3. Add to Track: Use d.Content.Add2Track(Track_id=..., Content={...}) to place the material on a specific track. You must define source_timerange (the segment from the original file) and target_timerange (where it sits on the timeline).
    import uuid

video_path = r"E:/Pulp Fiction 1994 720p BluRay DTS x264-SilverTorrentHD.mkv"
video_name = "PulpFiction"

# Generate unique IDs using uuid3
video_material_id = str(uuid.uuid3(namespace=uuid.NAMESPACE_DNS, name=video_name + "_material"))
video_track_id = str(uuid.uuid3(namespace=uuid.NAMESPACE_DNS, name=video_name + "_track"))

# 1. Import to library
d.Meta.Import2Lib(path=video_path, metetype="video")

# 2. Add material metadata
d.Content.AddMaterial(Mtype="videos", Content={
    "category_name": "local",
    "extra_type_option": 0,
    "has_audio": True,
    "id": video_material_id,
    "material_name": video_name,
    "path": video_path,
    "type": "video"
})

# 3. Add to track with timing
d.Content.Add2Track(Track_id=video_track["id"], Content={
    "id": video_track_id,
    "material_id": video_material_id,
    "visible": True,
    "volume": 1,
    "source_timerange": {
        "duration": 605000000,
        "start": 2050633333
    },
    "target_timerange": {
        "duration": 605000000,
        "start": 0
    }
})

  11. Reference Effect (特效) Data Structure

    main

    Effects are recorded within the Materials section of the metadata.

    |K|V|Des|
|:--:|:--:|:--:|
|apply_target_type|2|必要|
|id|E5E73C6B-8263-4896-957E-8CAB9B044940|id|
|name|蓝色丝印|特效名称|
|resource_id|7131985730791805448|资源id|
|type|video_effect||

  12. Reference `draft_meta_info.json` Root Keys

    main

    The root level of draft_meta_info.json contains project-wide settings and paths. You do not need to complete every field; Jianying will fill in missing fields if the necessary ones are provided.

    |K|V|Des|
|:--:|:--:|:--:|
|draft_fold_path|`C:/xxx/JianyingPro Drafts/HelloWorld`|草稿文件夹的地址(Root)|
|draft_cover|`draft_cover.jpg`|草稿文件封面图(相对路径)|
|draft_name|`HelloWorld`|草稿文件名|
|draft_removable_storage_device|`C:`|移动硬盘盘符|
|draft_root_path|`C:/xxx/JianyingPro Drafts/`|草稿文件夹父目录路径|
|canvas_config|`{"height":1080,"ratio":"original","width":1920}`|草稿的比率|
|color_space|0|色彩空间|
|fps|30|帧率|