Skip to Content
Starlight

Video versions

A version is a new file that Starlight makes from one of your video clips, for example a copy with less noise. The scene still names the original clip. Each layer picks the original or one of its versions.

Words on this page

Original
The clip as you imported it, in assets/. The scene file always names it.
Version
A new file made from the original, for example with less noise or smoother gradients. It has the same size on the surface and the same length. Its name is the operation and a short code, for example denoise-41c0e9aa.
Active version
The version a layer shows now. A layer with no active version shows the original.
  • A version never moves or resizes a layer. It draws exactly where the original draws, also when its file is bigger.
  • Effects, colour, masks and blend modes work on a version the same way as on the original.
  • Only a clip in the project's assets/ folder can have versions. A linked file (Linked media) and a still image cannot.

Make a version

  1. Right-click a video layer on the canvas, or its node in the node graph.
  2. Choose make version ›.
  3. Pick one of the list. Hold the pointer over a row to read what it does.
  4. The job starts at once. It runs on this computer and costs nothing. (A row that ends in … costs money. It opens a window with the price first: see Upscale to surface · LTX.)
  5. Open the Generations panel (⇧G / Shift+G) to see the job. Its row shows the progress, the time left and $0 · local.
In make version ›What it does
denoise · lightRemoves fine grain and noise. Keeps detail. Fast.
denoise · strongRemoves heavy noise that moves between frames. It can soften fine detail.
deflicker + denoiseEvens out brightness that pulses from frame to frame, then removes light noise.
deband · lightSmooths steps in soft gradients (skies, glows) with a fine dither.
deband · strongSmooths wide, visible steps in gradients. It can soften fine texture.
upscale to surface · LTX…A sharper, bigger version at the size the surfaces show the clip, made at starlight cloud. It costs money: it opens a window with the price first (Upscale to surface · LTX).
  • To stop a job, click cancel on its row in the Generations panel. A file that a job already made stays.
  • If a job failed or you cancelled it, click retry to run it again. The row shows why it failed.
  • To clear a finished row from the list, click dismiss. The version file stays.
  • To see only these jobs, click versions in the panel's filter strip. Click it again to see every job.

Upscale to surface · LTX

upscale to surface · LTX makes a sharper, bigger version of a clip at the size your surfaces show it. LTX refine renders it again on a cloud computer at starlight cloud. It costs money, and Starlight shows the price before anything starts.

You need a starlight cloud key. Your studio admin gives it to you. Add it in Settings › Keys, on the starlight cloud row (Keys). Each key has its own budget for each month.

  1. Right-click a video layer on the canvas, or its node in the node graph.
  2. Choose make version › upscale to surface · LTX…. A small window opens. Nothing starts yet.
  3. Check from. If the layer plays a version, the new version starts from it. Click original to start from the original clip instead.
  4. Check size. It starts at the size the clip has on its biggest surface. To change it, type a new width. The height follows the shape of the clip. The size is never smaller than the clip.
  5. Read the price and the time. The price is an estimate. For a big surface it is a range, for example ≈ $8.77–$11.20, because the same job can take longer one time than another. The window also shows how much of this month's budget is left, and it warns you when the budget is too small.
  6. Click start · ≈ $… (the button shows the price). The window closes.
  7. The Generations panel (⇧G / Shift+G) shows the job: uploading the clip, waiting for a free GPU, rendering · 3 min, downloading the result, then making the version. Its row shows the estimate (≈$8.77–11.20). When the job ends, the real cost takes its place. If the job stops, see When a job stops.
  8. When it is done, use it like any other version (Use a version). Press ⌥B / Alt+B to compare it with the original.
  • A render that has started can't be stopped. It is still billed. If you cancel it, you pay for the render and get no version. Starlight asks you first.
  • A job that still waits at starlight cloud stops at once when you cancel it, and costs nothing.
  • retry on a job that failed or that you cancelled: if it must render again, it costs again. Starlight shows the price and asks first. If it only needs to finish the last step, it starts at once and costs nothing.
  • If the window says Settings › Keys, you have no key yet. Click open Settings › Keys, add the key, and try again.
  • The ⓘ button in the window shows the steps of the job and what a cancel does.

