# mcncarl/jianying-headless architecture

> Architecture diagram of the GitHub repository mcncarl/jianying-headless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mcncarl/jianying-headless
- Repository: https://github.com/mcncarl/jianying-headless

## Overview

Jianying Headless is a local editing automation tool: users provide media and a structured plan, generate an editable Jianying draft, verify it, optionally register it in the local Jianying home page, and export a verified snapshot. Existing-project editing is a separate private-copy workflow; Windows FFmpeg export is a separate, non-editable backend. The map preserves documented fonts, motion, effects, compound edits, environment checks, and Agent entry points. Some subsystem links are based on README descriptions because their implementations were not sampled; uncertain call wiring is omitted.

Main entry points: [`skills/yichen-jianying-edit/scripts/headless_draft.py`](https://github.com/mcncarl/jianying-headless/blob/main/skills/yichen-jianying-edit/scripts/headless_draft.py) (Headless CLI), [`engine/jy14_headless.py`](https://github.com/mcncarl/jianying-headless/blob/main/engine/jy14_headless.py) (Draft Builder), [`bridge/jy14_codec.cpp`](https://github.com/mcncarl/jianying-headless/blob/main/bridge/jy14_codec.cpp) (Draft Codec), [`engine/native_edit.py`](https://github.com/mcncarl/jianying-headless/blob/main/engine/native_edit.py) (Private Copy Editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Plan and Draft"]
  node_entry["Headless CLI<br/>[headless_draft.py]"]
  node_plan["Edit Plan<br/>[plan-format.md]"]
  node_draft["Draft Builder<br/>[jy14_headless.py]"]
  node_media["Media Validation<br/>[jy14_headless.py]"]
  node_codec["Draft Codec<br/>[jy14_codec.cpp]"]
  node_io["Secure Runtime I/O<br/>[runtime_io.py]"]
  node_publish["Local Draft Registration"]
end

subgraph group_editing["Editing Features"]
  node_fonts["Local Fonts<br/>[native_fonts.py]"]
  node_motion["Keyframe Motion<br/>[native_motion.py]"]
  node_effects["Native Effects<br/>[native_effects.py]"]
  node_visual["Visual Effects"]
  node_compound["Compound Timelines<br/>[native_compound.py]"]
  node_editcopy["Private Copy Editor<br/>[native_edit.py]"]
end

subgraph group_export["Export Backends"]
  node_nativeexport["Native Export<br/>[native_export.py]"]
  node_nativeengine["Jianying Engine"]
  node_winexport["Windows Snapshot"]
  node_ffmpeg["FFmpeg Tools<br/>[ffmpeg_tools.py]"]
end

subgraph group_agent["Agent and Checks"]
  node_runtimecheck["Environment Check"]
  node_skill["Agent Skill<br/>[SKILL.md]"]
  node_starter["First-Run Helper<br/>[start_here.py]"]
end

node_user(("Editor / Agent"))

node_user -->|"runs commands"| node_entry
node_entry -->|"reads plan"| node_plan
node_entry -->|"checks environment"| node_runtimecheck
node_entry -->|"builds draft"| node_draft
node_draft -->|"validates media"| node_media
node_draft -->|"collects fonts"| node_fonts
node_draft -->|"audits effects"| node_effects
node_draft -->|"applies effects"| node_visual
node_draft -->|"applies motion"| node_motion
node_draft -->|"encodes draft data"| node_codec
node_codec -->|"uses I/O primitives"| node_io
node_entry -->|"edits private copy"| node_editcopy
node_editcopy -->|"handles compounds"| node_compound
node_entry -->|"registers draft"| node_publish
node_entry -->|"exports snapshot"| node_nativeexport
node_nativeexport -->|"invokes renderer"| node_nativeengine
node_entry -.->|"selects Windows export"| node_winexport
node_winexport -.->|"renders snapshot"| node_ffmpeg
node_user -->|"uses guidance"| node_skill
node_skill -->|"invokes workflow"| node_entry
node_user -->|"starts setup"| node_starter
node_starter -->|"prepares commands"| node_entry

click node_entry "https://github.com/mcncarl/jianying-headless/blob/main/skills/yichen-jianying-edit/scripts/headless_draft.py"
click node_plan "https://github.com/mcncarl/jianying-headless/blob/main/skills/yichen-jianying-edit/references/plan-format.md"
click node_draft "https://github.com/mcncarl/jianying-headless/blob/main/engine/jy14_headless.py"
click node_media "https://github.com/mcncarl/jianying-headless/blob/main/engine/jy14_headless.py"
click node_fonts "https://github.com/mcncarl/jianying-headless/blob/main/engine/native_fonts.py"
click node_motion "https://github.com/mcncarl/jianying-headless/blob/main/engine/native_motion.py"
click node_effects "https://github.com/mcncarl/jianying-headless/blob/main/engine/native_effects.py"
click node_visual "https://github.com/mcncarl/jianying-headless/blob/main/engine/native_visual_effects.py"
click node_compound "https://github.com/mcncarl/jianying-headless/blob/main/engine/native_compound.py"
click node_editcopy "https://github.com/mcncarl/jianying-headless/blob/main/engine/native_edit.py"
click node_codec "https://github.com/mcncarl/jianying-headless/blob/main/bridge/jy14_codec.cpp"
click node_io "https://github.com/mcncarl/jianying-headless/blob/main/bridge/runtime_io.py"
click node_nativeexport "https://github.com/mcncarl/jianying-headless/blob/main/engine/native_export.py"
click node_winexport "https://github.com/mcncarl/jianying-headless/blob/main/engine/windows_portable.py"
click node_ffmpeg "https://github.com/mcncarl/jianying-headless/blob/main/engine/ffmpeg_tools.py"
click node_runtimecheck "https://github.com/mcncarl/jianying-headless/blob/main/engine/runtime_profiles.py"
click node_skill "https://github.com/mcncarl/jianying-headless/blob/main/skills/yichen-jianying-edit/SKILL.md"
click node_starter "https://github.com/mcncarl/jianying-headless/blob/main/tools/start_here.py"
click node_publish "https://github.com/mcncarl/jianying-headless/blob/main/engine/headless_runtime.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_plan,node_draft,node_media,node_codec,node_io,node_publish toneBlue
class node_fonts,node_motion,node_effects,node_visual,node_compound,node_editcopy toneAmber
class node_nativeexport,node_nativeengine,node_winexport,node_ffmpeg toneMint
class node_runtimecheck,node_skill,node_starter toneRose
class node_user toneIndigo
```

## Components

### Plan and Draft

- [Headless CLI](https://github.com/mcncarl/jianying-headless/blob/main/skills/yichen-jianying-edit/scripts/headless_draft.py): `skills/yichen-jianying-edit/scripts/headless_draft.py`
- [Edit Plan](https://github.com/mcncarl/jianying-headless/blob/main/skills/yichen-jianying-edit/references/plan-format.md): `skills/yichen-jianying-edit/references/plan-format.md`
- [Draft Builder](https://github.com/mcncarl/jianying-headless/blob/main/engine/jy14_headless.py): `engine/jy14_headless.py`
- [Media Validation](https://github.com/mcncarl/jianying-headless/blob/main/engine/jy14_headless.py): `engine/jy14_headless.py`
- [Draft Codec](https://github.com/mcncarl/jianying-headless/blob/main/bridge/jy14_codec.cpp): `bridge/jy14_codec.cpp`
- [Secure Runtime I/O](https://github.com/mcncarl/jianying-headless/blob/main/bridge/runtime_io.py): `bridge/runtime_io.py`
- [Local Draft Registration](https://github.com/mcncarl/jianying-headless/blob/main/engine/headless_runtime.py): `engine/headless_runtime.py`

### Editing Features

- [Local Fonts](https://github.com/mcncarl/jianying-headless/blob/main/engine/native_fonts.py): `engine/native_fonts.py`
- [Keyframe Motion](https://github.com/mcncarl/jianying-headless/blob/main/engine/native_motion.py): `engine/native_motion.py`
- [Native Effects](https://github.com/mcncarl/jianying-headless/blob/main/engine/native_effects.py): `engine/native_effects.py`
- [Visual Effects](https://github.com/mcncarl/jianying-headless/blob/main/engine/native_visual_effects.py): `engine/native_visual_effects.py`
- [Compound Timelines](https://github.com/mcncarl/jianying-headless/blob/main/engine/native_compound.py): `engine/native_compound.py`
- [Private Copy Editor](https://github.com/mcncarl/jianying-headless/blob/main/engine/native_edit.py): `engine/native_edit.py`

### Export Backends

- [Native Export](https://github.com/mcncarl/jianying-headless/blob/main/engine/native_export.py): `engine/native_export.py`
- **Jianying Engine**
- [Windows Snapshot](https://github.com/mcncarl/jianying-headless/blob/main/engine/windows_portable.py): `engine/windows_portable.py`
- [FFmpeg Tools](https://github.com/mcncarl/jianying-headless/blob/main/engine/ffmpeg_tools.py): `engine/ffmpeg_tools.py`

### Agent and Checks

- [Environment Check](https://github.com/mcncarl/jianying-headless/blob/main/engine/runtime_profiles.py): `engine/runtime_profiles.py`
- [Agent Skill](https://github.com/mcncarl/jianying-headless/blob/main/skills/yichen-jianying-edit/SKILL.md): `skills/yichen-jianying-edit/SKILL.md`
- [First-Run Helper](https://github.com/mcncarl/jianying-headless/blob/main/tools/start_here.py): `tools/start_here.py`

### Other components

- **Editor / Agent**

## Connections

- Editor / Agent → Headless CLI: runs commands
- Headless CLI → Edit Plan: reads plan
- Headless CLI → Environment Check: checks environment
- Headless CLI → Draft Builder: builds draft
- Draft Builder → Media Validation: validates media
- Draft Builder → Local Fonts: collects fonts
- Draft Builder → Native Effects: audits effects
- Draft Builder → Visual Effects: applies effects
- Draft Builder → Keyframe Motion: applies motion
- Draft Builder → Draft Codec: encodes draft data
- Draft Codec → Secure Runtime I/O: uses I/O primitives
- Headless CLI → Private Copy Editor: edits private copy
- Private Copy Editor → Compound Timelines: handles compounds
- Headless CLI → Local Draft Registration: registers draft
- Headless CLI → Native Export: exports snapshot
- Native Export → Jianying Engine: invokes renderer
- Headless CLI → Windows Snapshot: selects Windows export
- Windows Snapshot → FFmpeg Tools: renders snapshot
- Editor / Agent → Agent Skill: uses guidance
- Agent Skill → Headless CLI: invokes workflow
- Editor / Agent → First-Run Helper: starts setup
- First-Run Helper → Headless CLI: prepares commands