Roto and transcript correction guide

Before you start

Roto works on footage layers in a composition: video, image and composition clips. While Roto is active, the Stage shows the selected layer's source, so marks land on the original pixels even when the layer is scaled or cropped in the composite.

Transcript correction needs a transcript in the project. If Edit Transcript… reports that there isn't one, ask Ape to transcribe the clip. Transcription needs the Whisper Small model installed on your computer.

W: Roto on the selected footage
V: Done, back to the Select tool
C: Cycle through alternative subject selections
Esc: Clear untracked marks on the current frame
Alt while brushing: Subtract from the mask
I / O: Mark In and Out in a source preview

Isolate a subject

Select the footage layer in the timeline or on the Stage.
Press W or choose Roto in the Stage toolbar. The Roto panel opens in Properties.
Choose New mask and pick Subject mask.
Go to a frame where the subject is clear of other objects. Brush over the subject, or choose the Rectangle tool and drag a box around it. Hold Alt as you brush to mark areas to leave out, or switch between Add and Subtract in the panel.
Check the outline on the Stage. If Grapple has selected only part of the subject, or too much, press C to cycle through the alternatives. The panel shows which one you are on.
Choose Apply selection. The mask now covers this frame.

To start again on the current frame, choose Clear selection or press Esc. That discards marks that haven't been tracked.

Track the mask and repair drift

In the tracking controls, set In and Out to the frames the mask should cover. The range has to stay inside the footage.
Choose Track forward or Track backward. For a difficult stretch, use Track one frame forward or backward and check each frame as you go.
Watch the Stage while tracking runs. Choose Stop as soon as the mask starts to drift. Frames tracked before you stopped are kept.

Repair a frame that drifted

Go to the first frame where the mask is wrong.
Add marks there: brush over what is missing, or Alt-brush over what shouldn't be included.
Choose Apply selection, then track forward again from this frame.

Every frame where you applied a selection is listed under Frame corrections; choose one to jump back to it. The Roto panel tells you when the current frame hasn't been tracked, and you can track into it from a selection frame or add a new selection there.

Draw and track a vector mask

With Roto active, choose New mask and pick Vector mask, or choose the Pen tool (G).
Click to place corner points and drag to pull out curves. Click the first point to close the shape.
To change an existing mask, select it in the Roto panel list and move its points on the Stage.
Choose how the shape may move under Motion. Position suits a flat object that only slides. Position, scale & rotation suits one that also turns or moves toward the camera. Affine adds skew, for a surface seen at a slowly changing angle.
Set In and Out and track. Grapple follows the texture inside the boundary.
If the object changes shape, go to a later frame, adjust the points and track on from there.

Vector masks are the right choice for screens, signs, windows and other hard edges.

Paint a mask by hand

Choose New mask and pick Paint mask. The Brush tool (B) is selected.
Set Diameter in source pixels; the circle on the Stage shows the size. Set Softness for the edge of each stroke.
Under Apply to, choose This frame for a one-frame fix or Entire clip for a stroke that should hold for the whole clip. Strokes already painted keep the range they were painted with.
Paint to add to the mask. Hold Alt to paint it away.

Order, feather and smooth masks

Masks on a clip apply from top to bottom in the Roto panel list. Use Move earlier and Move later to change the order, double-click a name to rename it, and remove masks you no longer need.

Threshold: Makes a subject matte hard-edged: pixels at or above the value become solid and the rest drop out. Lower it to keep more of a soft boundary such as hair; raise it to tighten a loose mask.
Feather: Blurs the edge by a radius in pixels. Use it to soften the hard edge that Threshold leaves.
Smoothing: Blends each frame's matte with the frames either side to reduce flicker. At high values, the edge of a fast-moving subject can soften.

When you're finished, choose Done or press V to return to the Select tool.

Correct transcript text and speakers

Choose Edit Transcript… from the Edit menu. If the project has several transcripts, choose the one you want from the list.
Select a line in the table. The source preview cues to the start of the line and marks its range. Press Space to play it, or turn on Loop marked source range to hear it repeatedly.
Type the correction in the Text field under Selected span and choose Apply. If you select another line before applying, Grapple asks whether to apply or discard the change.
To attribute the line, pick a speaker and choose Apply speaker. To add a speaker, type a name and choose Add. To rename one, select it, type the new name and choose Rename.

Change the structure of a line

Split at cursor: Place the text cursor where the line should break, then choose Split at cursor. Apply any pending text change first.
Merge with next: Joins the selected line and the one after it.
Delete: Removes the line from the transcript.
Replace transcript text: Edit or paste the whole transcript under Full transcript text and choose Replace transcript text. This clears the timing of every line.

Confirm or set timing

When you change a line's words, Grapple keeps the original stretch of audio for listening but no longer treats it as the line's timing. Lines created by splitting or merging start with no timing. The Status column shows where each line stands.

Timed: Confirmed timing. The line appears in linked captions.
Source window only: The words changed. The original audio range is kept for listening until you confirm timing.
Needs timing: The line has no timing yet.

Select the line and listen to it in the source preview.
If the words sit where the original range says, choose Apply timing to confirm the values already in the Timing fields.
Otherwise, step to the first frame of the words and press I, then step to the last frame and press O. The Timing fields update. Choose Apply timing.

You can also type start and end times in seconds. The end has to come after the start.

Create and style linked captions

In the composition, put the playhead where the start of the transcript's source should line up. For an interview clip placed at the start of the composition without a trimmed head, leave the playhead at the beginning.
Make sure the composition has a visual track to hold the captions.
In the transcript window, choose Create linked captions… and pick the track. The captions run to the end of the source or of the composition, whichever comes first.
Select the new caption layer. Set its font, size, colour, line height, backdrop and shadow in Properties, and position it on the Stage.

The caption layer shows the timed lines that are active at each moment. Correct a line later and the caption text follows while your styling stays put. Lines without confirmed timing are left out until you time them.

Take over the caption text

Move the playhead to a moment when the line you want is on screen, select the caption layer and choose Make Caption Text Independent from the Edit menu. The whole layer keeps the text shown at the playhead, as ordinary text with the same styling, and later transcript edits no longer change it. Use it for a caption layer that covers a single line, or when you want to write the wording yourself.

Undo, history and duplicates

The transcript window has its own Undo, Redo and Reload buttons, and they work on the project's history. In the editor, Undo and Redo also cover mask and tracking changes. The History panel lists each change: choose Compare to see the frame before and after it on the Stage, or Restore before this to take the project back to the state before that change.

When you reuse a masked shot, pick the duplicate that matches what should happen next.

Duplicate Linked Clips: The copies share later mask corrections. Fix a frame on one and every linked copy updates.
Duplicate after selection (Ctrl+D): The copies start with the same masks, and later corrections to each one stay separate.

Roto models and common problems

Roto uses two models that are included with Grapple and run on your computer: EfficientTAM follows the subject from frame to frame, and ViTMatte refines the matte edge. No download, account or provider is required. To use a compatible alternative, add it in Settings > Models and choose it under Defaults. Clearing that choice restores the included model.

If something goes wrong

The selection could not be resolved: Edit the marks on the frame and apply again. A clearer frame or a tighter box usually helps.
The subject models need attention: Choose Roto models… in the Roto panel to open the model settings and resolve the item listed there.
The tracking range must stay inside the footage: Set In and Out within the clip, with at least one frame between them.
The project has no transcript: Ask Ape to transcribe the clip. This needs the Whisper Small model installed on your computer.
The transcript changed: Another edit reached the transcript first. Choose Reload, then repeat the change.