When a job stops

The job's row in the Generations panel always says what is happening, what it cost, and what to do next. Red means the job failed. Orange means "look at this", but the job is not broken. Grey means it ended without a version, for example because you cancelled it.

The row saysWhat it meansWhat to do
waiting for a free GPU · 45 min so far · starts by itselfThe job is in the queue. starlight cloud often has only one GPU free, so a job can wait a long time behind other jobs (yours too). Waiting costs nothing.Nothing. It starts by itself. You can close Starlight: the job goes on.
rendering · 3 minThe GPU renders your clip. The minutes count up. A big surface can take 2 hours.Nothing. It is not stuck. You can close Starlight: the render goes on, and Starlight picks it up again when it opens.
… · longer than usual (5 h)The job takes longer than such jobs usually take. This is not an error.Nothing. Starlight keeps checking, and it downloads the result by itself.
waiting: you already have 2 jobs at starlight cloudYou can run 2 jobs at once. This one waits for one of them to end. Nothing is spent while it waits.Nothing. It starts by itself.
stopped checking · ≈$8.77–11.20 if it finishesStarlight stopped checking the job (orange, not red). The render may still finish at starlight cloud, and then it is billed. So the cost is not known yet: the row shows the price it has if it finishes.Click check again. It costs nothing. send again makes a new job, and that costs again.
cancelled before it started · $0You cancelled the job (grey) while it was uploading or waiting for a GPU. Nothing was spent.Nothing. Click retry to make it again. Starlight shows the price first.
cancelled after 28 s of rendering · $0.07You cancelled the job (grey) while it rendered. You pay for the GPU time it used, and the row shows it. If starlight cloud says cancelling · the render runs to its end, the render could not be stopped: it ends by itself, and you pay for all of it.Nothing. Click retry to make it again. Starlight shows the price first.
Cancelled at starlight cloud, not in StarlightSomeone cancelled the job outside Starlight, for example with a tool or an admin page. The row shows what it cost.Click retry if you still want the version.
Your starlight cloud budget for this month is used upstarlight cloud refused the job. Nothing was spent. The window warns you before you start.Ask your studio admin to raise the budget, or wait for the 1st of next month.
starlight cloud does not know this keyThe key in Starlight is wrong, old or turned off. Nothing was spent.Open Settings › Keys and paste the key the team gave you. Then click retry.
starlight cloud refused the job settingsThis is a problem in Starlight, not in your clip. Nothing was spent.Copy the details (below) and send them to us.
The upload stopped · starlight cloud is not answering right nowThe connection dropped, or starlight cloud has a problem for a moment. Nothing was spent.Nothing. Starlight tries again by itself, up to 7 times. If it still fails, check your internet connection and click retry.
The GPU ran out of memory · The render took longer than 4 hoursThe render was too big for the GPU. The row says what it used, for example It used $1.30 of GPU time.Make the clip shorter or the size smaller, then try again.
its file is no longer in storageThe render finished, but starlight cloud keeps files for 30 days only.Click retry to render it again. That costs again.
download failedThe render is done and paid (orange, not red). Only the download failed, for example because the connection dropped or the disk is full.Click download again. It costs nothing.
This clip is too long for starlight cloud at 6400×2752A bigger size takes fewer frames. The message says the most frames for this size, and a width that fits the whole clip.Make the clip shorter, or type the smaller width that the message gives.

Where is the finished file? When the job is done, its row shows the path, for example assets/.versions/walls/north.mp4/upscale-0badc0de.mp4. Click show in folder to see it in Finder or Explorer. (On a Mac, Finder hides folders whose names start with a dot, such as .versions. show in folder opens it for you.)

