DOCUMENTATION

Aegis Video Organizer Documentation

Aegis Video Organizer turns folders full of video files into a searchable library. It finds your videos, generates scene thumbnails, uses local AI models to describe what happens in each scene, recognizes the people who appear, and lets you search in plain language. Built-in tools let you watch, stream to your phone, trim, merge, convert and upscale your videos.

Everything runs on your own computer. Your videos and the information extracted from them are never uploaded anywhere.

This guide covers version 1.3. See the in-app Release Notes for what changed in each version.

Installation & First Run

Aegis Video Organizer runs on Linux and Windows. See the download page for details.

Linux

Install the Snap, or the Debian/Ubuntu .deb package from the download page. Both include the video and AI libraries the app needs.

sudo snap install aegisvideoorganizer

Windows

Install from the Microsoft Store, where the app is listed as AegisVideoManager. The Store keeps it up to date automatically.

Local AI (optional)

Scene descriptions and semantic search use models running locally through Ollama. See our Ollama setup guide, then pull a vision model and an embedding model, for example:

ollama pull llama3.2-vision:11b
ollama pull nomic-embed-text

Our guide to choosing a vision model helps if your computer has less memory or no GPU. vLLM is also supported as a backend. Without a local model you can still discover, browse, play, stream and edit your videos.

First run

Choose a Dark or Light appearance. You can change it later in Configure.
Click Configure Source Directories… and add the folders where your videos are stored. You can add or remove folders at any time.
Click Start Background Processing. The app starts finding and analysing your videos while you browse.

Background Processing

Your library is built by a pipeline that always runs its steps in this order:

Step	What it does
Find Videos	Scans your source folders and reads each video's duration, resolution, codecs, bitrate and audio tracks. Moved and copied files are recognized, so nothing is processed twice.
Thumbnails	Extracts scene thumbnails using all CPU cores.
LLM Metadata	A local vision model describes each scene — objects, setting, actions, clothing, and whether it contains explicit content — and summarizes the whole video, including its category (music video, home movie, podcast…), source (YouTube, DVD, web…) and performers or band.
Embeddings	Indexes the descriptions for natural-language search.
Faces	Detects faces in the scenes and groups them into people.

With automatic processing enabled, the pipeline runs shortly after startup and every five minutes after that, picking up new videos.
The 🧠 AI Processing quick tool in the sidebar starts the full pipeline on demand.
The Batch Actions dialog shows the current step in its Full Pipeline card, with Start, Stop and Log buttons for each step.
A step that fails, is stopped or has nothing to do never stalls the pipeline; it moves on to the next step.
To run a single step, click its card's Start. Turn on Refresh existing data to reprocess videos that were already done.
Stop on a card stops that step; ■ Stop All cancels the pipeline and stops every background process. An interrupted step resumes where it left off the next time it runs.

Browsing the Library

The Library view shows your videos as a grid of cards. Move the mouse across a card to scrub through its scene thumbnails (or let them cycle automatically — see Configure → General). DVDs carry a DVD badge. The small coloured chiclets under a thumbnail are people and tags: click one to filter the library by it.

Ratings: rate videos from −1 (Poor) to 4 (Must Keep) with ⭐ Set Rating, and filter by rating.
Collections: add a video to the active collection, or remove it, with the buttons on its thumbnail. Manage collections in the Collections Manager.
Properties: right-click a video and choose Properties to see every scene thumbnail next to its AI description, actions and detected objects.
Editing metadata: category, source and performer can be edited in the side panel, in Properties, or in the Metadata Edit window.

Search & Filters

Search

Type in Search videos… to search names and descriptions. Switch on 🧠 Semantic search to search by meaning: "kids playing in the snow" finds matching scenes even if those exact words never appear.

Filters

The sidebar has multi-select filters for resolution, duration, file size, file type and star rating, plus the AI filters: actors, actions, tags, performer / band, category and source. Combine as many as you like. Lists with more than seven entries open a search-and-select dialog.

The Explicit Content Filter in Configure → General hides explicit videos, shows only explicit videos, or shows everything.

Sidebar styles

Choose a layout in Configure → General:

Elevated Studio (default) — card-based groups with active-filter counts.
Compact Fluent — a single card with a bar of active-filter chips and quick clear.
Tabbed Studio Deck — separate tabs for Filters, Collections and Tools.

People & Faces

The People view groups the faces found in your videos into people. Give a person a name and every video they appear in is a click away; named people are kept when new videos are processed.

Click the ⓘ button on a person card, or double-click the card, to open the person's details. The Similar Faces tab finds look-alike faces to merge.
Face Workbench: with the workbench open, click a person's thumbnail to list their most similar faces from other identities. Drag faces onto the person (or onto any person card) to merge them, select several and click Merge Selected, or drag a whole person card into the workbench to merge that person.
Rename: right-click a person and choose Rename; the name appears in every filter straight away.
Merge into…: Ctrl+click several people, right-click and merge them when the AI split one person into several.
Forget: deletes a person and their face data.
Click a person, or their chiclet in the Library, to see every video they appear in.

Merges happen immediately, and people left without any faces are removed.

Word Cloud & Analytics

The Word Cloud view shows the most frequent tags, actions and objects in your library; click a word to filter by it.

The Analytics view charts your library: formats, resolutions, durations, storage, and how much of the library each AI step has processed.

Player & Playlists

