Video Material DB (Video Material Semantic Database)

A local-first knowledge base for short-form video research and creation. It unifies videos, subtitles, and AI-structured analysis into PostgreSQL, and provides natural-language retrieval through a Web interface, REST API, and MCP tools. Media material and analysis data are stored by default in the user's own runtime environment.

Main Features

• Import media from local files, folders, or public video links

• Automatically scrape video lists of creators from platforms such as Douyin, TikTok, YouTube, and Bilibili

• Automatically complete to video preprocessing, speech transcription, keyframe extraction, and visual analysis through:

• Extract characters, scenes, shots, dialogue, story structure, punchlines (malloc), and adaptation suggestions

• Use pgvector to build a semantic index and search videos, dialogue, and narrative elements in natural language

• Manage media and background tasks through FastAPI Web interface

• Front MCP into AI tools such as Codex

• Support deduplication, asynchronous processing, failure retry, and batch export

Use Cases

• Short-video writers search for reference on plot, dialogue , jokes, plot twists, and camera shots

• Content teams build a searchable video case library and creative knowledge base

• Analyze popular creators' content structure, narrative pacing, and visual style

• Look for reusable creative patterns in large volumes of reference videos

• Provide AI assistants with structured, traceable video research material

Tech Composition

• Python 3.11+

• FastAPI

• PostgreSQL + pgvector

• MCP Server

• ffmpeg / ffprobe

• Qwen-compatible interfaces (ASR, visual analysis, and vector embeddings)

Quick Start

Full installation instructions are shown in INSTALL.md. media are stored by default in local ./data directory under the project.

python3 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env

Once the database is running, start the Web service and background analysis tasks:

.venv/bin/video-db-api
.venv/bin/video-db-worker

Open http://127.0.0.1:8000/ in your browser.

MCP Integration

codex mcp add video-material-db -- <仓库绝对路径>/.venv/bin/video-db-mcp

The available tools include add_video_url, add_locale_video, search_videos, search_dialogue, search_jokes, search_stroy_structure, and get_video_detail.

Data and Security

The public repository contains only generic application source code. .env, API keys, video files, database content, backups, machine-local paths, and personal data remain out of version control.