Search video by what was said, what appeared on screen, and recurring faces.
A local-first video search engine for people, applications, and AI agents.
Dialogue search · Scene search · Actor grouping
Windows · Apple Silicon macOS · Linux
VidXP makes one video—or an entire collection—searchable by meaning:
- Dialogue search: type what you remember someone saying and jump to the matching moments.
- Scene search: describe what appeared on screen and find the closest visual matches.
- Actor matching: find recurring faces within a video and export a highlighted video for a selected group.
Use it to search years of family videos, add video search to an editing workflow, or let an AI agent answer questions using evidence from your own video library. Your videos can stay on your machine.
Choose the setup that fits how you want to use VidXP.
For direct use, scripts, and local AI agents, install uv, then run:
# Install the CPU edition
uv tool install --python 3.14 --torch-backend cpu "vidxp[local-worker,mcp]"
# Set up FFmpeg
vidxp init
# Download search models
vidxp prepare
# Check everything
vidxp doctor
# Connect an MCP client
vidxp mcp-configAdd the browser interface with:
uv tool install --python 3.14 --torch-backend cpu \
"vidxp[local-worker,mcp,frontend]"
vidxp uiSee the installation guide for client-specific MCP configuration, the HTTP API, and remote server setup.
Download the installer for Windows, Apple Silicon macOS, or Linux from GitHub Releases.
Connect an existing VidXP installation or let the desktop app manage an isolated runtime for you. See the desktop guide for supported setup options.
Run the published all-in-one image on a home server or another single machine:
docker run --rm --init \
-p 8501:8501 \
-v vidxp-data:/var/lib/vidxp \
ghcr.io/grayhatdevelopers/vidxp:latestFor a long-lived server, pin a published version instead of latest. For a
Coolify deployment, use the published -control and -worker images with
compose.coolify.yaml—no repository build is required.
See the Coolify guide for the complete setup.
- Build searchable libraries from individual videos or whole collections.
- Find dialogue by meaning and visual moments by describing the scene.
- Ask grounded questions and inspect the supporting boards, frames, or clips.
- Group recurring faces and render highlighted actor overlays.
- Keep personal, client, or project libraries separate.
- Use VidXP through the desktop app, browser, CLI, MCP, or HTTP API.
The browser app guides you through importing and indexing. The same flow from the command line is:
# Add a video
vidxp media import samplevideo.mp4 --json
# Index the returned media ID
vidxp index create <media-id>
# Find a visual moment
vidxp search scene "a yellow taxi on a city street"
# Find something that was said
vidxp search dialogue "the bread just came out of the oven"Results include the source video, timestamps, match score, and the evidence
used to find the moment. Add --media-id <media-id> to search only one video.
Run vidxp --help or vidxp <command> --help for the full command reference.
Use the Python package to add selected VidXP capabilities directly to an application, or use the HTTP API when VidXP runs as a service.
MCP lets AI clients add and index videos, search dialogue and scenes, ask questions about a library, and return inspectable evidence such as boards, frames, and clips. Clients can connect locally over stdio or to a self-hosted VidXP server.
VidXP includes reusable skill source folders for the two common agent workflows:
Download a skill folder and add it through a supported ChatGPT desktop or Codex Skills surface. The skills require a connected VidXP MCP server; installable plugin packaging for additional ChatGPT surfaces will follow separately.
First setup downloads only the models needed for the capabilities you select. VidXP shows the download size and destination before it starts.
| Capability | Approximate model download |
|---|---|
| Dialogue search | 2.64 GiB |
| Scene search | 1.43 GiB |
| Actor matching | 37 MiB |
Leave additional space for the VidXP runtime, indexes, source videos, and exported results.
By default, the CLI and desktop app share the same VidXP data directory:
| Platform | Default location |
|---|---|
| Windows | %LOCALAPPDATA%\VidXP |
| macOS | ~/Library/Application Support/VidXP |
| Linux | ${XDG_DATA_HOME:-~/.local/share}/VidXP |
Docker keeps the same data in the vidxp-data volume shown above.
The next product improvements are focused on:
- labeling actor groups and matching the same person across different videos;
- more reliable face tracking across angle, lighting, motion, and occlusion;
- connecting visible people with the dialogue they are speaking;
- better search ranking, time ranges, and natural-language questions across a whole library;
- richer previews, timelines, filters, saved searches, and result playback;
- easier organization for large personal and project video collections;
- faster indexing and supported GPU acceleration; and
- smoother desktop updates, repair, and model management.
VidXP is in beta. Feedback about search quality, actor workflows, and real video-library use cases is especially useful.
- Installation and troubleshooting
- Desktop application
- Coolify deployment
- Changelog
- Issue tracker
- MIT license
Contributions are welcome. Read the contribution guide before opening a pull request.
Built by Grayhat Developers PVT Ltd. and maintained by the community. Originally researched by students:
Working with Dr Shahab Tahzeeb (NED University of Engineering and Technology) and Saad Bazaz (Grayhat).
Email: info@grayhat.studio