arkiv：面向 DIT 工作流的本地优先 AI 元数据层，原生接入 DaVinci Resolve

Source-available AI metadata layer for DIT workflows — Resolve-native, CJK-first.

🌐 English | 繁體中文

📦 Looking for the application? → https://vulture-s.github.io/arkiv/ — downloads, capabilities, and licence terms on a single page. Free for any purpose, commercial use included.

arkiv sits between your media drive and DaVinci Resolve: it ingests your footage, attaches AI-generated metadata (transcript, vision tags, atmosphere, energy, edit position), and surfaces clips via semantic search in any language — Chinese, Japanese, or English. The Resolve plugin lets you search, import with clip color, and drop frame markers without leaving the NLE.

Designed for solo DITs and small crews who own their data: local-first, self-hosted, source-available (PolyForm Perimeter), no cloud dependency.

Why arkiv

• Too much footage, can't find the shot → search in plain language ("all dusk establishing shots from May"), in Chinese / Japanese / English — it searches what's in the frame and the transcript, not filenames.
• AI editing tools only understand footage with someone talking → arkiv runs vision analysis + transcription on every clip, so B-roll and dialogue-free footage stay searchable and manageable.
• Your library has to feed any downstream edit → manual, automated, or script-driven: native Resolve plugin, EDL / FCPXML export, API / MCP interface.

License in one line: arkiv is free to use for any purpose, commercial work included (source-available); what you make with it is 100% yours. Off-limits: turning arkiv into a product that competes with it, and modifying it to get past the free-tier allowance.

Proven at scale: fully indexed a 1,506-clip real production library (1,161 of them dialogue-free B-roll) on a single RTX 4070.

Screenshots

System architecture & data flow (for contributors / fork authors)

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│  index.html │◄──►│  server.py   │◄──►│   db.py      │
│  (Tailwind) │    │  (FastAPI)   │    │  (SQLite)    │
└─────────────┘    └──────┬───────┘    └─────────────┘
                          │
                   ┌──────┴───────┐
                   │  embed.py    │◄──► ChromaDB
                   │  (Ollama)    │     (bge-m3)
                   └──────────────┘

  ═══════════════ Ingest Pipeline (2-Phase) ═══════════════

  Phase 1: Probe + Transcribe + LLM Polish
  ┌───────────┐ ┌─────────────┐ ┌──────────────┐
  │ ingest.py │→│transcribe.py│→│ qwen2.5:14b  │
  │ (FFmpeg)  │ │(Whisper+VAD)│ │ (LLM polish) │
  └───────────┘ └─────────────┘ └──────────────┘
       │              ↑
       │         Silero VAD
       │        (silence filter)
       ▼
  Phase 2: Vision (after unloading LLM from VRAM)
  ┌─────────┐  ┌──────────────┐
  │frames.py│→ │  vision.py   │
  │(extract)│  │(qwen2.5vl:7b) │
  └─────────┘  └──────────────┘

→ Full pipeline (4 stages, storage layout, exit codes, maintenance modes): docs/pipeline.md · architecture overview ARCHITECTURE.md

Features

Find footage

• Semantic search (Chinese / English / Japanese) — searches what's in the frame and the transcript, not filenames
• Library Chat: compilation search, refine the previous result, find similar shots, analytics — with conversation memory
• Ratings (GOOD / NG / Review) plus auto and manual tags with autocomplete

AI metadata

• Whisper large-v3-turbo transcription + a 4-layer anti-hallucination guard (VAD silence filter → no_speech threshold → blank/repeat filter → LLM correction)
• Frame vision analysis with brand/object recognition; 360 footage (Insta360 / GoPro Max) reprojected before indexing
• Chinese transcripts stored as Taiwan Traditional (plus a batch converter for an existing library)
• Full camera metadata: EXIF + Sony XAVC sidecar, so FX-series footage keeps its identity

On-set DIT

• Card offload: parallel multi-destination copy + per-file hash verify + resumable, and it never deletes the source card
• ASC MHL v2 hash manifests (interop-verified against the ASC reference implementation)
• Camera report CSV, auto-offload on card insert, browser DIT console (/dit)

Into the edit

• DaVinci Resolve plugin: search, import with clip color, add frame markers
• Export SRT / VTT / TXT / EDL (DF/NDF) / FCPXML 1.8, plus metadata CSV straight into Resolve
• Web UI, CLI and API all work on the same library

Full feature list (including advanced options)

