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 qwen3-vl:8b && 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 qwen3-vl:8b && 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 qwen3-vl:8b; 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 docker compose up -d

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

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

Index options

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

Configuration

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.

API Authentication

All /api/* endpoints require a Bearer token with the correct scope. Scope-based tokens let you split a fleet by machine role: read-only review stations can use videos_read or media_read, ingest machines can use ingest_write, and admin machines can manage tokens.

First-time bootstrap:

export ARKIV_ADMIN_BOOTSTRAP_TOKEN=$(openssl rand -base64 32)
python server.py

On first startup, the server seeds a single admin token from that env var. Use it once to create per-machine tokens, then unset it and revoke the bootstrap token.

Create and manage tokens directly with the CLI:

python arkiv_token.py create --name "PC-dev" --scopes videos_read,videos_write --ip-allowlist 127.0.0.1/32,100.64.0.0/10 --expires-in 90
python arkiv_token.py list
python arkiv_token.py show <token-id>
python arkiv_token.py revoke <token-id>

Use the token in requests:

curl -H "Authorization: Bearer <token>" http://localhost:8501/api/media

Available scopes: videos_read, videos_write, media_read, collections_read, collections_write, projects_read, projects_write, ingest_write, chat_read, chat_write, admin

Chat API — RAG over your video library

Ask natural-language questions about your archive. The classifier routes each prompt to one of five handlers:

Conversation history (last 10 messages) is threaded into each follow-up, so refinement acts on what the previous turn returned.

Model requirement: chat uses ARKIV_CHAT_MODEL (default qwen2.5:14b) for both intent classification and answers — a single ollama pull qwen2.5:14b covers it. Only set ARKIV_INTENT_MODEL to a smaller model (e.g. qwen2.5:7b-instruct) if that model is actually installed on the Ollama host. If the model is missing, /api/chat returns a clear "run ollama pull …" message instead of a 500.

Prerequisite — ingest + index first: chat queries your indexed library, not a standalone chatbot. Ingest media (Step 1) and build the index with python embed.py (Step 2) before chatting. compilation / refinement / similarity need the vector index; analytics needs ingested media only; general is the only intent that works on an empty library. On an empty/unindexed library chat does not error — it just returns "0 results".

```bash

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 360: .insv (Insta360), .360 (GoPro Max) — indexed as raw fisheye 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.