Stash Import

Overview

Stash is a self-hosted media organiser with a local GraphQL API. If you already maintain a curated Stash library, Stash Import brings that curation into Onset Engine rather than making you rebuild it.

Onset matches your ingested source files to Stash scenes by file path, then creates a Subject for each performer — with a CLIP centroid computed from the matched clips. That last part is the important bit: imported Subjects work immediately with Find More, so they can surface clips from footage that was never catalogued in Stash at all.

Note

This reads your own metadata from your own machine over localhost. Nothing is transmitted anywhere.

Requirements

• Stash running locally (default http://localhost:9999)
• Stash v0.17 or newer (the import uses the scene.files schema)
• Your footage already ingested into Onset — matching is against files Onset knows about
• An API key only if your Stash requires authentication

Running an import

From the GUI

1. Open the SUBJECTS tab in the asset bin
2. Click ⬇ STASH
3. Confirm the URL, and enter an API key if your instance needs one
4. Click Preview (Dry Run) — this reports what would be imported without writing anything
5. If the numbers look right, click ⬇ Import

From the CLI

# See what would happen
OnsetEngine.exe stash-import --dry-run

# Import performers
OnsetEngine.exe stash-import

# Include Stash tags as well as performers
OnsetEngine.exe stash-import --include-tags

# Non-default instance
OnsetEngine.exe stash-import --url http://192.168.1.50:9999 --api-key YOUR_KEY

Path matching

Matching is by file path, case-insensitively. Stash and Onset must be looking at the same files by the same route.

If a dry run reports far fewer matches than expected, a path mismatch is almost always the cause — for example Stash indexing \\NAS\media\clip.mp4 while Onset ingested Z:\media\clip.mp4. Same file, different route, no match.

What gets imported

Stash	Onset
Performer	Subject, with a CLIP centroid from the matched clips
Tag	Subject (only with --include-tags)

Tags are opt-in because Stash tag vocabularies are often large and not all of it is useful for editing.

Clip associations are recorded with source='stash', distinguishing them from manual approvals and automatic matches.

Granularity

Stash metadata is scene-level, so matching is per source video. Every clip cut from a matched scene inherits that scene’s performers — including moments where they are not on screen.

That’s inherent to the source data. Refine it afterwards using the review queue and Find More, which operate at clip level.

Re-running

Imports are idempotent. Subjects are keyed by name, so re-importing after tagging more material in Stash updates the existing Subjects rather than duplicating them. Re-run it whenever your Stash library grows.

Notes

• Only affects Subjects and tags. Your clips, ratings and projects are untouched.
• If Stash isn’t reachable, the import reports it plainly and exits without changes.
• No face recognition is involved — Subjects are general visual similarity.