• Semantic search — query in natural language (Chinese/English/Japanese)
• Chat RAG over your video library — 5-intent assistant for compilation searches, refinement, similarity, analytics, and general questions with persisted conversation memory
• AI transcription — Whisper large-v3-turbo + Silero VAD + LLM polish (Apple Silicon MLX / NVIDIA CUDA)
• 4-layer anti-hallucination guard — VAD silence filter → no_speech threshold → blank/repeat filter → LLM correction
• Frame analysis — qwen2.5vl:7b vision descriptions with brand/object recognition
• 2-phase pipeline — transcribe first, unload LLM, then vision (avoids VRAM conflict on 12GB GPUs)
• Rating system — GOOD / NG / Review with notes + clip color in Resolve
• Tag system — auto (AI) + manual tags with autocomplete
• DaVinci Resolve UI — dark theme, 3-panel layout, filmstrip, waveform
• Export — SRT, VTT, TXT, EDL (drop-frame TC), FCPXML 1.8 (FCPX + DaVinci compatible)
• DaVinci Resolve metadata CSV — /api/export/metadata-csv endpoint exports clip metadata (Camera/Lens/ISO/Shutter/Aperture/GPS/CreateDate) ready for Resolve's File → Import Metadata from CSV. Plugin auto-prompts after import
• ExifTool integration — auto-extracts 12 fields per clip (Make/Model/LensModel/GPS/ColorSpace/ISO/Shutter/Aperture/FocalLength/CreateDate). Sidecar-aware for Sony XAVC .XML, iPhone Keys group, Blackmagic Cam app per-vendor lens tags. Auto-detects exiftool binary on Windows (winget/scoop/chocolatey/Program Files)
• EDL reel name — uses ExifTool ReelName with safe fallback to filename stem (8-char CMX3600 compat, control-char sanitized)
• HEVC/ProRes browser proxy — auto-builds H.264 proxy on demand for browser playback
• Tauri native app — desktop app with native file/folder dialogs
• DaVinci Resolve plugin — search, import with clip color, add frame markers
• ASC MHL v2 hash manifests — mhl.py create / verify CLI emits real urn:ASC:MHL:v2.0 with xxh3 / md5 / sha1 / sha256 / c4, directory + structure root hashes, chained ascmhl_chain.xml. Interop-verified with ASC reference impl 1.2 — drop-in for Silverstack / MediaVerify / Hedge / YoYotta workflows
• Multi-destination offload — offload.py --src <SD> --dst <A> --dst <B> does chunked parallel copy + per-file hash verify + 3× retry on mismatch + atomic rename + sidecar-aware (XAVC / ARRI / RED / iPhone Live Photo). Resumable JSON state file — kill mid-copy and pending files pick up exactly where they stopped. Emits per-dst MHL v2
• Camera report CSV — camera_report.py writes 20-col DIT-spec CSV (Reel / TC / Camera / Lens / ISO / Shutter / Aperture / WB / FPS / Codec / ...) for Resolve's File → Import Metadata from CSV. Day-summary footer aggregates clip count + runtime by camera / by card
• DIT Offload UI (/dit) — browser control panel for card→backup offload: preview the destination layout, run with live per-file progress streaming, multi-destination + xxh3 verify + ASC MHL v2. Never deletes the source card
• Offload organize policy — offload.py --organize "{date}/{camera}/{reel}" files footage into a date/camera/reel tree (tokens: {date}/{camera}/{reel}/{stem}/{ext}, fs-safe, path-traversal guarded) — or leave it empty to mirror the source structure
• Card-watcher — offload.py --watch auto-offloads on card insert (detects DCIM / media volumes), with re-insert / mount-flicker guard so a wobbling card never re-copies
• 360 reprojection — dual-fisheye .insv / .360 clips are reprojected to equirectangular before vision tagging (FFmpeg v360), so on-frame text and events the raw fisheye hides become searchable
• Vision failure tolerance — ingest.py --max-failures N / --skip-failed tolerate flaky per-frame vision on long unattended runs; failed frames are left empty for a later --vision-only resume (a whole-Ollama outage still halts fast)

DaVinci Resolve integration

arkiv isn't just another asset manager sitting beside your NLE — it runs inside it:

• Resolve plugin (resolve_plugin/): search your arkiv library from within Resolve, import results with clip color onto the timeline, and drop frame markers — without leaving the NLE.
• Ratings carry through: GOOD / NG / Review become Resolve clip colors.
• Metadata CSV: /api/export/metadata-csv emits exactly the columns Resolve's File → Import Metadata from CSV expects (Camera/Lens/ISO/Shutter/Aperture/GPS/CreateDate); the plugin prompts for it after import.
• Timeline interchange: EDL (drop-frame / non-drop timecode) and FCPXML 1.8, compatible with both FCPX and DaVinci.