To ask us for help with a job that failed or stopped:

  1. Find the job's row in the Generations panel.
  2. Click copy details under the message. If the panel shows one line per job, hold the pointer over the row: copy details shows at its end. (A generation job has it in its right-click menu.)
  3. Starlight copies a short report: the Starlight version, the time, the size, frames and fps, the starlight cloud job number, how far the job got, the message, the words starlight cloud gave, and the cost.
  4. The report never has your key, a password or a download link in it.
  5. Paste it into Discord for the team, and say what you were doing.

Use a version

When the job is done, the clip has a new version. Pick it for a layer in one of these ways:

  1. In the Generations panel, click use on layer on the job's row. The version goes on the layer you made it from. If that layer is not in the open scene, it goes on every layer of the open scene that plays the clip.
  2. Or right-click the layer and choose versions ›. Pick a version, or original. A dot (●) shows the one in use.
  3. To give every layer of this clip the same choice, choose versions › use on every layer of this clip.
  • Each of these is one normal edit. ⌘Z / Ctrl+Z undoes it. The scene is not saved until you press ⌘S / Ctrl+S.
  • The scene file then has version: denoise-41c0e9aa on the layer. It still names the original clip as src.
  • versions › shows only when the clip has at least one version.

When a version is not used

Sometimes a layer names a version, but Starlight cannot use it. The layer then plays the original. Nothing is lost, and the scene does not change.

  • In versions ›, the row says not used and a short reason, for example not used: original changed. Hold the pointer over the row to read the full reason.
  • original changed: someone replaced the original clip after the version was made. Make the version again.
  • other shape, frame count or frame rate: the version does not have the same shape, length or speed as the original.
  • not on this computer: the scene names a version, but its file is not here. In a shared project, wait for Dropbox to copy it.

Mattes of a clip: person, depth, roto

A matte of a clip is a grey video made from the clip. White keeps and black cuts. A person matte shows who is in the clip. A depth matte shows how near each part is (white is near). A roto matte shows what a typed prompt names, for example the singer. A matte is a kind of version, but it is never the picture of a layer: it cuts the layer.

  1. To make a matte on this Mac, right-click a video layer and choose make matte ›: person · this Mac, person · accurate · this Mac (finer edges, about three times slower) or depth · this Mac. It is free. The job shows in the Generations panel with its progress, and cancel stops it.
  2. When the matte job is done, click cut layer on its row in the Generations panel. Or right-click the layer and choose versions › cut layer by ›, or pick the matte under cut by in the layer's Properties.
  3. Starlight cuts the clip by its matte. The cut is inside the layer, so it moves, scales and fades with it. A depth matte starts with range 0.5 to 1: the nearer half shows.
  4. cut layer cuts one layer: the one you made the matte from. If that layer is gone, select the layer to cut, then click cut layer again.
  5. Set range from and range to, feather px or invert in the matte section of the layer's Properties.

A photo can have a depth matte too:

  1. Right-click an image layer and choose depth matte › make · this Mac. A Mac makes the depth map once and saves it in the project, so every computer has it. This does not cut the layer yet. While it runs, the same menu shows cancel making.
  2. Right-click the layer again and choose depth matte › cut layer by it. The nearer half shows. Set range from and range to to choose near and far.
  3. If there is no depth map yet, the layer shows without the cut and the canvas says why. (A cutout is different: it changes the picture at once.)
  • Nothing is cut by itself when a matte is made. You choose the layer to cut.
  • The first depth matte downloads the depth model once (about 50 MB). It needs the internet that one time. After that, depth mattes are made offline.
  • Mattes marked this Mac are made on a Mac. It needs the Xcode Command Line Tools: if the job says so, open Terminal and run xcode-select --install. On Windows, make the matte on a Mac, or use a cloud matte.
  • If the same matte of the clip was made before (on this computer, or on another one in a shared project), Starlight uses it and does not make it again.
  • Each of these is one normal edit. ⌘Z / Ctrl+Z undoes it.
  • If the matte file is not on this computer, or the clip changed after the matte was made, the layer shows without the cut. It is never cut by the clip itself. The canvas line says matte not used and why. Make the matte again.
  • An export then stops and names it as no matte. render anyway exports that layer without the cut.
  • use on every layer of this clip never puts a matte on a layer as its picture.
  • ⤺ in the matte section removes the cut, and the matte with it.
  • Make Loop does not work on a clip that is cut by its matte. Remove the cut, make the loop, then cut again.
  • A scene with a matte cut, or with a range, is scene version 18. An older Starlight asks you to update before it opens it.

