Referência
Scripts
Nesta página
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:
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
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.
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
# 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.
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:
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:
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.
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. Uma proposta vinda de um script seu tem Manter e Descartar. Veja Propostas.