Metadata-Version: 2.4
Name: vidxp
Version: 0.4.0
Summary: VidXP - Video indexing and search by dialogue, scene, and actor
Author: Muhammad Haroon, Talha Momin, Talha Amjad, Abdurrehman Subhani, Saad Bazaz
License-Expression: MIT
Project-URL: Homepage, https://github.com/grayhatdevelopers/vidxp
Project-URL: Repository, https://github.com/grayhatdevelopers/vidxp
Project-URL: Issues, https://github.com/grayhatdevelopers/vidxp/issues
Keywords: video,search,indexing,cli,streamlit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dbos<3,>=2.28
Requires-Dist: filelock<4,>=3.32
Requires-Dist: packaging<27,>=26.2
Requires-Dist: platformdirs<5,>=4.11
Requires-Dist: pydantic<3,>=2.13.4
Requires-Dist: pydantic-settings<3,>=2.14.2
Requires-Dist: pyjwt<3,>=2.13
Requires-Dist: rich<16,>=15
Requires-Dist: sqlalchemy<2.1,>=2.0.51
Requires-Dist: typer<1,>=0.27
Provides-Extra: storage
Requires-Dist: chromadb<2,>=1.5.9; extra == "storage"
Requires-Dist: psutil<8,>=7.2.2; extra == "storage"
Provides-Extra: dialogue
Requires-Dist: chromadb<2,>=1.5.9; extra == "dialogue"
Requires-Dist: psutil<8,>=7.2.2; extra == "dialogue"
Requires-Dist: faster-whisper<2,>=1.2.1; extra == "dialogue"
Requires-Dist: sentence-transformers<6,>=5.6.1; extra == "dialogue"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "dialogue"
Provides-Extra: scene
Requires-Dist: chromadb<2,>=1.5.9; extra == "scene"
Requires-Dist: psutil<8,>=7.2.2; extra == "scene"
Requires-Dist: numpy<3,>=2.3; extra == "scene"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "scene"
Requires-Dist: Pillow<13,>=12.3; extra == "scene"
Requires-Dist: torch<3,>=2.13; extra == "scene"
Requires-Dist: transformers<6,>=5.14.1; extra == "scene"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "scene"
Provides-Extra: actor
Requires-Dist: chromadb<2,>=1.5.9; extra == "actor"
Requires-Dist: psutil<8,>=7.2.2; extra == "actor"
Requires-Dist: numpy<3,>=2.3; extra == "actor"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "actor"
Requires-Dist: pooch<2,>=1.9; extra == "actor"
Provides-Extra: videoprism
Requires-Dist: chromadb<2,>=1.5.9; extra == "videoprism"
Requires-Dist: psutil<8,>=7.2.2; extra == "videoprism"
Requires-Dist: numpy<3,>=2.3; extra == "videoprism"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "videoprism"
Requires-Dist: torch<3,>=2.13; extra == "videoprism"
Requires-Dist: torchvision<1,>=0.28; extra == "videoprism"
Requires-Dist: transformers<6,>=5.14.1; extra == "videoprism"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "videoprism"
Provides-Extra: all
Requires-Dist: chromadb<2,>=1.5.9; extra == "all"
Requires-Dist: psutil<8,>=7.2.2; extra == "all"
Requires-Dist: faster-whisper<2,>=1.2.1; extra == "all"
Requires-Dist: sentence-transformers<6,>=5.6.1; extra == "all"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "all"
Requires-Dist: numpy<3,>=2.3; extra == "all"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "all"
Requires-Dist: Pillow<13,>=12.3; extra == "all"
Requires-Dist: torch<3,>=2.13; extra == "all"
Requires-Dist: transformers<6,>=5.14.1; extra == "all"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "all"
Requires-Dist: numpy<3,>=2.3; extra == "all"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "all"
Requires-Dist: pooch<2,>=1.9; extra == "all"
Requires-Dist: numpy<3,>=2.3; extra == "all"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "all"
Requires-Dist: torch<3,>=2.13; extra == "all"
Requires-Dist: torchvision<1,>=0.28; extra == "all"
Requires-Dist: transformers<6,>=5.14.1; extra == "all"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "all"
Provides-Extra: local-worker
Requires-Dist: chromadb<2,>=1.5.9; extra == "local-worker"
Requires-Dist: psutil<8,>=7.2.2; extra == "local-worker"
Requires-Dist: pydantic-ai-slim[openai]<3,>=2.13; extra == "local-worker"
Requires-Dist: faster-whisper<2,>=1.2.1; extra == "local-worker"
Requires-Dist: sentence-transformers<6,>=5.6.1; extra == "local-worker"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "local-worker"
Requires-Dist: numpy<3,>=2.3; extra == "local-worker"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "local-worker"
Requires-Dist: Pillow<13,>=12.3; extra == "local-worker"
Requires-Dist: torch<3,>=2.13; extra == "local-worker"
Requires-Dist: transformers<6,>=5.14.1; extra == "local-worker"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "local-worker"
Requires-Dist: numpy<3,>=2.3; extra == "local-worker"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "local-worker"
Requires-Dist: pooch<2,>=1.9; extra == "local-worker"
Requires-Dist: numpy<3,>=2.3; extra == "local-worker"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "local-worker"
Requires-Dist: torch<3,>=2.13; extra == "local-worker"
Requires-Dist: torchvision<1,>=0.28; extra == "local-worker"
Requires-Dist: transformers<6,>=5.14.1; extra == "local-worker"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "local-worker"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2.0; extra == "mcp"
Provides-Extra: slm
Requires-Dist: pydantic-ai-slim[openai]<3,>=2.13; extra == "slm"
Provides-Extra: server
Requires-Dist: asgi-correlation-id<6,>=5.0.1; extra == "server"
Requires-Dist: alembic<2,>=1.18.5; extra == "server"
Requires-Dist: fastapi<0.141,>=0.140.13; extra == "server"
Requires-Dist: psutil<8,>=7.2.2; extra == "server"
Requires-Dist: psycopg[binary]<4,>=3.3.4; extra == "server"
Requires-Dist: pyjwt[crypto]<3,>=2.13; extra == "server"
Requires-Dist: python-multipart<0.1,>=0.0.32; extra == "server"
Requires-Dist: uvicorn[standard]<0.52,>=0.51; extra == "server"
Requires-Dist: mcp<3,>=2.0; extra == "server"
Provides-Extra: server-worker
Requires-Dist: asgi-correlation-id<6,>=5.0.1; extra == "server-worker"
Requires-Dist: alembic<2,>=1.18.5; extra == "server-worker"
Requires-Dist: fastapi<0.141,>=0.140.13; extra == "server-worker"
Requires-Dist: psutil<8,>=7.2.2; extra == "server-worker"
Requires-Dist: psycopg[binary]<4,>=3.3.4; extra == "server-worker"
Requires-Dist: pyjwt[crypto]<3,>=2.13; extra == "server-worker"
Requires-Dist: python-multipart<0.1,>=0.0.32; extra == "server-worker"
Requires-Dist: uvicorn[standard]<0.52,>=0.51; extra == "server-worker"
Requires-Dist: chromadb-client<2,>=1.5.9; extra == "server-worker"
Requires-Dist: pydantic-ai-slim[openai]<3,>=2.13; extra == "server-worker"
Requires-Dist: faster-whisper<2,>=1.2.1; extra == "server-worker"
Requires-Dist: sentence-transformers<6,>=5.6.1; extra == "server-worker"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "server-worker"
Requires-Dist: numpy<3,>=2.3; extra == "server-worker"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "server-worker"
Requires-Dist: Pillow<13,>=12.3; extra == "server-worker"
Requires-Dist: torch<3,>=2.13; extra == "server-worker"
Requires-Dist: transformers<6,>=5.14.1; extra == "server-worker"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "server-worker"
Requires-Dist: numpy<3,>=2.3; extra == "server-worker"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "server-worker"
Requires-Dist: pooch<2,>=1.9; extra == "server-worker"
Requires-Dist: numpy<3,>=2.3; extra == "server-worker"
Requires-Dist: opencv-python-headless<6,>=5.0.0.93; extra == "server-worker"
Requires-Dist: torch<3,>=2.13; extra == "server-worker"
Requires-Dist: torchvision<1,>=0.28; extra == "server-worker"
Requires-Dist: transformers<6,>=5.14.1; extra == "server-worker"
Requires-Dist: huggingface-hub<2,>=1.25.1; extra == "server-worker"
Provides-Extra: test
Requires-Dist: httpx<0.29,>=0.28.1; extra == "test"
Requires-Dist: pytest<10,>=9.1.1; extra == "test"
Provides-Extra: frontend
Requires-Dist: streamlit<2,>=1.60; extra == "frontend"
Provides-Extra: benchmarks
Requires-Dist: srt<4,>=3.5; extra == "benchmarks"
Dynamic: license-file

