Referensi
Scripting
Di halaman ini
Pakai skrip kalau sebuah pekerjaan lebih mudah sebagai program: memotong di setiap beat, memasang efek di setiap hit, mengukur sebelum memotong. Klien Python nolan dan nolan-cli menjangkau operasi yang sama dengan tombol dan agen, jadi setiap perubahan dicek, dan perubahan lewat skrip menjadi satu langkah di riwayat.
Persiapan
Klien hanya butuh Python 3.10 atau lebih baru. OpenTimelineIO opsional, untuk to_otio(). App membawa klien di resources-nya, di folder bernama python-client. Di Mac, dengan app di Applications:
pip install /Applications/nolanlabs.app/Contents/Resources/python-client
Tambahkan [otio] di akhir path untuk OpenTimelineIO, atau taruh folder itu di PYTHONPATH sebagai gantinya.
Klien menemukan app yang sedang berjalan dengan sendirinya. NOLAN_URL didahulukan kalau kamu mengaturnya. Setiap request membawa secret layanan: di samping app yang sedang berjalan, klien dan CLI membacanya sendiri, jadi tidak ada yang perlu diatur. NOLAN_TOKEN menyebutkannya untuk layanan di tempat lain.
Skrip pertama
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"])
Di luar transaksi, setiap batch masuk ke timeline sebagai langkahnya sendiri. Di dalam with tl.transaction(label), batch masuk ke transaksi yang ditampilkan halaman seperti usulan agen, dan akhir blok menyimpannya sebagai satu langkah. Batch yang ditolak mesin memunculkan nolan.NolanError, dengan op_index yang menyebutkan perintahnya, dan tidak mengubah apa pun.
Panggil op apa pun
Setiap op adalah fungsi per domain, dengan field-nya sebagai argumen dan docstring yang menyebutkan satuan dan rentang tiap field. Field yang tidak ada ditolak, disertai daftar field yang ada. session di sini adalah jawaban dari nolan.connect().
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")
Field yang merupakan kata kunci Python diberi akhiran _ sebagai argumen (in_, from_). Di tl.edit dan tl.do namanya tetap. nolan.ops.CATALOGUE memuat setiap op dengan field-nya, dan nolan.ops.catalogue() menanyakannya ke editor, termasuk plug-in.
Berdasarkan yang ingin kamu lakukan
# 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")
Setiap method mengirim satu batch dan membaca timeline kembali, jadi objek menampilkan timeline sebagaimana adanya setelah perubahan. Klip yang dipotong dua mempertahankan id-nya di potongan kiri.
Buat media dari kode
Program bisa membuat apa yang ditaruhnya di timeline. Masing-masing fungsi ini menulis file ke Media/Generated milik proyek, mengimpornya, dan menaruhnya di atas yang sudah ada, tanpa menggeser apa pun, sebagai satu langkah di riwayat. Urungkan melepas klipnya, dan sumbernya tetap di 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")
| Panggilan | Menerima | Menjadi |
|---|---|---|
tl.add_image(image, at, length, track, name) |
Array (H, W), (H, W, 1), (H, W, 3), atau (H, W, 4), dalam uint8, uint16, atau float 0 sampai 1, atau gambar Pillow | PNG, 16-bit dari uint16 atau float |
tl.add_frames(frames, fps, at, length, track, name) |
Generator atau list berisi itu, atau array (T, H, W[, C]) | ProRes 422 HQ, atau 4444 dengan alpha |
tl.add_audio(samples, rate, at, length, track, name) |
Array (N,) atau (N, channels), float atau int16, atau generator berisi potongan-potongan | WAV 24-bit |
Array dan gambar itu milik programmu sendiri, jadi NumPy dan Pillow perlu kamu pasang sendiri untuk ini.
Bekerja dari 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 menjalankan skripmu dengan nolan, session, dan tl yang sudah siap, di dalam satu transaksi: disimpan sebagai satu langkah kalau selesai dengan baik, dibuang kalau memunculkan error. --dry-run menyebutkan apa yang dilakukannya lalu membuangnya. Skrip yang kamu jalankan dengan cara ini milikmu dan berjalan tanpa safe mode. python -m nolan adalah perintah yang sama.
Dari bahasa apa pun, nolan-cli add membaca data mentah dari 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
Jangkau proyek terbuka mana pun
nolan-cli --project NAME bekerja di proyek itu tanpa mengganti jendela app. Begitu juga nolan.project(name), di 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")
Ganti mode dan perbarui
s.mode adalah mode app, "lite" atau "pro", dan s.set_mode("pro") menggantinya. nolan-cli mode mencetaknya, dan nolan-cli mode lite menggantinya.
nolan-cli update # or: update check, update install
Isi setiap objek
| Objek | Isinya |
|---|---|
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 |
Membaca: 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(). Mengubah: 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). Keluaran: 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 |
Skrip milik agen
Agen juga punya klien ini. Skrip yang dijalankannya bekerja pada draf, salinan dari usulannya. Kalau skrip selesai dengan baik, semuanya masuk ke usulan sebagai satu batch. Kalau gagal, tidak ada yang disimpan, dan media yang dibuatnya ikut dibuang.
Skrip agen berjalan dalam safe mode: import terbatas, menulis hanya di folder sementaranya sendiri, tanpa proses baru, dan dengan batas waktu, CPU, dan memori. Di Windows tidak ada tampilan disk yang hanya-baca dan tidak ada batas memori. Safe mode adalah pengaman dari kesalahan, bukan batas keamanan. Lihat Batasan yang diketahui. Usulan dari skripmu sendiri punya Pakai dan Buang. Lihat Usulan.