Reference
Scripting
On this page
Use a script when a job is easier as a program: cutting to every beat, putting an effect on every hit, measuring before you cut. The nolan Python client and nolan-cli reach the same ops as the buttons and the agent, so every change is checked, and a scripted change is one step in the history.
Set up
The client needs nothing but Python 3.10 or later. OpenTimelineIO is optional, for to_otio(). The app carries the client in its resources, in a folder named python-client. On a Mac, with the app in Applications:
pip install /Applications/nolanlabs.app/Contents/Resources/python-client
Add [otio] to the end of the path for OpenTimelineIO, or put the folder on PYTHONPATH instead.
The client finds the running app by itself. NOLAN_URL wins if you set it. Every request carries the service’s secret: beside the running app the client and the CLI read it themselves, so there’s nothing to set. NOLAN_TOKEN names it for a service elsewhere.
A first script
import nolan
s = nolan.connect() # NOLAN_URL, or http://127.0.0.1:8790
tl = s.timeline() # NOLAN_TIMELINE, or the first timeline
music = s.sources("Music")[0]["id"]
beats = s.sound(music, fps=tl.fps)["beats"]
with tl.transaction("Cut to the beat"): # one step in the history; dropped if the block raises
for clip, beat in zip(tl.track("V1").items, beats[4::4]):
if clip.end > beat:
clip.trim("tail", beat - clip.end, ripple=True)
tl.track("V1").items[0].effect("grain", 0.3)
print(tl.summary()["mean_shot_s"])
Outside a transaction, each batch lands on the timeline as its own step. Inside with tl.transaction(label), the batches go to a transaction the page shows like an agent’s proposal, and the block’s end keeps it as one step. A batch the engine refuses raises nolan.NolanError, with op_index naming the command, and changes nothing.
Call any op
Every op is a function by domain, with its fields as arguments and a docstring saying each one’s unit and range. A field that doesn’t exist is refused with the fields there are. session here is what nolan.connect() answers.
nolan.ops.clip.trim(clip="c4", edge="tail", delta=-6, tl=tl)
nolan.ops.text.add(at=24, len=48, text="NEXT LEVEL", look="impact", y=0.2, in_="slam", in_len=6, tl=tl)
beats = nolan.analyse.sound("Rocket")["beats"] # nolan.analyse and nolan.track are nolan.ops.analyse and .track
tl.edit([{"op": "clip.dissolve", "clip": "c5", "frames": 12},
{"op": "grade.primary", "clip": "c5", "temp": 0.15}], name="Warmer")
tl.do("timeline.marker_add", at=96, name="Drop")
session.op("deliver.render", preset="prores", path="/out/master.mov")
Fields that are Python words take a trailing _ as arguments (in_, from_). In tl.edit and tl.do they keep their names. nolan.ops.CATALOGUE has every op with its fields, and nolan.ops.catalogue() asks the editor, plug-ins included.
By what you want to do
# Bring things in, and cut them
s.import_media(["/footage/a.mov", "/footage/b.mov"])
tl.insert("a", 0, length=48, overwrite=True)
# Grade with wheels and curves, and a LUT
clip.grade(lift=[0, 0, .02], gain=[.05, 0, -.03], curves={"m": [[0, 0], [.5, .55], [1, 1]]})
clip.grade(lut="film.cube", lut_mix=.6) # in the project's LUTs folder, or a full path
# Read the frame from the originals, and check the numbers
print(tl.scopes(at=48)["luma"])
# Mask, track and move the mask with what it follows
clip.set(masks=[{"shape": "ellipse", "x": .5, "y": .4, "w": .3, "h": .5, "feather": .05, "invert": True}])
path = s.track(clip.src, clip.source_in, clip.source_in + clip.length, x=.5, y=.4, w=.3, h=.5, mode="move")
clip.track_apply(path, target="mask:0")
# Words on an arc, letter by letter
tl.title("STUNT SHOW", 0, 72, path=[[.2, .6], [.5, .4], [.8, .6]], by="char",
per=[{"prop": "opacity", "stagger": 2, "keys": [{"f": 0, "v": 0}, {"f": 8, "v": 1}]}])
# Sound
clip.set(afx=[{"kind": "highpass", "freq": 80}, {"kind": "reverb", "size": .4, "mix": .15}], pan=-.2)
# Cameras
angles = s.sync(["cam_a", "cam_b"])
tl.multicam(angles, at=0, length=240)
# Deliver anything
tl.render("/out/master.mov", preset="prores", profile="hq", audio="pcm24", loudness=-16)
tl.render("/out/frames", sequence="exr", alpha=True)
tl.render("/out/hdr.mov", codec="prores", profile="hq", hdr="pq") # cache=True does nothing for HDR or EXR
tl.export("fcpxml", "/out/cut.fcpxml")
Each method sends one batch and reads the timeline back, so objects show the timeline as it is after the change. A clip cut in two keeps its id on the left piece.
Make media from code
A program can make what it puts on the timeline. Each of these writes the file into the project’s Media/Generated, imports it and lays it over what’s there, moving nothing, as one step in the history. Undo takes the clip off, and the source stays in the pool.
import numpy as np
from PIL import Image, ImageDraw
# A picture: an array or a Pillow image, for 5 seconds at the end of the track unless you say
picture = Image.new("RGBA", (tl.width, tl.height), (0, 0, 0, 0))
ImageDraw.Draw(picture).ellipse((200, 100, 600, 500), fill=(255, 80, 0, 255))
tl.add_image(picture, at=0, length=48, track="V2", name="Disc")
# Moving pictures: a generator is sent as it makes them, so length costs no memory
def noise():
rng = np.random.default_rng(7)
for i in range(96):
yield rng.random((tl.height, tl.width, 3)) * (i / 96)
tl.add_frames(noise(), fps=tl.fps, at=48, name="Noise")
# Sound: float from -1 to 1, or int16; one channel or (samples, channels)
t = np.arange(96000) / 48000
tl.add_audio(np.sin(2 * np.pi * 110 * t) * 0.3, rate=48000, at=0, track="A2", name="Hum")
| Call | Takes | Becomes |
|---|---|---|
tl.add_image(image, at, length, track, name) |
An array of (H, W), (H, W, 1), (H, W, 3) or (H, W, 4), in uint8, uint16 or float 0 to 1, or a Pillow image | A PNG, 16-bit from uint16 or float |
tl.add_frames(frames, fps, at, length, track, name) |
A generator or list of those, or an array (T, H, W[, C]) | ProRes 422 HQ, or 4444 with alpha |
tl.add_audio(samples, rate, at, length, track, name) |
An array (N,) or (N, channels), float or int16, or a generator of chunks | A 24-bit WAV |
The arrays and images are your program’s own, so NumPy and Pillow are yours to install for these.
Work from a shell
nolan-cli [--url URL] [--project NAME|FOLDER|ID] [--timeline ID] COMMAND
projects | open PATH [--force] | close [NAME] [--stop] the projects open at once
runs [--state S] | ask PROMPT [--thread T] [--wait] the agent of --project (or the one the app shows)
answer RUN OPTION [--note N] | cancel RUN
host status | host restart|stop [--when idle|now] | host cancel
run [--label L] [--dry-run] script.py [-- args] a script, in one transaction
summary | ops [WORDS] | lookup WORDS read; ops lists every op with its fields
op NAME [FIELD=JSON ...] [--dry-run] any op: op clip.trim clip=c4 edge=tail delta=-6
inspect WHAT [FIELD=JSON ...] the agent's inspect tool: inspect clips track=V1
look WHAT [FIELD=JSON ...] [--out DIR] the agent's look tool; pictures saved to DIR, their paths printed
wait ID [--timeout S] | busy | background wait for a script in the background (r1) or a render (j1); what still runs
apply '[{"op": "split", "at": 48}]' [--dry-run] any engine commands
clip ID [FIELD=JSON ...] read or change a clip
render [--out F] [--preset P] [--from A] [--to B] [FIELD=JSON ...] waits for it
export otio|fcpxml|edl|aaf [OUT] [--track V2] import FILE
scopes [--at F] | cache [--from A --to B --wait] sheet OUT.jpg [--count N]
fonts | font FILE | relink [--folder D | --src ID --path F]
add image|frames|audio [--name N] [--at F] [--length L] [--track V2]
[--width W --height H --pix rgb24 --fps F | --rate R --channels C --format f32le] < RAW
run executes your script with nolan, session and tl ready, inside one transaction: kept as one step when it ends well, dropped when it raises. --dry-run says what it did and drops it. Scripts you run this way are yours and run without safe mode. python -m nolan is the same command.
From any language, nolan-cli add reads raw data from a pipe:
my_renderer | nolan-cli add frames --width 1920 --height 1080 --pix rgb24 --fps 24 --track V2 --name Sim
my_synth | nolan-cli add audio --rate 48000 --channels 2 --format f32le --at 96
Reach any open project
nolan-cli --project NAME works in that project without switching the app’s window. So does nolan.project(name), in Python:
import nolan
teaser = nolan.project("Launch Teaser")
teaser.timeline().marker(48, "From the script") # edits that project, whatever the app's window shows
run = teaser.agent.ask("Tighten the second half") # a Run: id, thread, status (running, paused, done, failed, cancelled), and what it waits on you for
run.wait() # waits through a restart: a paused run carries on by itself
for r in nolan.runs(state="waiting"): # every open project's runs that wait for an answer
print(r.project, r.title)
teaser.close(stop=False) # refused while its work goes, unless stop=True
nolan.host.status(); nolan.host.restart(when="idle")
Switch modes and update
s.mode is the app’s mode, "lite" or "pro", and s.set_mode("pro") switches it. nolan-cli mode prints it, and nolan-cli mode lite switches.
nolan-cli update # or: update check, update install
What each object has
| Object | What it has |
|---|---|
Session |
project, timelines, timeline(id), new_timeline, new_project, open, import_media, add_media, sources(q), sound, sfx, sync(srcs, by), motion, track, shake, subject, key_colour, relink, fonts(), import_font(path), import_timeline(path), set_proxy(size), set_agent(access, ask_me), style(), set_style(user, project), plugins(), save_generator(name, code, params), op(name, **fields), run_script(code) |
Timeline |
Reading: fps, width, height, length, markers, tracks, track(id), clips, clip(id), at(frame, track), summary(), checks(), frame(at, path), still(at, path), contact_sheet(path), scopes(at, pictures, hdr), cache(frm, to, wait), mix(), watch(). Changing: edit(ops, name), do(name, **fields), apply(commands), op(command, **fields), dry_run(commands), transaction(label), undo(), insert, lay, add_image, add_frames, add_audio, split, title, marker, add_track, compound(frm, to), decompose(clip), multicam(angles, at). Out: render(path, preset, frm, to, **deliver), export(kind, path, track), otio_json(), to_otio() |
Track |
id, kind, name, items, set(**fields) |
Clip |
id, track, src, at, end, length, source_in, title, anim, fx, speed; trim, roll, slip, slide, move, split, delete, set, keyframe, effect, motion, transition, grade, track_matte, track_apply, stabilize |
The agent’s scripts
The agent has this client too. A script it runs works on a draft, a copy of its proposal. When the script ends well, everything goes into the proposal as one batch. When it fails, nothing is kept, and the media it made goes too.
The agent’s scripts run in safe mode: limited imports, writes only inside their own temporary folder, no new process, and limits on time, CPU and memory. On Windows there’s no read-only view of the disk and no memory limit. Safe mode is a guard against mistakes, not a security boundary. See Known limits. A proposal from a script of your own has Keep and Discard. See Proposals.