<p align="center">
<a href="https://github.com/grayhatdevelopers/vidxp">
<img alt="VidXP logo" src="https://github.com/grayhatdevelopers/vidxp/blob/main/docs/images/logo.png?raw=true" width="180"/>
</a>
</p>
<h1 align="center">VidXP</h1>
<p align="center">
<em>Search video by what was said, what appeared on screen, and recurring faces.</em>
</p>
<p align="center">
  A local-first video search engine for people, applications, and AI agents.
</p>
<p align="center">
<strong>Dialogue search · Scene search · Action search · Actor grouping</strong>
</p>
<p align="center">
<a href="https://github.com/grayhatdevelopers/vidxp/releases/latest">
<img alt="Download VidXP desktop app" src="https://img.shields.io/badge/Download-Desktop_app-5865F2?style=for-the-badge&amp;logo=github"/>
</a>
</p>
<p align="center">
  Windows · Apple Silicon macOS · Linux
</p>
<p align="center">
<a href="https://pypi.org/project/vidxp/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/vidxp"/></a>
<a href="https://github.com/grayhatdevelopers/vidxp/pkgs/container/vidxp"><img alt="GHCR container" src="https://img.shields.io/badge/container-GHCR-blue"/></a>
<a href="https://github.com/grayhatdevelopers/vidxp/blob/main/LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/grayhatdevelopers/vidxp"/></a>
<a href="https://grayhat.studio/discord"><img alt="Discord" src="https://img.shields.io/discord/867124708473700363?logo=discord&amp;logoColor=white"/></a>
</p>

