FAQ & Common Fixes

System Requirements

What are the minimum specs?

Onset Engine requires a minimum of 8GB RAM. It runs on Windows 10+ or macOS 13+.

Do I need an NVIDIA GPU?

No dedicated GPU is required, as Onset Engine works great on CPU (using fallback inference). However, an NVIDIA GPU (CUDA) or Apple Silicon (MPS) will significantly speed up AI-powered clip analysis and hardware encoding. Read more.

Installation Issues

SmartScreen warnings

Windows SmartScreen may flag the installer as unrecognized since it is a new application. Proceed through the warning to continue installation.

Antivirus false positives

Some antivirus software may mistakenly flag Onset Engine due to its bundled AI models and FFmpeg binaries. Add the installation folder to your antivirus exclusions. Read more.

FFmpeg not found

Symptom: FileNotFoundError: ffmpeg or ffmpeg is not recognized

Fix: FFmpeg is bundled with Onset Engine in the ffmpeg/ folder. If you receive this error:

1. Verify the ffmpeg/ folder exists in your Onset Engine installation directory
2. If missing, re-extract the application from the original download archive
3. Restart Onset Engine

libmpv-2.dll missing (DJ Mode)

Symptom: DJ Mode button is grayed out or crashes immediately

Fix: MPV is bundled with Onset Engine in the mpv/ folder. If you receive this error:

1. Verify the mpv/ folder exists in your installation directory with mpv.exe and libmpv-2.dll
2. If missing, re-extract the application from the original download archive
3. Restart Onset Engine

CUDA not available

Symptom: RuntimeError: CUDA not available during ingest

Fix:

1. Verify you have an NVIDIA GPU: open Device Manager → Display adapters
2. Update to the latest NVIDIA driver from nvidia.com/drivers
3. Ensure CUDA Toolkit 11.8+ is installed: nvcc --version
4. If using a laptop, make sure Onset Engine is running on the discrete GPU (NVIDIA Control Panel → Manage 3D Settings → add OnsetEngine.exe → select “High-performance NVIDIA processor”)

Tip

Apple Silicon Macs (M1/M2/M3) are supported via the MPS backend — no CUDA needed. If no GPU is available at all, Onset will fall back to CPU inference (slower but fully functional).

First Run

Where are my clips stored?

By default, extracted clips are saved in the output_clips/ folder. You can change this location in config.yaml.

How long does ingest take?

Ingest time depends heavily on your hardware and the video length. With an NVIDIA GPU or Apple Silicon, it is much faster, while CPU fallback may take longer.

What is ViT-B-32 vs ViT-L-14?

These are the OpenCLIP models used for AI clip analysis. ViT-B-32 outputs 512-dimensional embeddings and is faster, while ViT-L-14 outputs 768-dimensional embeddings and is the default in config.yaml. Read more.

Ingest Issues

Ingest is very slow

Possible causes:

• CPU-bound decode: Large 4K files may decode slowly on CPU. Ensure you have a modern multi-core processor for best performance
• Antivirus scanning: Windows Defender may scan every extracted clip file. Add your clips directory to the exclusion list
• Mechanical HDD: Ingest is I/O heavy. Use an SSD or NVMe for the clip output directory
• CLIP inference: First run may download the OpenCLIP model (~1.7 GB). Subsequent runs use the cached model

Clips are too short / too long

Scene detection thresholds are adjustable in config.yaml:

# Adjust scene detection sensitivity
min_clip_duration: 1.5    # Minimum clip length in seconds (default: 1.5)
max_clip_duration: 12.0   # Maximum clip length in seconds (default: 12.0)
scene_threshold: 27.0     # FFmpeg scene detection threshold (lower = more cuts)

Lower the scene_threshold to get more clips (finer cuts). Raise it if clips are too fragmented.

Rendering Issues

Why is rendering slow?

Rendering speed depends on your export settings and hardware. CPU rendering takes significantly longer than hardware encoding.

