Subjects & Few-Shot Tagging

Overview

Subjects let you describe something by example rather than by filename. Select roughly five clips that share a quality — a person, a vehicle, a pose, a shot type, a location — name it, and Onset Engine sweeps your entire library for anything similar.

This works because ingest stores a CLIP embedding for every clip: a mathematical description of its visual content. Clips that look alike sit close together in that space, so a handful of examples is enough to define a region and find the rest.

The SUBJECTS tab in the asset bin is where you manage them.

Note

This is visual similarity, not face recognition. No biometric identification is performed. That has a practical consequence worth understanding — see What it keys on below.

Creating a Subject

1. In the VIDEO tab, enable Tag Mode.
2. Click 4–6 clips that share the quality you want to capture.
3. Click 🤖 Propagate Tag.
4. Name the Subject and set a match threshold.
5. Run it.

Onset scores every clip in the library against your examples, auto-tags the confident matches, and collects the uncertain ones into a review queue.

Choosing good examples

Example quality matters far more than quantity:

• Vary them. Different scenes, lighting, angles. Five near-identical clips define a narrow region that only matches more of the same.
• Keep them clean. Clips where the subject is unambiguous, not one of five things in frame.
• Stay consistent. All examples should share the one quality you’re capturing. Mixing “this person” and “this pose” teaches a blurry average of both.

The match threshold

Higher values mean fewer, more certain matches. Lower values cast wider and admit more false positives. The default is a sensible starting point; tune it once you’ve seen the results on your own library.

The review queue

Matches that fall just below the threshold are shown for approval rather than discarded. Each row gives you a thumbnail, a similarity percentage, and a ▶ button that plays that exact segment.

Approve what’s right, ignore the rest. This step is worth doing: approvals are stored as manual tags and feed back into the Subject, so each pass sharpens the next one.

Finding more

On any Subject card, 🔍 MORE re-scans the library using the Subject’s current members — including everything you’ve approved since — at a slightly looser threshold than the original propagation. New candidates come back through the same review queue.

Running this a few times, approving as you go, surfaces material the first pass missed. Matching is against the nearest member as well as the group average, so a Subject that spans several different looks keeps working rather than degrading into a blurry mean.

Using Subjects in an edit

Filter the bin. The FILTER button on a Subject card scopes the asset bin to that Subject.

Reference it in a driver. Add the Subject name to any tier’s tags:

{
  "tiers": {
    "4_MAX": {
      "descriptions": ["peak intensity moment"],
      "tags": ["@SubjectName"]
    }
  }
}

That tier now draws from that Subject. Put it on the peak tier and the drops feature it; put it on every tier and the whole edit does. See Creating Drivers for the full schema.

What it keys on

Because this is general visual similarity rather than identity detection, a Subject responds to everything in frame: the subject itself, the framing, the setting, the lighting.

The limitation: the same person shot in a very different context may not match from your original examples. The fix is the review queue — approve a few of those outliers and the Subject widens to include them.

The upside: you can define a Subject by pose, composition or shot type rather than by who or what is in it. Seed on five wide shots and you get a wide-shot pool; seed on a particular camera setup and you get every instance of it across your library. Combined with driver tiers, that’s a way to give an edit a consistent visual grammar — wides on the quiet passages, close-ups on the peaks.

Importing existing tags

If you already maintain a tagged library in Stash, you can import those performers and tags directly as Subjects, complete with embeddings, rather than building them by hand.

Notes

• Only ingested clips can be matched. Anything not analysed is invisible to a sweep.
• Subjects persist in library.db and are reusable across every future project.
• Larger libraries produce better results, since there’s more for a sweep to find.
• All analysis and matching runs locally.