EDL Format Explained: Required Fields for Video Editing in video-use

The EDL (Edit Decision List) format in video-use is a JSON schema that defines how raw source clips are combined into a final edit through required fields including version, sources, ranges, and optional grading, overlays, and subtitle specifications.

The EDL format provides the declarative backbone for the video-use rendering engine, allowing editors to specify precise cut points, color grading, and compositing instructions in machine-readable JSON. According to the specification in SKILL.md and the implementation in helpers/render.py, the EDL acts as a contract between editorial decisions and automated video generation.

Required Top-Level Fields in the EDL Format

The video-use engine requires specific top-level keys to construct a valid edit timeline. These fields are validated by the rendering pipeline before any media processing begins.

version

The version field is an integer specifying the EDL schema version. The current implementation requires version 1 as defined in SKILL.md at line 268.

sources

The sources object maps unique identifiers to video file paths. Each key represents a source ID referenced in the ranges array, while the value is an absolute or relative path resolved via helpers/render.py → resolve_path.

{
  "sources": {
    "C0103": "/abs/path/C0103.MP4",
    "B0021": "/abs/path/B0021.MP4"
  }
}

ranges

The ranges array contains the ordered sequence of cut segments. Each range object must include:

• source: ID matching a key in the sources object
• start: Float value in seconds
• end: Float value in seconds

Optional but recommended fields include beat for semantic labels like HOOK, quote for transcript excerpts, and reason for editorial justification. The rendering logic in helpers/render.py extracts these segments and concatenates them sequentially.

{
  "ranges": [
    {
      "source": "C0103",
      "start": 2.42,
      "end": 6.85,
      "beat": "HOOK",
      "quote": "Welcome to the future of video editing",
      "reason": "Cleanest delivery, stops before slip at 38.46"
    }
  ]
}

Optional Fields for Advanced Editing

Beyond the minimum requirements, the EDL format supports professional grading, compositing, and subtitle workflows.

grade

The grade field accepts a preset name (e.g., warm_cinematic), a raw ffmpeg filter string, or the value auto to trigger per-segment auto-grading. When set to auto, helpers/render.py expands this to a sentinel value and invokes auto_grade_for_clip for each segment.

{
  "grade": "auto"
}

overlays

The optional overlays array enables compositing of animation or video elements on top of the base edit. Each overlay object requires file (path relative to the edit directory), start_in_output (float in seconds), and duration (float in seconds). The implementation in helpers/render.py (around line 640) shifts each overlay's PTS so frame 0 aligns with the specified start time.

{
  "overlays": [
    {
      "file": "edit/animations/slot_1/render.mp4",
      "start_in_output": 0.0,
      "duration": 5.0
    }
  ]
}

subtitles

The optional subtitles field specifies a path (relative to the edit directory) to a master SRT file. If provided, helpers/render.py burns these subtitles into the final output during the rendering phase.

{
  "subtitles": "edit/master.srt"
}

total_duration_s

While not strictly required for rendering, total_duration_s provides an expected duration in seconds for validation and reporting purposes, helping editors verify that the assembled timeline matches their target length.

Complete EDL Format Example

Here is a minimal yet functional EDL that demonstrates the required structure alongside optional advanced features. This JSON is directly consumable by the video-use rendering pipeline.

{
  "version": 1,
  "sources": {
    "C0103": "/abs/path/C0103.MP4",
    "B0021": "/abs/path/B0021.MP4"
  },
  "ranges": [
    {
      "source": "C0103",
      "start": 2.42,
      "end": 6.85,
      "beat": "HOOK",
      "quote": "Welcome to the future of video editing",
      "reason": "Cleanest delivery, stops before slip at 38.46"
    },
    {
      "source": "B0021",
      "start": 0.0,
      "end": 5.0,
      "beat": "INTRO"
    }
  ],
  "grade": "auto",
  "overlays": [
    {
      "file": "edit/animations/slot_1/render.mp4",
      "start_in_output": 0.0,
      "duration": 5.0
    }
  ],
  "subtitles": "edit/master.srt",
  "total_duration_s": 87.4
}

Rendering the EDL with video-use

Once your EDL JSON is complete, pass it to the rendering helper to generate the final video. The helpers/render.py script handles path resolution, segment extraction, grading application, concatenation, and overlay compositing.

python helpers/render.py edl.json -o final.mp4

This command invokes the rendering logic described in helpers/render.py lines 15-19, processing the EDL through the full pipeline.

How the Rendering Pipeline Validates EDL Fields

The helpers/render.py implementation enforces strict validation of the EDL structure. It first checks for the presence of sources and ranges, then resolves each source path through resolve_path, extracts the specified time ranges, applies the grading filters, and concatenates the segments in order. Overlays are processed separately with PTS adjustments to align with the output timeline, and subtitles are burned in if the field is present.

Summary

• The EDL format in video-use is a JSON-based Edit Decision List that declaratively describes video edits.
• Required fields are version (integer), sources (object mapping IDs to paths), and ranges (array of cut segments with start/end times).
• Optional fields include grade (color grading presets or auto-grading), overlays (compositing instructions), subtitles (SRT path), and total_duration_s (validation metric).
• The rendering pipeline in helpers/render.py validates, processes, and assembles the final video from the EDL specification.
• All paths in sources are resolved via resolve_path, while overlay timing is synchronized by shifting PTS values in the compositing stage.

Frequently Asked Questions

What is the EDL format used for in video-use?

The EDL format serves as a machine-readable instruction set that tells the video-use rendering engine how to assemble raw source clips into a final edited video. It specifies cut points, color grading, overlays, and subtitles in a structured JSON format interpreted by helpers/render.py.

Is the grade field required in the EDL format?

No, the grade field is optional. If omitted, no grading is applied. You can specify a preset name like warm_cinematic, a raw ffmpeg filter string, or set it to auto to trigger per-segment auto-grading via the auto_grade_for_clip function in helpers/render.py.

How does video-use handle overlay timing in the EDL format?

Each overlay object in the overlays array includes start_in_output and duration fields. During rendering, helpers/render.py adjusts the overlay's presentation timestamp (PTS) so that frame 0 of the overlay aligns with the specified start_in_output time in the final timeline, typically around line 640 of the rendering script.

Can I use relative paths in the EDL sources field?

Yes, the sources field accepts both absolute and relative paths. The rendering engine resolves all paths through the resolve_path function in helpers/render.py, allowing flexibility in how source files are referenced relative to the EDL file location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}