Script Sniper

Overview

Script Sniper tracks a point in your video and translates its vertical motion into script points in real time. It uses a correlation tracking engine powered by OpenCV.js running directly in your browser, built to survive fast strokes, motion blur, deforming targets and camera movement.

Points are added directly to the timeline as tracking progresses. There is no separate apply step.

How It Works

1. You define a tracking region (bounding box) over the video
2. You click inside the box to select a specific point to track
3. The tracker follows that point as the video plays
4. Vertical movement within the box is mapped to position values (0-100)
5. Script points are generated directly on the timeline, one per video frame

Every generated point passes a quality check first. When the tracker is not confident about a frame, that frame is skipped instead of writing an unreliable point into your script.

The bounding box defines the full range of motion. By default, the bottom of the box maps to position 0 and the top to position 100. You can reverse this direction or switch to horizontal mode where left maps to 0 and right maps to 100.

The box is a ruler, not a cage: when the tracked point overshoots the box at a stroke extreme, the output simply pins at 0 or 100 until it comes back. Overshooting is never treated as a tracking failure, so the box does not need to be sized generously, just to the range you want mapped.

Getting Started

1. Load a video into ScriptCompiler
2. Open Script Sniper from the Tools Panel
3. A bounding box appears over the video. You can resize and position it, or draw a new one by clicking and dragging anywhere on the video.
4. Click inside the box on the specific point you want to follow
5. The video starts playing and script points are generated automatically

The box displays "0%" and "100%" labels to show the position range, and a direction arrow indicates which way the stroke maps. A small circle and trailing line show the current tracked position.

Bounding Box Controls

Moving the Box

• Click and drag anywhere on the box border to move it
• Or use the move handle on the left side of the box

Resizing the Box

• Drag any of the 4 corner handles to resize diagonally
• Drag any of the 4 edge handles to resize along one axis
• Scroll the mouse wheel while hovering over the box to scale it (5% per tick)

Rotating the Box

• Drag the rotation handle (circular icon above the box center)
• Press Q to rotate counter-clockwise or E to rotate clockwise
• Rotating is useful when the motion axis is not perfectly vertical

All handles scale proportionally to the box size, so small boxes have smaller controls and large boxes have larger ones.

Drawing a New Box (Rectangle Lasso)

Instead of adjusting the existing box, you can draw a brand new one at any time by clicking and dragging anywhere on the video outside or inside the current box. This works like a rectangle lasso tool.

• Click and drag to define the new box area
• The minimum box size is 50x50 pixels
• The new box inherits the current reverse and horizontal axis settings
• If tracking is active, it automatically restarts from the center of the new box

Direction Controls

Script Sniper lets you control how tracked motion maps to position values. An arrow inside the bounding box shows the current stroke direction.

Reverse Toggle

Swaps the 0% and 100% sides. By default, bottom is 0% and top is 100%. Reversing flips them so top becomes 0% and bottom becomes 100%.

• Press F during tracking mode
• Or click the reverse button on the right side of the bounding box
• The 0% and 100% labels swap positions to reflect the change

Horizontal Axis Mode

Switches from vertical to horizontal stroke mapping. Instead of tracking up/down motion (bottom to top), it tracks left/right motion (left to right). This is useful for scenes where the primary motion is horizontal.

• Press Shift+F during tracking mode
• Or click the axis button at the bottom of the bounding box
• The 0% and 100% labels move to the left and right sides
• The direction arrow updates to show the horizontal mapping

Tracking Process

Once you click a point inside the bounding box:

1. The tracking engine initializes on that point
2. If the video is paused, it starts playing automatically
3. The tracker follows the point and generates script points for every video frame
4. Points appear on the timeline in real time

You can adjust the bounding box position, size, or rotation while tracking is active. The tracker adapts to the new configuration without stopping.

To stop tracking, use the stop button or navigate away from Script Sniper. After tracking, apply Smoothing to clean up tracking jitter.

Tracking Status and Auto-Stop

A status badge above the bounding box tells you what the tracker is doing whenever it is not simply locked on:

• Coasting through motion blur: the target is briefly unrecognizable (usually a very fast stroke) and the tracker is bridging the gap using the motion it has seen so far
• Re-acquiring target: the target was lost and the tracker is searching for it. No points are written while this badge is visible.

Momentary blips that recover on their own are not shown; a badge only appears when a state persists for a noticeable moment.

Tracking stops on its own when continuing would produce garbage points:

• Scene change detected: a hard cut removed the target from the frame
• Target lost: the target could not be found again after a few seconds of searching
• Scene boundary: the video reached the end of the current scene (when scene data is available)

When this happens, a notice on the video explains why tracking stopped, and by default the video pauses so you land exactly on the frame where tracking ended. The notice offers two actions:

• Resume here: restarts tracking at the last trusted position. Useful after a brief loss or when the action continues after a cut.
• Dismiss: closes the notice. You can also just select a new tracking point as usual.

The notice also carries a small checkbox to turn the automatic video pause on or off right there, without opening Settings. It controls the same Pause on tracking stop setting described below.

Camera Follow

When the camera pans, the whole frame moves even though the action stays the same. Script Sniper measures this background motion and automatically moves the bounding box along with the camera, so a panning shot does not require you to re-drag the box mid-scene.

Camera follow is enabled by default and can be turned off in Settings under the Script Sniper tab.

Two-Point Tracking (Experimental)

Two-point mode tracks two points instead of one and scripts the distance between them: points touching maps to 0, points separated by the full box length maps to 100, and the reverse toggle flips this. Because the value is a relative distance, it is unaffected by camera movement and by the subjects drifting across the frame, which makes it the most robust mode for scenes where the whole action slowly moves around.

Enable it in Settings under the Script Sniper tab, then click two points inside the box, typically one on each of the two moving parts. The first click marks the first point, the second click starts tracking. Both dots update live with a dashed line between them showing the measured separation.

In this mode the bounding box plays a different role than in single-point tracking:

• Axis: only separation along the box axis counts, so sideways wobble does not pollute the depth signal. Rotate the box so its axis lies along the line between your two points.
• Scale: the box length defines what separation counts as 100. Size the box so its length roughly matches the fully-apart distance.
• No constraint: the tracked points may sit at or beyond the box edges without any penalty; separations beyond the box length pin at 100.

Tracking Settings

Fine-tune tracking behavior in Settings under the Script Sniper tab:

Click Reset Defaults to restore all tracking settings to their original values.

Tips for Best Results

Good Tracking Conditions

• Clear, consistent motion with good lighting
• Good contrast between the tracked object and its background
• Camera panning is compensated automatically by Camera Follow, but a steady shot still gives the best results

Selecting the Tracking Point

• Click on a distinct, high-contrast feature
• Avoid edges of objects where tracking may jump

Bounding Box Placement

• Size the box to cover the full range of vertical motion
• Position "0%" at the minimum position and "100%" at the maximum
• Rotate the box if the motion axis is diagonal

Post-Processing

• Apply Smoothing to reduce tracking jitter
• Use Position Multiplier to adjust intensity
• Manually fix any sections where tracking lost the point