Open Video Guide Server

Open Video Guide converts a tutorial video into an illustrated guide.

The project is local-first and open source. It does not require a paid AI API. Users supply the computer, storage, network bandwidth, and electricity.

[!IMPORTANT] This repository contains the engineering foundation. It does not contain a working video conversion pipeline yet.

Product goal

The product must make each generated step easy to verify. Each step must include a timestamp, visual evidence, confidence data, and a review state.

The first release will process user-owned video files. It will support narrated and silent screen recordings. It will export Markdown, HTML, and structured JSON.

Product difference

Most products extract a transcript and make a summary. Open Video Guide will connect each instruction to evidence from the source video.

The product will:

• Keep all processing on the local computer after model download.
• Mark uncertain instructions for review.
• Keep source timestamps with each step.
• Select useful screenshots for each instruction.
• Let the user correct the result before export.
• Use replaceable model and platform adapters.

Planned local pipeline

Video file
  |
  +-- FFmpeg: media inspection and extraction
  +-- whisper.cpp: narrated speech and timestamps
  +-- PySceneDetect: scene and motion candidates
  +-- PaddleOCR: text visible in frames
  +-- Qwen3-VL through MLX-VLM: visual step analysis
  |
Evidence merge and verification
  |
Editable guide
  |
Markdown, HTML, JSON, and screenshots

The architecture also permits other runtimes. For example, Linux systems can use faster-whisper and a CUDA model server.

Integration plan

One Model Context Protocol (MCP) server will expose the product functions. Transport adapters will support these clients:

• ChatGPT and Codex plugins
• Claude and other MCP clients
• Odysseus local workspaces
• Command-line and local web clients

Odysseus is the correct name of the PewDiePie project. It is a self-hosted AI workspace that can connect to MCP servers.

See docs/INTEGRATIONS.md for the verified plan.

Repository map

Current commands

Use Python 3.11 or a later compatible version.

python -m pip install -e ".[dev]"
ovg validate examples/example-guide.json
pytest
python scripts/check_ste.py

The validate command checks a guide against the public JSON schema. Video processing commands will arrive in a later milestone.

Development status

The project is in phase 0. The repository now defines scope, contracts, quality gates, and contribution rules.

See these documents:

• Product requirements
• System architecture
• AI system plan
• MCP tool contract
• Development workflow
• Quality plan
• Roadmap

Writing standard

Project technical text must obey ASD-STE100 Simplified Technical English, Issue 9. The project uses an approved terminology list for software terms.

The automated checker finds only some rule violations. A trained reviewer must do the final language review.

Legal text and exact source text are not changed. See docs/STE_STYLE_GUIDE.md.

License

The project source uses the Apache License 2.0. Model files and third-party programs keep their own licenses.

See LICENSE and docs/MODEL_LICENSE_POLICY.md.