How to get 60fps?

Ensure the fps setting in config.yaml is set to 60.0. Note that the free Demo license tier enforces a strict cap of 30 FPS.

What codecs are used?

Onset Engine uses H.264 or HEVC for video encoding.

NVENC vs CPU encoding

NVENC is a hardware encoder on NVIDIA GPUs that drastically speeds up exports. If no compatible GPU is found, Onset Engine falls back to CPU encoding, which takes longer but produces identical quality. Read more.

Render crashes with OOM (Out of Memory)

Symptom: Python crashes or NVENC fails during long renders

Fix: Onset Engine uses chunked rendering to prevent this, but if you’re still hitting OOM:

1. Reduce quality tier from maximum to balanced
2. Close other GPU-intensive applications (games, browsers with hardware acceleration)
3. Render at 1080p instead of 4K for the initial pass

Render output has no audio

Symptom: The rendered MP4 has video but silent audio

Fix: This usually means FFmpeg couldn’t find the music file during the final stitch:

1. Ensure the music file path has no special characters (spaces are fine, emoji are not)
2. Check that the music file is a standard format (.mp3, .wav, .flac, .ogg)
3. Re-run the render with the same music file selected

Colors look wrong in rendered output

Symptom: Output is oversaturated, undersaturated, or has a color shift

Fix:

• Check your preset’s color grading settings — the PRESTIGE preset applies teal-and-orange grading and the AGGRESSIVE preset desaturates
• Some media players apply their own color management. Try viewing in VLC or MPV instead of Windows Media Player
• If rendering at maximum quality, NVENC CQ17 preserves more color detail than balanced CQ21

DJ Mode Issues

DJ Mode shows black screen

Possible causes:

1. libmpv-2.dll not found — see installation fix above
2. No clips in library — run ingest first (minimum 50 clips for DJ Mode)
3. Virtual clips with moved source files — if you ingested with --skip-clip-export and then moved the source files, the pointers are broken

Clips play with a flash at the start

Symptom: Brief flicker of the first frame before the clip plays from the correct start time

Fix: This is a known issue with virtual (pointer-only) clips when hr_seek is enabled. Onset uses start property injection to mitigate this. Ensure you’re running the latest version.

Keybinds don’t work

DJ Mode keybinds only work when the MPV window has focus. Click inside the playback window, then use:

• ↑/↓ — Energy tier
• ←/→ — Force clip transition
• / — CLIP text query
• G — Gold star clip
• B — Block clip
• ? — Show help overlay

Performance Tips

Speed up rendering

1. Use balanced quality — p4/CQ21 is 2–3× faster than maximum (p6/CQ17) with minimal visible quality loss
2. Use draft for previews — FFmpeg direct stitch at 720p, renders in ~30 seconds
3. Close Chrome — Chrome’s GPU process competes for VRAM with NVENC
4. Use physical clips — Virtual clips require FFmpeg seek per clip, which is slower than direct file reads

Speed up ingest

1. Use an NVMe SSD for both source files and the clips output directory
2. Ingest in pointer-only mode for large archives — skips the clip export step entirely
3. Start working during ingest — DJ Mode activates at 50 clips, Studio at 1 clip

Reduce disk usage

1. Use virtual ingest (Pointer Only mode) — zero disk usage beyond the SQLite database
2. After rendering, delete the chunks/ temp directory if it wasn’t auto-cleaned
3. Use draft quality for iterations, maximum quality only for final exports

Licensing

How to activate?

Click the tier badge button in the upper-right corner of the GUI to open the License & Activation dialog, paste your key, and click Activate.

Can I use on multiple machines?

The Demo tier allows 1 activation. The Core and Studio tiers allow up to 2 simultaneous activations.

What happens when license expires?

Onset Engine will revert to the Demo tier, capping exports at 30 FPS and 720p resolution. Read more.

Related Articles

• Autopilot
• DJ Mode