Physical vs Virtual Ingest

Overview

When you ingest footage into Onset Engine, it either cuts a separate video file for every clip it finds, or indexes clips in place as pointers into your original footage.

Core and Studio index in place by default. The Demo tier always cuts physical clips.

Measured on 60 seconds of 4K source (23 clips detected, proxy creation skipped in both runs):

	Ingest time	Written to disk
Pointer-only (Core / Studio)	0m 30s	0 bytes
Physical clip cutting (Demo)	1m 51s	144 MB

That is roughly 4x faster, and cutting duplicates a substantial fraction of your source footage onto your drive.

Pointer-only is also strictly more capable, which matters more than the speed: a physically cut clip cannot be read past its own end, so when the music calls for a longer shot the editor has no footage left to hold. A pointer can always read further into the source. That is why pointer-only is the default wherever it is available.

You can force the old behaviour with --no-skip-clip-export if you specifically want standalone clip files on disk.

Physical Ingest (Demo tier)

Physical ingest extracts individual clip files from your source videos:

Source: wedding_ceremony.mp4 (45 min, 12 GB)
      ↓ Scene detection + CLIP analysis
Output: clips/
  ├── clip_0001.mp4  (3.2s, 18 MB)
  ├── clip_0002.mp4  (4.1s, 22 MB)
  ├── clip_0003.mp4  (2.8s, 15 MB)
  └── ... (347 clips)

Characteristics

Aspect	Physical
Disk usage	High — clips are duplicated as separate files
Render speed	Fast — clips read directly from individual files
DJ Mode seek	Instant — each clip is a standalone MP4
Portability	Self-contained — can move clip folder independently
Best for	Working sets < 500 GB, maximum render performance

How It Works

1. FFmpeg splits the source video at scene-change boundaries
2. Each clip gets a CLIP embedding (768-dim float32 vector)
3. Motion score, duration, and peak frame are computed
4. Metadata is stored in library.db (SQLite)
5. The physical .mp4 file is written to the clips/ directory

Virtual Ingest (Pointer-Only) — the default on Core and Studio

Virtual ingest creates database references without copying any files:

Source: wedding_ceremony.mp4 (45 min, 12 GB)
      ↓ Scene detection + CLIP analysis
Output: 0 bytes on disk (only DB entries)

Database entry:
  source_path: "D:/footage/wedding_ceremony.mp4"
  start_time: 34.2
  end_time: 37.4
  embedding: [0.023, -0.117, 0.891, ...]
  is_virtual: 1

Enable it with the “Pointer Only” checkbox in the Ingest dialog.

Characteristics

Aspect	Virtual
Disk usage	Zero — only SQLite metadata, no file copies
Render speed	Slightly slower — FFmpeg seeks into source files
DJ Mode seek	Uses start property in MPV — no first-frame flash
Portability	Tied to source paths — moving files breaks references
Best for	Data hoarders, 1TB+ libraries, NAS-backed storage

How It Works

1. FFmpeg probes the source video for scene-change boundaries
2. Each segment gets a CLIP embedding from the peak frame
3. The database stores source_path, start_time, end_time, and all metadata
4. No physical clip file is created — the source video IS the clip storage
5. During render, FFmpeg seeks to start_time in the source file

Tip

Virtual ingest is ideal for indexing massive archives (anime series, raw drone footage, surveillance archives) where duplicating files would consume terabytes of disk space.

Drift-Split Clip Boundaries

Scene detection only fires on hard cuts. A long continuous take — a locked-off camera, a single unbroken shot — registers as one scene, which then gets divided into clips at essentially arbitrary points. The result is clips that span a change in the action: half of one thing, half of another.

Since v1.0.7, ingest also watches for content drift. As it walks through a scene, it compares each sampled frame against the frame the current clip started on. When the content has drifted past drift_threshold, the clip ends there instead of at the arbitrary point.

This only ever shortens a clip, never extends one, which makes the behaviour adaptive:

• Moving footage (handheld, roaming camera, changing action) gets cut on the changes. Measured on real footage, clips spanning a hard content change dropped by about a quarter, yielding roughly 20% more clips.
• Static footage (locked-off, single setup) barely triggers it at all — clip lengths stay as they were.

The threshold is configurable via generator.scene_detection.drift_threshold (default 0.92; 0 disables it). Higher values split more aggressively and produce shorter clips; lower values rarely fire.

Ingest reports what it did:

[DRIFT] 46 clips cut early on content change (threshold 0.92)

Note

Clip segmentation is deterministic — the same file always produces the same clips. If you re-ingest footage that was indexed before v1.0.7, expect different (better-placed) boundaries than you had previously. Existing libraries are untouched unless you choose to re-ingest.

Mixing Modes

You can use both modes in the same library. Some sources can be physically ingested (your working set) while others are virtual (your deep archive). The render pipeline handles both transparently.

library.db
  ├── Physical clips: 2,400 (from working set)
  └── Virtual clips: 18,000 (from archive NAS)

The Studio render and DJ Mode don’t care whether a clip is physical or virtual — they follow the same selection logic. The only difference is at the file I/O level during rendering.

When to Use Which

Scenario	Recommendation
Small project (< 100 GB footage)	Physical — faster renders, simpler management
Large archive (1TB+)	Virtual — saves disk space, indexes everything
NAS-backed storage	Virtual — avoid copying over network
Portable project (USB drive)	Physical — self-contained clip folder
Mixed workflow	Physical for active project + Virtual for archive browse

Progressive Ingest

Both modes support progressive ingest — you can start working before all files are processed. The minimum threshold is 50 clips before DJ Mode becomes available. Studio Mode requires at least one clip.

During progressive ingest, the Vision Matrix dashboard shows live thumbnails and AI tags as each video file completes analysis.

Related Articles

• Style Presets
• Studio Mode