Build a plugin

The plugin.json format: every timeline operation, its options and limits, with complete samples.

A plugin adds a ready-made piece of motion graphics to the timeline at the playhead: a lower third, a spotlight with an arrow, a transition style. People install it from the marketplace and apply it from the editor’s Plugins panel. One Undo removes everything it added.

Plugins are data, not code

A plugin is a plugin.json file listing timeline operations. Swamp Dragon never downloads or runs code from a plugin, so a plugin can’t reach the network, read files or see anything outside the timeline. That is why installing one is safe, and why the format below is strict.

#What a plugin can do

Operation	What it adds	Options
`add_text`	A caption on the text track	Style `lower-third`, `title` or `chapter`, text up to 500 characters, text and background color, entrance animation
`add_shape`	A motion graphic on the graphics track	Shape `arrow`, `spotlight`, `highlight`, `ellipse` or `progress`, position and size, entrance animation
`set_transition`	The same transition on every cut	Kind `fade-black`, `fade-white`, `blur`, `zoom-in` or `slide-left`, 0.05 to 1 second

A plugin holds 1 to 50 operations. Everything it adds stays editable: people can move it, retype a caption or restyle a shape in the inspector after applying it.

#The plugin.json file

Put the listing details and the operations in one JSON file. The marketplace form reads the name, description, category, icon and version from it, so you don’t type them twice.

{
  "name": "Studio lower third",
  "description": "Add an animated name and role caption at the playhead.",
  "category": "Titles",
  "icon": "lower-third",
  "version": "1.0.0",
  "operations": [
    {
      "type": "add_text",
      "start": 0,
      "end": 4,
      "text": "Name · Role",
      "style": "lower-third",
      "patch": {
        "anim": { "in": "slide-up", "out": "fade", "duration": 0.4 },
        "color": "#F8F9F1",
        "bg": "#23392A"
      }
    }
  ]
}

#Listing fields

Field	Rules
`name`	Up to 60 characters. Say what it adds, like “Studio lower third”, not “Pro Titles Pack Ultimate”
`description`	One sentence, up to 120 characters, starting with a verb
`category`	`Titles`, `Effects`, `Transitions`, `Sound` or `Integrations`
`icon`	One of `lower-third`, `pointer`, `transitions`, `zoom`, `camera`, `video`, `chapters`, `scissors`, `keyboard`, `privacy`, `brand`, `tutorial`
`version`	Three numbers, like `1.0.0`. Raise it with every change
`operations`	The operations below. You can also nest them as `"package": { "operations": [...] }`

#Operations reference

#Timing

start and end are seconds from the playhead, between 0 and 60, and end must be after start. If the video ends sooner, the item is shortened to fit. set_transition has no timing because it applies to every cut.

#add_text

{
  "type": "add_text",
  "start": 0,
  "end": 3,
  "text": "Chapter 2 · Setting up",
  "style": "chapter",
  "patch": {
    "anim": { "in": "fade", "out": "fade", "duration": 0.3 },
    "color": "#23392A",
    "bg": "#DCE7CC"
  }
}

Key	Values
`text`	1 to 500 characters. Use placeholder wording people will replace, like “Name · Role”
`style`	`lower-third`, `title` or `chapter`
`patch.color`	Text color as six-digit hex, like `#F8F9F1`
`patch.bg`	Background color as six-digit hex
`patch.anim`	Optional entrance: `in` is `slide-up`, `draw` or `fade`, `out` is `fade`, `duration` is 0.05 to 3 seconds

#add_shape

{
  "type": "add_shape",
  "start": 0,
  "end": 4,
  "shape": "arrow",
  "patch": {
    "rect": { "x": 0.18, "y": 0.72, "w": 0.18, "h": -0.2 },
    "anim": { "in": "draw", "out": "fade", "duration": 0.5 }
  }
}

rect places the shape as fractions of the output frame: x and y are the top-left corner from 0 to 1, w and h the size. An arrow is drawn from (x, y) to (x + w, y + h), so a negative h points it upwards. Values range from −1 to 1. Leave rect out to use the shape’s default position in the middle of the frame.

#set_transition

{
  "type": "set_transition",
  "id": "all",
  "transition": { "kind": "fade-black", "duration": 0.25 }
}

id is always "all". Keep transitions short; 0.2 to 0.4 seconds suits screen recordings.

#Samples

These are the official plugins in the marketplace, complete and ready to copy.

#Focus pointer

A spotlight on the middle of the frame and an arrow drawn towards it.

{
  "name": "Focus pointer",
  "description": "Spotlight the middle of the frame and draw an arrow to it.",
  "category": "Effects",
  "icon": "pointer",
  "version": "1.0.0",
  "operations": [
    { "type": "add_shape", "start": 0, "end": 4, "shape": "spotlight",
      "patch": { "rect": { "x": 0.35, "y": 0.3, "w": 0.3, "h": 0.3 } } },
    { "type": "add_shape", "start": 0, "end": 4, "shape": "arrow",
      "patch": { "rect": { "x": 0.18, "y": 0.72, "w": 0.18, "h": -0.2 },
                 "anim": { "in": "draw", "out": "fade", "duration": 0.5 } } }
  ]
}

#Smooth cuts

A short fade through black on every cut.

{
  "name": "Smooth cuts",
  "description": "Fade through black on every cut.",
  "category": "Transitions",
  "icon": "transitions",
  "version": "1.0.0",
  "operations": [
    { "type": "set_transition", "id": "all",
      "transition": { "kind": "fade-black", "duration": 0.25 } }
  ]
}

#Test before you publish

Check the file
Make sure it is valid JSON, every operation has a type, and no key is misspelled. Unknown keys are rejected, not ignored.
Try it on a real recording
Recreate the operations by hand in the editor on a short recording, at the start, middle and near the end of the timeline, in 16:9 and 9:16.
Check Undo
Applying a plugin is one undo step. After one ⌘Z, the timeline must look exactly as before.
Publish
Open your account on the website, go to Publish, choose Plugin and upload plugin.json. The upload is checked with the same rules as the app, and any error names the operation and key to fix.

Plan

Installing and applying plugins needs the Unlimited plan. Anyone can publish one.

Before you publish, read the publishing guidelines.