# Scripting

> Drive nolanlabs from the nolan Python client and nolan-cli: the same ops as the buttons and the agent, each change checked, each script one step in the history.

Page: https://nolanlabs.io/docs/scripting

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:

```sh
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

```python
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.

```python
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

```python
# 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.

```python
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:

```sh
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:

```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.

```sh
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](https://nolanlabs.io/docs/known-limits). A proposal from a script of your own has **Keep** and **Discard**. See [Proposals](https://nolanlabs.io/docs/proposals).
