diff --git a/CITATION.cff b/CITATION.cff index 309ea2a..d5c2f4b 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -28,5 +28,5 @@ authors: orcid: "https://orcid.org/0000-0001-5846-3444" license: "MIT" repository-code: "https://github.com/InfantLab/VideoAnnotator" -version: "1.4.2" -date-released: "2026-03-04" +version: "1.4.4" +date-released: "2026-07-08" diff --git a/README.md b/README.md index 6ca3869..ae4a660 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ VideoAnnotator automatically analyzes videos of human interactions and extracts ## 🖥️ Complete Solution: Processing + Visualization -VideoAnnotator provides both **automated processing** and **interactive visualization**: +VideoAnnotator provides both **automated processing** and **interactive visualization** — and installing this repository gets you both, no separate setup required. ### 📹 **VideoAnnotator** (this repository) @@ -34,8 +34,9 @@ VideoAnnotator provides both **automated processing** and **interactive visualiz - REST API for integration with research workflows - Supports batch processing and custom configurations - Outputs standardized JSON data +- Bundles **[Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer)**, served at `/viewer` -### 🌐 **[Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer)** (paired repository) +### 🌐 **[Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer)** (companion project, bundled here) **Interactive web-based visualization tool** @@ -43,8 +44,25 @@ VideoAnnotator provides both **automated processing** and **interactive visualiz - Synchronized video playback with annotation overlays - Timeline scrubbing with pose, face, and audio data - Export tools for further analysis +- Also fully independent: usable standalone with output from any tool that produces COCO/WebVTT/RTTM/scene-JSON files, no VideoAnnotator install required -**Complete workflow**: `Your Videos → [VideoAnnotator Processing] → Annotation Data → [Video Annotation Viewer] → Interactive Analysis` +
+ Running Video Annotation Viewer standalone (without VideoAnnotator) + + ```bash + git clone https://github.com/InfantLab/video-annotation-viewer.git + cd video-annotation-viewer + npm install + npm run dev + ``` + + Note: Ensure Node and NPM are installed. On macOS with Homebrew: `brew install node`. Open + http://localhost:3000 and load your files, or connect it to a VideoAnnotator server via `.env` or + the in-app Settings page — see that repo's README for details. + +
+ +**Complete workflow**: `Your Videos → [VideoAnnotator Processing] → Annotation Data → [Video Annotation Viewer, at /viewer] → Interactive Analysis` ## 🚀 Get Started in 60 Seconds @@ -82,20 +100,19 @@ curl -X POST "http://localhost:18011/api/v1/jobs/" \ ### 3. Visualize Results -```bash -# Install the companion web viewer -git clone https://github.com/InfantLab/video-annotation-viewer.git -cd video-annotation-viewer -npm install -npm run dev -``` +No extra install needed — VideoAnnotator bundles [Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer) and serves it directly: -Note: Ensure Node and NPM are installed. On macOS with Homebrew: `brew install node` +``` +Open http://localhost:18011/viewer +``` -Open http://localhost:3000 and load your VideoAnnotator results. +It's pre-configured to talk to this server, so your job results are one click away. Set `VIDEOANNOTATOR_ENABLE_VIEWER=false` if you'd rather not serve it. **🎉 That's it!** You now have both automated video processing and interactive visualization. +(Want to run Video Annotation Viewer on its own, without VideoAnnotator? See the standalone option +in the "Complete Solution: Processing + Visualization" section above.) + ## 🧠 AI Pipelines & Capabilities Authoritative pipeline metadata (names, tasks, modalities, capabilities) is generated from the registry: @@ -223,7 +240,7 @@ VideoAnnotator produces machine-readable outputs (primarily JSON files and API r - **Python**: Load JSON into pandas / numpy for analysis (see [examples/](examples/)) - **R / MATLAB**: Not currently supported with official helper packages, but the JSON outputs can be consumed using standard JSON readers -- **Visualization**: Use the companion [Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer) for interactive playback + overlays +- **Visualization**: Bundled [Video Annotation Viewer](https://github.com/InfantLab/video-annotation-viewer) at `/viewer` for interactive playback + overlays; also runs standalone against output from other tools ## 🛠️ Installation Options diff --git a/docs/README.md b/docs/README.md index 6383b42..3c90157 100644 --- a/docs/README.md +++ b/docs/README.md @@ -55,7 +55,9 @@ For more copy-pasteable CLI workflows, see `usage/demo_commands.md`. - **[Roadmap Overview (Archived)](archive/development/roadmap_overview.md)** - Historical release strategy notes - [v1.4.0 Roadmap](development/roadmap_v1.4.0.md) - Roadmap for the v1.4.0 cycle -- [v1.5.0 Roadmap](development/roadmap_v1.5.0.md) - Roadmap for the v1.5.0 cycle +- [v1.5.0 Roadmap](development/roadmap_v1.5.0.md) - Modularity & integration release (JOSS resubmission response) +- [v1.6.0 Roadmap](development/roadmap_v1.6.0.md) - Plugin ecosystem & local LLM (Ollama/llama.cpp) backends +- [Modular Pipeline Architecture Spec](../specs/003-modular-pipeline-architecture/spec.md) - Full design spec underlying v1.5.0/v1.6.0 - [Examples CLI Update Plan](development/EXAMPLES_CLI_UPDATE_CHECKLIST.md) - CLI modernization checklist ## 🧪 Testing & QA diff --git a/docs/archive/development/roadmap_v1.5.0_ux_wishlist.md b/docs/archive/development/roadmap_v1.5.0_ux_wishlist.md new file mode 100644 index 0000000..4e1543f --- /dev/null +++ b/docs/archive/development/roadmap_v1.5.0_ux_wishlist.md @@ -0,0 +1,496 @@ +# Archived: Original v1.5.0 UX Wishlist (Deferred, Unscheduled) + +**Archived**: 2026-07-08 +**Reason**: The JOSS pre-review of VideoAnnotator (#10182) and Video Annotation Viewer (#10183) raised +concerns about install footprint, monolithic packaging, and evidence of active cross-project integration. +Responding to that feedback took priority over this wishlist, so the v1.5.0 and v1.6.0 slots were +reassigned to the modular-pipeline-architecture work and the FastAPI/VAV integration +(see [`roadmap_v1.5.0.md`](../../development/roadmap_v1.5.0.md)) and to plugin ecosystem + local LLM +backend support (see [`roadmap_v1.6.0.md`](../../development/roadmap_v1.6.0.md)). + +The content below is the original v1.5.0 plan, preserved as-is. None of it has been done; it has no +committed release slot. Revisit and re-prioritize into a future roadmap (v1.7.0+) once the modularity +and integration work lands. + +--- + +# 🚀 VideoAnnotator v1.5.0 Development Roadmap + +## Release Overview + +VideoAnnotator v1.5.0 is the **Feature Enhancement Release** - bringing all the wishlist items that were intentionally deferred from v1.4.0 to keep the JOSS release focused. This release adds usability improvements, advanced features, and quality enhancements that make VideoAnnotator more powerful and easier to use. + +**Target Release**: Q3 2026 (3-4 months after v1.4.0) +**Current Status**: Planning Phase +**Main Goal**: Enhanced usability and advanced capabilities +**Duration**: 12-14 weeks + +**Prerequisites**: v1.4.0 delivered JOSS publication foundation: +- ✅ JOSS paper submitted/accepted +- ✅ PyPI package published +- ✅ 4 research workflow examples +- ✅ Docker images (CPU/GPU) +- ✅ Core documentation complete +- ✅ Multi-platform testing + +--- + +## 🎯 Core Principles + +This release focuses on enhancing the user experience and adding advanced capabilities: + +- ✅ **Usability First** - Progress indicators, wizards, intuitive workflows +- ✅ **Quality & Performance** - Assessment pipelines, batch optimization +- ✅ **Integration** - FiftyOne, Label Studio, flexible exports +- ✅ **Developer Experience** - Better logging, debugging, analysis tools +- ✅ **Advanced Features** - Quality metrics, comparison tools, smart scheduling + +**Still OUT OF SCOPE** (deferred to v1.6.0+): +- ❌ Enterprise features (SSO, RBAC, multi-tenancy) +- ❌ Plugin system architecture +- ❌ Real-time streaming +- ❌ GraphQL API +- ❌ Cloud provider integration +- ❌ Microservice architecture + +--- + +## 📋 Feature Categories + +All items in v1.5.0 were deferred from v1.4.0 to maintain JOSS focus. They are organized into logical feature groups: + +### Category A: Installation & Setup +- Model auto-download with progress +- Setup wizard for first-run +- Enhanced health metrics + +### Category B: Progress & Feedback +- Real-time progress indicators +- Resource usage monitoring +- Job notifications + +### Category C: Configuration +- Interactive config wizard +- Config templates library +- YAML validation improvements + +### Category D: Logging & Debugging +- Structured logging (JSON) +- Log analysis tools +- Enhanced version info + +### Category E: Export & Integration +- FiftyOne integration +- Label Studio integration +- Custom CSV templates + +### Category F: Quality & Performance +- Quality assessment pipeline +- Batch processing optimization +- Pipeline comparison tools + +--- + +## 📋 v1.5.0 Deliverables + +### Phase 1: Installation & Setup Improvements (Weeks 1-2) + +#### 1.1 Model Auto-Download System + +**Problem**: Users must manually download large model files before first use. + +**Solution**: +- [ ] Automatic model download on first use (not during pip install) +- [ ] Progress bar with download speed and ETA +- [ ] Configurable cache directory (`VIDEOANNOTATOR_MODEL_CACHE`) +- [ ] Offline mode (use cached models only) +- [ ] Manual download script for air-gapped systems + +**Deliverables**: +- `src/videoannotator/models/downloader.py` - Auto-download logic +- Progress indicators using `tqdm` +- Offline mode flag and detection +- Documentation in `docs/installation/models.md` + +**Effort**: 16 hours + +#### 1.2 First-Run Setup Wizard + +**Problem**: New users don't know what to configure. + +**Solution**: +- [ ] `videoannotator setup` command for first-run configuration +- [ ] Interactive prompts: + - Detect GPU availability (CUDA/ROCm) + - Set storage directory + - Generate API token + - Select common pipelines to cache + - Test installation with sample video +- [ ] Non-interactive mode with flags +- [ ] Skip wizard option (for CI/automated deployments) + +**Deliverables**: +- `src/videoannotator/cli/setup.py` - Setup wizard +- ASCII-safe prompts for Windows compatibility +- Documentation in `docs/usage/setup_wizard.md` + +**Effort**: 12 hours + +#### 1.3 Enhanced Health & Version Endpoints + +**Problem**: Limited diagnostic information available via API. + +**Solution**: +- [ ] `/api/v1/system/version` endpoint +- [ ] Enhanced health endpoint with GPU memory, storage, uptime +- [ ] `videoannotator version --detailed` CLI command + +**Deliverables**: +- New version endpoint +- Enhanced health metrics +- CLI version command + +**Effort**: 12 hours + +**Checkpoint**: Installation experience improved (40 hours total) + +--- + +### Phase 2: Progress & Feedback (Weeks 3-4) + +#### 2.1 Real-Time Progress Indicators + +- [ ] Progress tracking (percentage, stage, ETA, frames processed) +- [ ] CLI progress bar using `rich` library +- [ ] API progress endpoint: `GET /api/v1/jobs/{id}/progress` +- [ ] WebSocket support for real-time updates (optional) + +**Effort**: 20 hours + +#### 2.2 Resource Usage Monitoring + +- [ ] Real-time CPU, GPU, RAM, disk I/O monitoring +- [ ] Include in health endpoint +- [ ] `videoannotator monitor` CLI command +- [ ] Configurable warning thresholds + +**Effort**: 16 hours + +#### 2.3 Job Completion Notifications + +- [ ] Pluggable notification system: + - Email (SMTP) + - Webhook (HTTP POST) + - Desktop notification (CLI mode) + - Slack integration + - Discord integration +- [ ] Per-job notification preferences +- [ ] Notification templates + +**Effort**: 20 hours + +**Checkpoint**: Progress and feedback complete (56 hours total) + +--- + +### Phase 3: Configuration & Validation (Weeks 5-6) + +#### 3.1 Interactive Config Wizard + +- [ ] `videoannotator config init --interactive` command +- [ ] Step-by-step prompts for common scenarios +- [ ] Hardware detection (GPU, memory, storage) +- [ ] Scenario selection (fast/balanced/high-quality) +- [ ] Validation and preview before saving + +**Effort**: 16 hours + +#### 3.2 Config Templates Library + +- [ ] Pre-built configuration templates: + - `templates/fast.yaml` - Quick processing (lower accuracy) + - `templates/balanced.yaml` - Default settings + - `templates/high-quality.yaml` - Best accuracy (slower) + - `templates/cpu-only.yaml` - No GPU required + - `templates/classroom.yaml` - Multi-person + audio + - `templates/clinical.yaml` - Face + emotion focus +- [ ] `videoannotator config list-templates` command +- [ ] `videoannotator config use