nolanlabs

Scripts

Nesta página
  1. Configure
  2. Um primeiro script
  3. Chame qualquer operação
  4. Pelo que você quer fazer
  5. Gere mídia por código
  6. Trabalhe pelo shell
  7. Alcance qualquer projeto aberto
  8. Troque de modo e atualize
  9. O que cada objeto tem
  10. Os scripts do agente

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.

Documentação

↑↓ Mover↵ Abrir