Arkiv媒体资产管理器

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.

Windows (PowerShell) — UTF-8 required for CJK search

$env:PYTHONUTF8=1; uvicorn server:app --host 0.0.0.0 --port 8501

API search (requires server running)

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)

```bash 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)

```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)

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

Step 2 — Build search index

python embed.py

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

Quick Start

Screenshots

<details> <summary>System architecture & data flow (for contributors / fork authors)</summary>

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

```bash

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.

```bash

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

Configuration

<details> <summary>All environment variables (.env) — defaults just work; open this to tune</summary>

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.

</details>

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

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

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.