On macOS, Resolve needs the official python.org Python 3.10 Framework (see Prerequisites below).

API / MCP

Everything arkiv does is available over a REST API (/api/*, scope-based Bearer tokens) and a read-only MCP server — the Web UI is just one client. Script it, wire it into an automation, or let Claude/OpenClaw query your library.

→ API auth, token scopes, and the library Chat (RAG) endpoint: docs/api.md

MCP over the LAN

The default MCP server speaks stdio, which needs a local process and local access to the database — neither of which crosses a network. mcp_http_server.py serves the same read-only tools over HTTP/SSE so a client on another machine can query the library:

ARKIV_MCP_BIND=0.0.0.0 \
ARKIV_MCP_ALLOWED_HOSTS=192.168.1.50:8502 \
python mcp_http_server.py            # or: the arkiv-mcp service in docker compose

With docker compose, the ports are published on 127.0.0.1 by default. Start it with ARKIV_BIND_HOST=0.0.0.0 docker compose up -d to make them reachable from other machines.

Point your MCP client at http://<host>:8502/sse with an Authorization: Bearer <token> header. Tokens are the same ones the REST API uses, so revoking one revokes it everywhere.

🔴 ARKIV_MCP_ALLOWED_HOSTS is not optional for LAN use. The MCP SDK ships DNS rebinding protection with a loopback-only allow-list, so a request arriving as Host: 192.168.1.50:8502 is refused with 421 Misdirected Request before arkiv sees it. List the address your clients dial. Values are added to the loopback defaults, so localhost keeps working; * switches the host check off entirely.

The bind address defaults to 127.0.0.1 — publishing an MCP endpoint to the network is a decision, not a default.

Quick Start

Download the app (macOS Apple Silicon · Windows x64)

The quickest way to run arkiv without a Python setup. The installer bundles the Python backend and ML libraries (torch, whisper, chromadb, …), so you skip the venv/pip steps below. You still need FFmpeg and Ollama for frame extraction, embeddings, and vision.

macOS (Apple Silicon)

brew install ffmpeg ollama
ollama pull bge-m3 && ollama pull qwen2.5vl:7b && ollama pull qwen2.5:14b

Download arkiv_<version>_aarch64.dmg from the latest release, open it, and drag arkiv to Applications. On first launch the build is unsigned, so macOS Gatekeeper blocks a double-click — right-click → Open once (or run xattr -dr com.apple.quarantine /Applications/arkiv.app); afterwards it opens normally. Full walkthrough: docs/quickstart-mac.md.

Windows (x64)

winget install Gyan.FFmpeg Ollama.Ollama
ollama pull bge-m3; ollama pull qwen2.5vl:7b; ollama pull qwen2.5:14b

Download arkiv_<version>_x64-setup.exe from the latest release and run it — it installs per-user, no admin prompt. The build is unsigned, so SmartScreen shows "Windows protected your PC" once: click More info → Run anyway. An .msi is also published for admin/GPO deployment. Full walkthrough: docs/quickstart-windows.md.

On a fresh, empty library both builds load a pre-indexed sample of four CC-BY Blender clips, so the grid is browsable and searchable the moment it opens — no pipeline run, no models needed for that first look.

Intel Macs and Linux have no prebuilt app — run from source instead (below). The macOS bundle ships an aarch64 Python + mlx-whisper; the Windows bundle ships a CPU-only faster-whisper stack.

Everything below installs and runs arkiv from source — for development, or on Linux / Windows.

Prerequisites

DaVinci Resolve Plugin extra (macOS): Resolve requires the official Python 3.10 Framework installer (.pkg) from python.org — Homebrew Python is not recognized. Install path: /Library/Frameworks/Python.framework/Versions/3.10/. Restart Resolve after install; Py3 should appear in Console and scripts load via Workspace > Scripts.

Install — macOS (brew + pip)

brew install python ffmpeg ollama
git clone https://github.com/vulture-s/arkiv.git
cd arkiv
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install mlx-whisper          # Apple Silicon (Metal GPU)
ollama pull bge-m3 && ollama pull qwen2.5vl:7b && ollama pull qwen2.5:14b
python health.py

Install — Linux (pip)

sudo apt install python3 python3-venv ffmpeg
git clone https://github.com/vulture-s/arkiv.git
cd arkiv
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pip install faster-whisper torch  # NVIDIA CUDA GPU
# pip install faster-whisper      # CPU fallback
ollama pull bge-m3 && ollama pull qwen2.5vl:7b && ollama pull qwen2.5:14b
python health.py

Install — Windows (pip, PowerShell)

# Install Python 3.9+, FFmpeg, and Ollama manually first, then:
git clone https://github.com/vulture-s/arkiv.git
cd arkiv
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
pip install faster-whisper torch  # NVIDIA CUDA GPU
# pip install faster-whisper      # CPU fallback
ollama pull bge-m3; ollama pull qwen2.5vl:7b; ollama pull qwen2.5:14b
$env:PYTHONUTF8=1; python health.py

Install — Docker (all platforms)

git clone https://github.com/vulture-s/arkiv.git
cd arkiv

# Point ARKIV_MEDIA_DIR at your footage — a NAS share, an external drive,
# anything. It is mounted at /media inside the container, which is the path
# you give arkiv when you add a library. Defaults to ./media.
ARKIV_MEDIA_DIR=/path/to/your/footage docker compose up -d
# Open http://localhost:8501

Models are pulled automatically inside the Ollama container on first run (may take a few minutes).

Uploads through the web UI land in ./media-in on the host. Both that and your library are bind-mounted, so nothing you add survives only inside the container.

Split-host: arkiv here, Ollama on the GPU box

The default file runs arkiv and Ollama together. If the machine with the GPU is a different one on your LAN, use the sibling file instead — Ollama on that machine needs OLLAMA_HOST=0.0.0.0 and the models pulled first:

ARKIV_OLLAMA_URL=http://192.168.1.50:11434 \
ARKIV_MEDIA_DIR=/Volumes/footage \
docker compose -f docker-compose.remote-ollama.yml up -d

Full notes, including why this is a separate file rather than an override, are at the top of docker-compose.remote-ollama.yml.

Upgrading from an old version (v0.3.0 → v0.3.1 storage layout migration)

v0.3.1 changed the default storage layout (artifacts now live in BASE_DIR/.arkiv/). Only needed when upgrading from before that:

cd ~/.arkiv && git pull && python ingest.py --migrate-storage

Full SOP (backup, rollback, per-project layout): docs/pipeline.md · CHANGELOG

Option A: Web UI — browse, search, rate, and tag in the browser

# macOS / Linux
uvicorn server:app --host 0.0.0.0 --port 8501

# Windows (PowerShell) — UTF-8 required for CJK search
$env:PYTHONUTF8=1; uvicorn server:app --host 0.0.0.0 --port 8501

# Open http://localhost:8501 → click + to ingest media

Option B: CLI only — ingest and search without opening a browser

Both options use the same database. You can mix and match — ingest via CLI, then browse in Web UI, or vice versa.

Note: Do not run CLI and Web UI ingest at the same time. SQLite does not support concurrent writes — run one at a time.

# Step 1 — Ingest your media
python ingest.py --dir /path/to/media

# Step 2 — Build search index
python embed.py

# Step 3 — Search
python embed.py --search "interview outdoor"

Advanced CLI options

# Ingest options
python ingest.py --dir ./media --limit 10        # process first 10 files only
python ingest.py --dir ./media --skip-vision     # skip AI frame descriptions
python ingest.py --dir ./media --refresh         # re-process already-indexed files (re-extracts frames)
python ingest.py --dir ./media --skip-failed     # tolerate flaky per-frame vision (overnight runs)
python ingest.py --dir ./media --max-failures 20 # halt vision only after 20 cumulative frame failures
python ingest.py --vision-only --dir ./media     # resume: only re-run vision on frames left empty

# Index options
python embed.py --rebuild                    # drop and rebuild from scratch

# DIT offload (card → backup; never deletes source)
python offload.py --src /Volumes/CARD --dst /Volumes/Backup1 --dst /Volumes/Backup2
python offload.py --src /Volumes/CARD --dst /Volumes/Backup --organize "{date}/{camera}/{reel}"
python offload.py --watch --dst /Volumes/Backup # auto-offload on card insert

# Auto-watch a folder for new media (ingest)
python watch.py /path/to/footage
python watch.py ~/Movies/rushes --poll-interval 10

# API search (requires server running)
# Linux / macOS / Git Bash
curl "http://localhost:8501/api/media?q=keyword&limit=5"
# Windows PowerShell
Invoke-RestMethod "http://localhost:8501/api/media?q=keyword&limit=5"

Configuration

All environment variables (`.env`) — defaults just work; open this to tune

Copy .env.example to .env and customize:

Embedding model is locked to your index. The vector store is built with one embedding model (bge-m3, 1024-dim). Changing ARKIV_EMBED_MODEL after you have indexed media makes new query vectors incompatible with stored ones — search results degrade silently. To switch models, re-index from scratch.

Hardware floor for chat: qwen2.5:14b needs ~9 GB and runs alongside the embedding model. Plan for ~12–16 GB free RAM/VRAM on the Ollama host. On tighter machines, set ARKIV_CHAT_MODEL=qwen2.5:7b (~4.7 GB) for a lighter default.

Tech Stack

FAQ

Q: Which Whisper backend should I use?

• macOS with Apple Silicon: mlx-whisper (fastest, uses Metal GPU)
• NVIDIA GPU: faster-whisper + torch (CUDA acceleration)
• CPU only: faster-whisper (slower but works everywhere)

Q: Do I need Ollama running? Yes, for semantic search (embedding) and optional frame descriptions. Run ollama serve before starting arkiv.

Q: How do I add media? Use the + button in the Media Pool sidebar, or run python ingest.py --dir /path/to/media from CLI.

Q: Can I use this without Docker? Yes — the native Python install is the primary workflow. Docker is optional for deployment.

Q: What file formats are supported? Video: .mp4, .mov, .mkv, .avi, .webm, .m4v, .mts, .mxf (Sony FX6/FX9/Venice XAVC) 360: .insv (Insta360), .360 (GoPro Max) — dual-fisheye is reprojected to equirectangular before vision tagging (single-lens 360 footage is indexed as-is) Audio: .wav, .mp3, .m4a, .aac, .flac, .ogg Camera metadata (make/model/lens/timecode) is read from embedded EXIF and Sony XAVC NRT sidecar XML — so FX30/FX-series footage keeps its identity.

Smoke Test

Run the built-in smoke test to verify your setup:

# PC (Windows/macOS)
bash smoke-test.sh --platform pc

# Docker
docker exec arkiv-arkiv-1 bash smoke-test.sh --platform docker

The test has two phases: Health Check (environment) and API Smoke Test (server endpoints).

What SKIP means

SKIP items are optional dependencies — they do not affect functionality. A passing result is 0 FAIL, regardless of SKIP count.

Latest Results

For developers

ARCHITECTURE.md (architecture overview) · docs/api.md (API + Chat) · docs/pipeline.md (full pipeline) · CONTRIBUTING.md · CHANGELOG.md

License

PolyForm Perimeter License 1.0.1 plus Additional Terms — see LICENSE.

Using arkiv is free for any purpose, commercial work included: paid client jobs, studio use, funded productions. Videos, timelines and exports you produce with it are yours, with no restriction from the license. Two things are not permitted. Modifying arkiv to exceed the free-tier allowance or to switch on Pro functionality — this applies to your own use too (Additional Terms 1–2; installations in use before 1.1.0 keep their exemption). And providing others with a product that competes with arkiv — forking it into a rival asset manager, wrapping it as a hosted indexing service sold to third parties, or reimplementing its functionality as a substitute product, including free of charge.

The line is what your customer is buying: a deliverable you produced with arkiv is ordinary tool use; arkiv's functionality itself, sold as a product or service, competes.

Pro add-on

The free core covers up to 3 projects. The optional Pro add-on — a separate closed-source component — unlocks unlimited projects and cross-project aggregation (search and collections spanning projects) for NT$3,000, one time, perpetual. No subscription, no activation server, no phone-home. Terms: docs/pro-addon-license.md.

On sale since 2026-10-03 through the Waffle House store — see the product page.

Public-Interest Program

arkiv is free to use for any purpose, so public-interest work needs no permission from us to use the core. What the program grants is the Pro add-on, free and perpetual, for work that serves the public interest:

• Public-issue documentaries
• Nonprofit / public-good visual work
• Local memory, oral history, and archival preservation
• Public education and public media

The knowledge layer over footage shouldn't be something only big productions can afford.

How to apply: open a GitHub Issue with [public-interest] in the title, or DM @vulture.s on Instagram, with a short description of your project. Reviewed case by case — no automatic eligibility checklist. See PUBLIC-INTEREST.md for examples, a sample request, and the case-by-case discretion statement.

Contact & Follow

• Dev log and demos: Threads / Instagram @vulture.s
• Bug reports and feature requests: GitHub Issues
• Commercial partnership / deployment help: DM on IG, or open an Issue with [biz] in the title