The built-in player has a scene strip for jumping straight to any scene, and remembers your audio output device. Double-click the video for full screen; Next and Previous move through the videos in your current filtered set. If a video is already playing when you start another, you choose: Play Right Away, Queue in Playlist, or Play Concurrently side by side.

Playlists: select videos and choose Add to Playlist, then reorder and play them from the Playlist Manager.
Auto Mix: loops through the videos in the current grid, playing a few seconds of each before moving on — ideal for reviewing a large set. Set the clip length in Configure → Auto Mix.
VLC: any video can also be opened in VLC.

DVD Playback

DVD folders (VIDEO_TS) — such as those made by Aegis DVD Backup — are part of your library. Scene thumbnails and AI analysis cover the whole disc, not just its first file. Choose whether DVDs play in the built-in player or in VLC (which supports DVD menus) under Configure → General.

Stream to Phone

Watch any video on a phone or tablet on the same Wi-Fi or local network, in the phone's web browser — no app needed.

Click 📱 Stream in the side panel or in the video's Properties.
Scan the QR code with your phone's camera — or copy the link and open it on any device on the same network.

To stream a whole playlist, select it in the Playlist Manager and click 📱 Stream to Phone. The phone gets a playlist player with thumbnails, Previous / Next, and Auto ▶ to continue with the next video. Tap any video to jump to it.

Videos the phone can't play directly — DVDs, AVI and many MKV files — are converted automatically. Conversions are cached, so the next stream starts instantly.
Playlist videos are prepared in playback order, so playback starts as soon as the first one is ready; a video that is still converting shows its progress.
The dialog shows when a device connects. The stream stops when you close the dialog.

If your phone can't connect and a firewall is active, the dialog shows the command to run to allow the connection.

Workbench Tools

Open the Workbench from the sidebar's Tools panel. Every tool runs in the background and can be cancelled.

Tool	What it does
Upscale (Video2X)	AI super-resolution and frame interpolation.
Merge	Joins several clips into one video, in the order you choose.
Aspect Ratio	Converts to 16:9, 9:16, 4:3, 1:1 or 21:9, with pan-and-scan or pillarbox.
Extract Audio	Saves the soundtrack as MP3, AAC, FLAC, WAV or OGG.
Plot Description	Writes a storyline summary from the scene descriptions.

Cutting Room

A frame-accurate editor for trimming. Open a video with ✂ Open in Cutting Room, scrub along the timeline strip and set In and Out points. Add several segments to build a multi-cut timeline, then export with fast lossless stream copy or by re-encoding.

Configure

Tab	Settings
General	Appearance, sidebar style, explicit content filter, thumbnail animation (cycle or mouse scrub), auto-scan of new videos, DVD player choice.
Sources	The folders that make up your library — local folders or mounted network drives.
Background Actions	Automatic processing.
Scene Thumbnails	How often a scene thumbnail is taken (every 2 minutes of video by default).
LLM Options / LLM Prompts	Backend (Ollama or vLLM), model, concurrency (match it to your GPU memory), and the prompts used for analysis — with a built-in test tool to check the connection and try prompts.
Face Recognition	Face detection and grouping.
Auto Mix	How long each clip plays in Auto Mix.
Database	Library database maintenance.
Add-ons	Install or remove optional Python packages, and see which hardware acceleration is available.

Window size, panel layout and the active view are remembered between sessions.

How It Works

Each pipeline step runs as its own background process, so the window stays responsive and a problem in one step can't take down the app. Progress is shown in the status bar and in Batch Actions.

Duplicates: files are identified by a fast fingerprint (the first and last megabyte plus the file size), so moved or copied videos are recognized without being processed again.
Storage: the library is a local SQLite database. Thumbnails, status files, logs and the streaming conversion cache live in the app's data folder.
Closing with work in progress: if jobs are still running when you quit, the app lists them and lets you Wait or Exit & Terminate Jobs, which stops them cleanly and removes incomplete files.

Your Data & Privacy

No cloud, no account, no telemetry. AI models run on your own computer.
On Linux, your library data lives in ~/.AegisVideoOrganizer/ (with the Snap, under ~/snap/aegisvideoorganizer/current/). On Windows it is kept in your user profile.
Your videos are never modified by the library. Workbench and Cutting Room tools always write new files.
When streaming, videos are served only to devices on your local network while the Stream dialog is open.

Licensing

Aegis Video Organizer is free to try: without a license, the library shows up to 2,000 videos (the status bar says how many more a license would show). A one-time Pro or Max license raises the limit — see pricing. No subscription.

To activate, open License from the Help area and enter the email address, license name (for example aegispro or aegismax) and license key from your purchase confirmation.

Troubleshooting

No scene descriptions appear

Check that Ollama (or vLLM) is installed and the model selected in Configure → LLM Options is pulled. The extractor starts the backend automatically if it isn't running. Use the LLM test tool in Configure to check the connection, and the step's Log button in Batch Actions to see what happened.

Processing seems stuck

Open Batch Actions to see which step is running. A failed or stopped step never blocks the rest; Stop All cancels the whole pipeline.

My phone can't connect when streaming

Phone and computer must be on the same network. If a firewall is active, run the command shown in the Stream dialog.

A video won't play in the built-in player

Open it in VLC instead, or choose VLC for DVDs in Configure → General.

Reporting a problem

Use Support in the app's Help area, or email support@yourprivacysw.com.

Contact Support