Developer Reference

Timeline Bundle Format

A timeline bundle is an open folder format that CineLeopard imports as a ready-to-edit project. It contains ordinary media — standard .mp4 clips and an optional voiceover audio file — alongside a timeline.json manifest that lays out the edit. Any tool can produce one; CineLeopard reads it the same way it reads any imported files.

To import: File → Import Timeline Bundle… and select the folder containing timeline.json.

Available in CineLeopard 1.2.1 and later.

Folder layout

MyBundle/                     ← the folder the user selects
├── timeline.json             ← required — the manifest
├── clips/
│   ├── shot-01.mp4           ← referenced by clips[].file (relative path)
│   └── shot-02.mp4
└── voiceover.mp3             ← optional — referenced by "voiceover"

timeline.json

A complete, valid example. Every field marked required below must be present, or the import fails.

{
  "version": 1,
  "project": "My Project",
  "scene": "",
  "aspectRatio": "16:9",
  "renderSize": { "width": 1920, "height": 1080 },
  "title": { "text": "My Title", "show": true },
  "style": {
    "subtitlesEnabled": true,
    "fontName": "HelveticaNeue-Bold",
    "fontSize": 44,
    "colorHex": "#FFFFFF",
    "position": "bottom",
    "effect": "outline"
  },
  "voiceover": "voiceover.mp3",
  "voiceoverVoice": null,
  "totalDuration": 8.0,
  "clips": [
    {
      "index": 0,
      "shotNumber": 1,
      "file": "clips/shot-01.mp4",
      "in": 0.0,
      "out": 4.0,
      "duration": 4.0,
      "caption": ""
    },
    {
      "index": 1,
      "shotNumber": 2,
      "file": "clips/shot-02.mp4",
      "in": 4.0,
      "out": 8.0,
      "duration": 4.0,
      "caption": ""
    }
  ],
  "subtitles": [
    { "text": "First line",  "start": 0.0, "duration": 4.0 },
    { "text": "Second line", "start": 4.0, "duration": 4.0 }
  ]
}

Top-level fields

Field	Type	Required	Notes
version	number	Required	Format version. Currently 1.
project	string	Required	Becomes the imported project name.
scene	string	Required	Appended to the project name when non-empty.
aspectRatio	string	Required	One of 16:9, 9:16, 4:3, 1:1. Any other value is ignored and renderSize is used.
renderSize	{ width, height }	Required	Render dimensions in pixels.
title	{ text, show }	Required	Title card. Shown only when show is true and text is non-empty.
style	object	Required	Subtitle/title styling (see below).
voiceover	string \| null	Optional	Filename of an audio file placed at time 0 on its own audio track. Omit or null for none.
voiceoverVoice	string \| null	Optional	Informational only.
totalDuration	number	Required	Total timeline length in seconds.
clips	array	Required	One entry per shot (see below). Ordered by index.
subtitles	array \| null	Optional	Timed burned-in titles (see below). Applied only when style.subtitlesEnabled is true.

style object

Field	Type	Required	Notes
subtitlesEnabled	boolean	Required	When false, the subtitles array is ignored.
fontName	string	Required	PostScript font name, e.g. HelveticaNeue-Bold.
fontSize	number	Required	Subtitle font size; the title card scales up from this.
colorHex	string	Required	Text color. Leading # is optional.
position	string	Required	top, center, or bottom.
effect	string	Required	outline draws a stroke; none and shadow draw no stroke.

Clip entries

Field	Type	Required	Notes
index	number	Required	Ordering key (clips are sorted by this).
shotNumber	number	Required	Informational only.
file	string	Required	Path relative to the bundle folder. A file that cannot be found is skipped.
in	number	Required	Where the clip sits on the timeline, in seconds (not a source in-point).
out	number	Required	Reserved — currently not read, but must be present.
duration	number	Required	How much of the source plays, in seconds. Playback always starts at the source start.
caption	string	Required	Informational only.

Subtitle entries

Field	Type	Required	Notes
text	string	Required	The line to display.
start	number	Required	Start time in seconds.
duration	number	Required	On-screen duration in seconds.

Notes

Strict manifest. Every required key must be present — even the informational ones — or the whole import fails. Optional keys (voiceover, voiceoverVoice, subtitles) may be omitted or set to null.
Clip timing. in is the clip's position on the timeline; duration is how much of the source plays from its start. out is reserved for future use.
Relative paths. file and voiceover are resolved relative to the bundle folder. Clips may live in a subfolder (e.g. clips/) or alongside the manifest.
Extra keys are ignored. Unknown fields in the manifest are skipped, so producers may include additional metadata without breaking the import.
Standard media only. Clips are ordinary video files and the voiceover is an ordinary audio file. There is no proprietary container — a bundle is just a folder you can inspect, edit, or build by hand.