## Find the moment, not the timestamp

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.
- **Action search:** describe something that happens over several seconds.
- **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.

[![VidXP browser interface](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/images/video-screenshot.jpeg?raw=true)](https://www.linkedin.com/feed/update/urn:li:activity:7343569473720725505/)

## Start here

Choose the setup that fits how you want to use VidXP.

### 1. Desktop app

Download the installer for Windows, Apple Silicon macOS, or Linux from
[GitHub Releases](https://github.com/grayhatdevelopers/vidxp/releases).

Connect an existing VidXP installation or let the desktop app manage an isolated
runtime for you. See the
[Desktop installation instructions](https://github.com/grayhatdevelopers/vidxp/blob/main/INSTALLATION_GUIDE.md#desktop-app)
for supported setup options.

### 2. CLI and local AI assistants

For commands, scripts, and local AI assistants, install
[uv](https://docs.astral.sh/uv/getting-started/installation/), then run:

```bash
# Install the CPU edition
uv tool install --python 3.14 --torch-backend cpu "vidxp[local-worker,mcp]"

# Check FFmpeg, download models, and verify the installation
vidxp init
vidxp prepare
vidxp doctor

# Print the settings for a local MCP client
vidxp mcp-config
```

Add the browser interface with:

```bash
uv tool install --python 3.14 --torch-backend cpu \
  "vidxp[local-worker,mcp,frontend]"
vidxp ui
```

See the [installation guide](https://github.com/grayhatdevelopers/vidxp/blob/main/INSTALLATION_GUIDE.md) for client-specific MCP
configuration, the HTTP API, and remote server setup.

### 3. Docker for a server

Run the published all-in-one image on a home server or another single machine:

```bash
# Download the search models into the persistent volume
docker run --rm -it \
  -v vidxp-data:/var/lib/vidxp \
  ghcr.io/grayhatdevelopers/vidxp:latest \
  vidxp prepare

# Start the browser interface
docker run --rm --init \
  -p 8501:8501 \
  -v vidxp-data:/var/lib/vidxp \
  ghcr.io/grayhatdevelopers/vidxp:latest
```

For 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`](https://github.com/grayhatdevelopers/vidxp/blob/main/compose.coolify.yaml)—no repository build is required.
See the [Coolify guide](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/deployment/coolify.md) for the complete setup.

## What you can do today

- 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.

## A first search

The browser app guides you through importing and indexing. The same flow from
the command line is:

```bash
# 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 an action or event
vidxp search videoprism "a person opens a door and walks outside"

# 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.

## For applications and AI agents

Use the Python package to add selected VidXP capabilities directly to an
application, or use the HTTP API when VidXP runs as a service.

[![VidXP being used with ChatGPT Desktop AI](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/images/claude-with-vidxp.jpg?raw=true)](https://youtu.be/fa4Zx-bSOh4)

MCP lets AI clients add and index videos, search a library, ask grounded
questions, and return inspectable evidence such as boards, frames, and clips.
A local client can start VidXP as a program on the same computer. A hosted
client connects to a deployed VidXP server.

### Codex plugin and skills

VidXP is distributed as a Codex plugin through a Git marketplace hosted in
this GitHub repository. It includes three reusable workflows:

- install Desktop or the CLI and connect Codex;
- ingest and index videos; and
- find moments and return inspectable evidence.

Paste this into Codex:

```text
Add https://github.com/grayhatdevelopers/vidxp as a Git plugin marketplace, install the VidXP plugin, then use its $vidxp-install skill to set up VidXP on this computer.
```

VidXP Desktop can perform the same setup from its **Set up in Codex** button.

Compatible AI clients can show an interactive upload and evidence-review view.
Clients without that interface still receive the same workflow results through
ordinary MCP tools.

- [Python, HTTP, and MCP installation](https://github.com/grayhatdevelopers/vidxp/blob/main/INSTALLATION_GUIDE.md)
- [Local HTTP API and MCP server](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/local-api.md)
- [ChatGPT and Codex plugin integration](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/integrations/openai-plugin.md)
- [Optional capability packages](https://github.com/grayhatdevelopers/vidxp/blob/main/INSTALLATION_GUIDE.md#optional-dependency-extras)
- [Coolify server setup](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/deployment/coolify.md)

## Downloads and storage

First setup downloads only the models needed for the capabilities you select.
VidXP shows the download size and destination before it starts.

The Desktop-managed Python runtime and its selected dependencies can use
approximately 3 GiB.

| Capability | Approximate model download |
|---|---:|
| Dialogue search | 2.64 GiB |
| Scene search | 1.43 GiB |
| Action search | 0.93 GiB |
| Actor matching | 37 MiB |

A full local Desktop setup with every search capability uses approximately
8.1 GiB. Leave additional temporary space during installation and for 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.

## Product roadmap

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.

## Help and project links

- [Installation and troubleshooting](https://github.com/grayhatdevelopers/vidxp/blob/main/INSTALLATION_GUIDE.md)
- [Desktop development](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/desktop.md)
- [Coolify deployment](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/deployment/coolify.md)
- [Changelog](https://github.com/grayhatdevelopers/vidxp/blob/main/CHANGELOG.md)
- [Issue tracker](https://github.com/grayhatdevelopers/vidxp/issues)
- [MIT license](https://github.com/grayhatdevelopers/vidxp/blob/main/LICENSE)

## Contributing

Contributions are welcome. Read the
[contribution guide](https://github.com/grayhatdevelopers/vidxp/blob/main/docs/CONTRIBUTING.md) before opening a pull request.

## Credits

VidXP began as a student research project by:

- [Abdullah Mansoor](https://github.com/abdullahmansoor321)
- [Muhammad Haroon](https://github.com/haroon10725)
- [Sarah Jawaid](https://github.com/sarr266)
- [Talha Ahmed](https://github.com/talhaahmed1234)

The research was conducted with
[Dr Shahab Tahzeeb](https://scholar.google.com/citations?user=cryeRB0AAAAJ&amp;hl=en)
at [NED University of Engineering and Technology](https://www.neduet.edu.pk/)
and [Saad Bazaz](https://scholar.google.com/citations?user=mrJo09oAAAAJ&amp;hl=en)
at [Grayhat](https://grayhat.studio/).

VidXP is now built by [Grayhat](https://grayhat.studio/) and maintained by
community contributors.

Email: <info@grayhat.studio>
<a href="https://github.com/grayhatdevelopers/vidxp/graphs/contributors">
<img alt="VidXP contributors" src="https://contrib.rocks/image?repo=grayhatdevelopers/vidxp"/>
</a>
</info@grayhat.studio></media-id></media-id>
