# Scripts

> Controle o nolanlabs pelo cliente Python nolan e pelo nolan-cli: as mesmas operações dos botões e do agente, cada mudança checada, cada script um passo no histórico.

Page: https://nolanlabs.io/pt-br/docs/scripting

Use um script quando um trabalho fica mais fácil como programa: cortar em cada batida, pôr um efeito em cada acento, medir antes de cortar. O cliente Python `nolan` e o `nolan-cli` alcançam as mesmas operações dos botões e do agente, então cada mudança é checada, e uma mudança por script é um passo no histórico.

## Configure

O cliente só precisa de Python 3.10 ou posterior. O OpenTimelineIO é opcional, para `to_otio()`. O app traz o cliente nos recursos dele, numa pasta chamada `python-client`. No Mac, com o app em Aplicativos:

```sh
pip install /Applications/nolanlabs.app/Contents/Resources/python-client
```

Acrescente `[otio]` ao fim do caminho para o OpenTimelineIO, ou ponha a pasta no `PYTHONPATH`.

O cliente encontra sozinho o app em execução. `NOLAN_URL` tem prioridade se você a definir. Cada requisição leva o segredo do serviço: ao lado do app em execução, o cliente e a CLI o leem sozinhos, então não há nada para definir. `NOLAN_TOKEN` o informa para um serviço em outro lugar.

## Um primeiro 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"])
```

Fora de uma transação, cada lote cai na timeline como um passo próprio. Dentro de `with tl.transaction(label)`, os lotes vão para uma transação que a página mostra como uma proposta do agente, e o fim do bloco a mantém como um passo só. Um lote que o motor recusa levanta `nolan.NolanError`, com `op_index` indicando o comando, e não muda nada.

## Chame qualquer operação

Cada operação é uma função por domínio, com os campos como argumentos e uma docstring que diz a unidade e a faixa de cada um. Um campo que não existe é recusado com a lista dos campos que existem. `session` aqui é o que `nolan.connect()` devolve.

```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")
```

Campos que são palavras reservadas do Python levam um `_` no fim como argumentos (`in_`, `from_`). Em `tl.edit` e `tl.do` eles mantêm os nomes. `nolan.ops.CATALOGUE` tem todas as operações com os campos, e `nolan.ops.catalogue()` pergunta ao editor, com os plug-ins incluídos.

## Pelo que você quer fazer

```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")
```

Cada método envia um lote e lê a timeline de volta, então os objetos mostram a timeline como ela fica depois da mudança. Um clipe cortado em dois mantém o id na parte da esquerda.

## Gere mídia por código

Um programa pode gerar o que coloca na timeline. Cada um destes grava o arquivo em `Media/Generated` do projeto, importa e o coloca sobre o que já está lá, sem mover nada, como um passo no histórico. Desfazer tira o clipe, e a fonte fica no 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")
```

| Chamada | Recebe | Vira |
| --- | --- | --- |
| `tl.add_image(image, at, length, track, name)` | Um array de (H, W), (H, W, 1), (H, W, 3) ou (H, W, 4), em uint8, uint16 ou float de 0 a 1, ou uma imagem Pillow | Um PNG, de 16 bits a partir de uint16 ou float |
| `tl.add_frames(frames, fps, at, length, track, name)` | Um gerador ou uma lista desses, ou um array (T, H, W[, C]) | ProRes 422 HQ, ou 4444 com alfa |
| `tl.add_audio(samples, rate, at, length, track, name)` | Um array (N,) ou (N, channels), float ou int16, ou um gerador de blocos | Um WAV de 24 bits |

Os arrays e as imagens são do seu programa, então instalar o NumPy e o Pillow para isso fica por sua conta.

## Trabalhe pelo 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` executa o seu script com `nolan`, `session` e `tl` prontos, dentro de uma transação: mantida como um passo quando termina bem, descartada quando levanta um erro. `--dry-run` diz o que ele fez e descarta. Os scripts que você roda assim são seus e rodam sem modo seguro. `python -m nolan` é o mesmo comando.

De qualquer linguagem, `nolan-cli add` lê dados brutos de um 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
```

## Alcance qualquer projeto aberto

`nolan-cli --project NAME` trabalha naquele projeto sem trocar a janela do app. O mesmo vale para `nolan.project(name)`, em 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")
```

## Troque de modo e atualize

`s.mode` é o modo do app, `"lite"` ou `"pro"`, e `s.set_mode("pro")` o troca. `nolan-cli mode` o mostra, e `nolan-cli mode lite` troca.

```sh
nolan-cli update          # or: update check, update install
```

## O que cada objeto tem

| Objeto | O que tem |
| --- | --- |
| `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` | Leitura: `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()`. Mudança: `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)`. Saída: `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` |

## Os scripts do agente

O agente também tem este cliente. Um script que ele roda trabalha sobre um rascunho, uma cópia da proposta dele. Quando o script termina bem, tudo entra na proposta como um lote só. Quando falha, nada é mantido, e a mídia que ele gerou vai embora também.

Os scripts do agente rodam em modo seguro: imports limitados, gravação só dentro da própria pasta temporária, nenhum processo novo, e limites de tempo, CPU e memória. No Windows não há visão somente leitura do disco nem limite de memória. O modo seguro é uma proteção contra erros, não uma barreira de segurança. Veja [Limites conhecidos](https://nolanlabs.io/pt-br/docs/known-limits). Uma proposta vinda de um script seu tem **Manter** e **Descartar**. Veja [Propostas](https://nolanlabs.io/pt-br/docs/proposals).
