Scripting

OmniCut exposes a LuaJIT scripting API for automating complex compositions, batch workflows, and custom effects in the Timeline Editor.

Getting started

Scripts are .lua files placed in your Scripts folder:

• Windows: %APPDATA%\OmniCut\scripts\
• macOS: ~/Library/Application Support/OmniCut/scripts/
• Linux: ~/.config/omnicut/scripts/

To run a script: Tools → Scripts → Run Script or assign it to a keyboard shortcut.

Basic example

-- hello.lua
-- Adds a text overlay to every clip on track 1

local timeline = omnicut.timeline.active()
local track = timeline:track(1)

for i, clip in ipairs(track:clips()) do
  local text = omnicut.effect.text({
    content = "Clip " .. i,
    position = { x = 0.5, y = 0.9 },
    fontSize = 32,
    color = "#ffffff",
  })
  clip:addEffect(text)
end

omnicut.log("Done! Added text to " .. #track:clips() .. " clips.")

Core API

omnicut.timeline

omnicut.timeline.active()          -- returns the active Timeline object
omnicut.timeline.new(opts)         -- creates a new timeline

Timeline object

timeline:track(index)              -- returns Track at index (1-based)
timeline:tracks()                  -- returns all tracks
timeline:duration()                -- total duration in seconds
timeline:export(opts)              -- export the timeline

Track object

track:clips()                      -- returns all Clip objects
track:addClip(path, opts)          -- add a clip from a file path
track:type()                       -- "video" | "audio"

Clip object

clip:start()                       -- start time in seconds
clip:duration()                    -- duration in seconds
clip:addEffect(effect)             -- attach an effect
clip:setProperty(key, value)       -- set a property (opacity, scale, etc.)
clip:keyframe(time, key, value)    -- add a keyframe

omnicut.effect

omnicut.effect.text(opts)          -- create a text overlay effect
omnicut.effect.colorGrade(opts)    -- create a color grade effect
omnicut.effect.transition(type, opts) -- create a transition

omnicut.converter

omnicut.converter.convert({
  input  = "/path/to/input.mp4",
  output = "/path/to/output.mp4",
  format = "mp4",
  codec  = "h265",
  crf    = 23,
})

omnicut.ai

omnicut.ai.upscale({
  input  = "/path/to/input.mp4",
  output = "/path/to/output.mp4",
  scale  = 2,
  model  = "enhanced",
})

omnicut.ai.captions({
  input    = "/path/to/input.mp4",
  output   = "/path/to/output.srt",
  language = "en",
})

Batch processing example

-- batch_convert.lua
-- Convert all .mov files in a folder to H.265 MP4

local input_dir  = "/Users/me/footage/"
local output_dir = "/Users/me/converted/"

local files = omnicut.fs.glob(input_dir .. "*.mov")

for _, file in ipairs(files) do
  local name = omnicut.fs.basename(file, ".mov")
  omnicut.converter.convert({
    input  = file,
    output = output_dir .. name .. ".mp4",
    format = "mp4",
    codec  = "h265",
    crf    = 22,
  })
  omnicut.log("Converted: " .. name)
end

Script editor

OmniCut includes a built-in script editor with syntax highlighting and a console output panel. Open it via Tools → Script Editor.