This documentation is organized into clear sections for different user types and development phases.
- Installation Guide - Modern uv-based setup with CUDA support
- macOS specifics: see the macOS section inside the Installation Guide for libomp, Node, ffmpeg, and PATH fixes.
- Environment Setup - HuggingFace and configuration
- Python Development 2025 - Modern development practices with uv, Ruff, and Docker
- Getting Started - Quick start guide for new users
- Accessing Results - New: Downloading annotations and artifacts
- Configuration - Configuration guide
- Pipeline Specifications - Detailed pipeline documentation
- Scene Detection Guide - Scene detection usage
- Demo Commands - Example commands and workflows
- Troubleshooting - Common issues and solutions
If you are using the provided Docker/devcontainer images, a few convenience commands are available on PATH.
These are optional shortcuts; the canonical CLI remains uv run videoannotator ....
| Action | Shortcut | Equivalent |
|---|---|---|
| Initialize the database + create an admin token | setupdb --admin-email you@example.com --admin-username you |
uv run videoannotator setup-db --admin-email you@example.com --admin-username you |
| Run the VideoAnnotator CLI (any subcommand) | va ... |
uv run videoannotator ... |
| Start the API server (recommended defaults) | va |
uv run videoannotator |
| Start the API server (explicit subcommand) | server ... |
uv run videoannotator server ... |
| Generate a new API token | newtoken ... |
uv run videoannotator generate-token ... |
| List available pipelines (detailed) | va pipelines --detailed |
uv run videoannotator pipelines --detailed |
| Validate a config file | va config --validate configs/default.yaml |
uv run videoannotator config --validate configs/default.yaml |
| Submit a processing job | va job submit video.mp4 --pipelines scene,person |
uv run videoannotator job submit video.mp4 --pipelines scene,person |
| Check job status | va job status <job_id> |
uv run videoannotator job status <job_id> |
| List jobs | va job list |
uv run videoannotator job list |
| Run all tests (quick/quiet) | vatest |
uv run pytest -q |
| Run some tests (quick/quiet) | vatest tests/unit/ |
uv run pytest -q tests/unit/ |
For more copy-pasteable CLI workflows, see usage/demo_commands.md.
- Docker Guide - Container deployment (Docker Compose-first)
- Roadmap Overview (Archived) - Historical release strategy notes
- v1.4.0 Roadmap - Roadmap for the v1.4.0 cycle
- v1.5.0 Roadmap - Roadmap for the v1.5.0 cycle
- Examples CLI Update Plan - CLI modernization checklist
- Testing Overview - Complete testing strategy and results
- Testing Standards - Quality assurance standards
- Batch Testing Guide - Batch processing test procedures
Historical and superseded documentation lives under archive/:
- Archive Root - Top-level archive index
- Release Notes - Historical release notes
- Development (Archived) - Completed roadmaps, checklists, and completion summaries
- Testing (Archived) - Historical QA checklists
- Dated Updates - Dated update memos
- v1.3.0 (Future Release) - Advanced features, security, and scalability enhancements