Cloud mattes: roto by prompt, and depth

A cloud matte is made by fal.ai, a paid AI service, on any computer (Windows too). roto by prompt makes a mask of what you name, for example the singer, and follows it through the clip. depth makes a depth matte (white is near). You need a fal key.

Not available yet. In this version both rows are greyed out and say awaits a test run. Starlight first checks with one real run what fal sends back. An update turns them on. Meanwhile, make person and depth mattes on a Mac.

  1. Make a key at fal.ai › Keys. In Starlight, open Settings › Keys, find fal.ai and click set. Paste the key.
  2. Right-click a video layer and choose make matte › roto by prompt · fal… or make matte › depth · fal…. A menu row never spends money: it opens a small window first.
  3. For roto, type what the matte keeps, for example the singer or the guitar. A comma keeps several things: person, guitar.
  4. The window shows the clip's length and the price. Click start · ≈ $0.095 (the price is on the button). Nothing is spent before this click.
  5. The job shows in the Generations panel: the clip goes to fal, fal makes the matte, then Starlight makes it into the matte. A 10 s clip takes a minute or two.
  6. When it is done, click cut layer on its row, as for a matte made on this Mac (Mattes of a clip).
  • The price is fal's: roto about $0.10 for 10 s at 30 fps ($0.005 for each 16 frames), depth $0.04 for each second. fal does not say what a job cost, so Starlight shows that price.
  • A clip can have at most 2400 frames (80 s at 30 fps).
  • Starlight sends fal a copy of the clip, at most 1920 px wide and without sound. The matte comes back at the clip's own size. fal keeps the copy and the matte for one day at most, and Starlight asks fal to delete them as soon as the matte is here.
  • If fal finds nothing that the prompt names, the job says so. Try other words, then retry. A retry costs again, so it asks you first.
  • While the clip uploads, the row says nothing paid yet. A cancel then sends nothing to fal.
  • A job still waiting at fal never runs if you cancel it. A job that has started at fal may still finish after a cancel, and then it is billed. If you click retry meanwhile, Starlight waits for that job, and uses its matte if fal finishes it. Only when fal ended it without a matte does a retry cost again.
  • Each frame of the matte plays at the same moment as its frame of the clip, also for a clip whose frame rate changes. If the frame rate changes too often, Starlight says so: export the clip at a constant frame rate first.
  • If what fal sends back is not a matte (for example, a copy of the clip), Starlight does not keep it and says so. It was paid; the file stays in the project's generations folder.
  • If the same cloud matte of the clip was made before, Starlight uses it and does not pay again.
  • Claude can make one too, with version_create and the presets roto-matte-fal and depth-matte-fal. It always says the price first.

Where versions are kept

  • Versions are files in assets/.versions/, in a folder named after the original clip. For example, the versions of assets/walls/north.mp4 are in assets/.versions/walls/north.mp4/.
  • The Assets panel does not show them. They belong to their clip.
  • Version files are big, so Starlight keeps them out of git (the save history).
  • In a shared project, Dropbox copies them to the other computers, like any other file in the project.

In a shared project:

  1. You make a version as usual. Its file goes into assets/.versions/, and Dropbox copies it to the other computers.
  2. Each computer makes its own small preview copy (the proxy) of the version. This happens by itself, with no job in the Generations list. Until then, the layer plays the full file.
  3. Two computers never make the same version at the same time. If another computer is making it, Starlight says so, for example is being made on Studio-Mac since 21:04. Wait for Dropbox to bring it.
  4. If the same version is already there, Starlight uses it and does not make it again.
  • Starlight cannot make a version yet of a clip that has its own transparency (for example ProRes 4444) in a shared project.
  • If Dropbox keeps a clip online-only, make it available offline first.

On this page