yuniirhm/ilinxa-capture

**Video frame extraction & composition service for AI vision pipelines.**
ilinxa capture extracts video frames and tiles them into 2×2 or 4×4 grid sheets
a multimodal LLM can read in one image — self-hosted, via a REST API, a Web UI,
or an MCP server. Instead of sending a model dozens of separate frames, you send
one contact sheet, with optional frame-number and timestamp overlays so the
model can still reason about time. One core engine backs all three interfaces,
reachable however your pipeline prefers:
| Interface | For | Entry point |
|---|---|---|
| **REST API** | Scripts, services, pipelines | /api/v1 |
| **Web UI** | Interactive use | / (3-step wizard) |
| **MCP server** | AI agents / MCP clients | stdio + Streamable HTTP |
Table of contents
- Demo
- Features
- Quick start
- Usage
- REST API
- Web UI
- MCP server
- Configuration
- Architecture
- Development
- Testing
- Security model
- FAQ
- Contributing
- Support
- License
Demo
Video in, one grid sheet out — 16 frames tiled into a single 4×4 image with
per-frame timestamp overlays, ready for a multimodal LLM. Watch the clip.
Features
- **Frame extraction** at 1–30 FPS via FFmpeg
- **Grid composition** into 1×1, 2×2, or 4×4 sheets via Sharp, with optional
frame-number / timestamp overlays
- **Quality presets** tuned for vision models: llm (1024 px, JPEG 80 %),
high (original resolution, PNG), or fully custom
- **Video download** from YouTube, Vimeo, and 1,000+ sites via yt-dlp, with
per-resolution presets or raw format selectors
- **HLS support**: parse master playlists, discover .m3u8 streams embedded
in web pages, download variants (custom headers supported for protected
streams)
- **Sync or async jobs** — async returns 202 + poll URL and supports
webhook notifications on completion
- **Streaming ZIP downloads** of frames, sheets, or both — never buffered in
memory
- **Self-maintaining storage**: TTL-based cleanup of finished jobs and
orphaned temp files; job state recovers across restarts (no database)
Quick start
Docker (recommended)
Open — the Web UI, REST API, and MCP HTTP endpoint are
all served from the same port. FFmpeg and yt-dlp are included in the image.
Local
Requires **Node 22+**, **FFmpeg** (with ffprobe) and **yt-dlp** on PATH.
For development with hot reload, see Development.
Usage
REST API
Extract frames and compose a 2×2 sheet in one call:
Or upload a file (multipart):
Add "async": true (or -F "async=true") to get an immediate 202 with a
poll URL instead of waiting for the result. Pass "webhook_url" to be called
back on completion.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/metadata | Probe a video (file upload or {source} URL) |
| POST | /api/v1/extract | Extract frames |
| POST | /api/v1/compose | Compose frames into grid sheets |
| POST | /api/v1/extract-and-compose | Both steps in one call |
| POST | /api/v1/video/formats | List downloadable formats for a URL |
| POST | /api/v1/video/download | Download a video (preset or raw selector) |
| POST | /api/v1/hls/discover | Scan a web page for embedded HLS streams |
| GET | /api/v1/jobs/:id | Job status / result |
| DELETE | /api/v1/jobs/:id | Delete a job and its files |
| GET | /api/v1/jobs/:id/download?include=frames\|sheets\|all | Streaming ZIP |
| GET | /api/v1/jobs/:id/video | Download a downloaded video file |
| GET | /api/v1/files/:jobId/* | Serve an individual frame/sheet |
| GET | /api/v1/health | Health check |
Errors are consistent JSON:
{ "error": { "code": "VALIDATION_ERROR", "message": "fps: expected number" } }
with meaningful HTTP status codes (400, 404, 410, 413, 500).
Full endpoint documentation with request/response schemas:
docs/GUIDE.md.
Web UI
A three-step wizard — **Extract → Preview & Compose → Output** — with file