Build & Setup Guide

Complete guide for building, installing, and setting up the Video-to-Knowledge Pipeline.

Quick Start (One Command)

Option 1: Interactive Setup (Recommended)

# Clone or navigate to project directory
cd video_analysis_pipeline

# Run interactive build
python build.py

This will:

✅ Check system requirements
📦 Install dependencies (with virtual environment)
📥 Download Whisper models
🔑 Configure API keys
🚀 Create launcher script

Option 2: Makefile

# Using make
make install

# Or specific targets
make check      # Check requirements
make quick      # Quick setup
make models     # Download models

Option 3: One-line Installer

# Using curl (when published)
curl -sSL https://your-domain.com/install.sh | bash

# Or local install script
./install.sh

Manual Setup

Step 1: Prerequisites

Required:

Python 3.9 or higher
FFmpeg

macOS:

brew install python ffmpeg

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv ffmpeg

Windows:

Install Python from python.org
Install FFmpeg and add to PATH

Step 2: Install Dependencies

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements-local.txt

# Install package in development mode
pip install -e .

Step 3: Download Whisper Models

# Interactive model manager
python -m src.model_manager

# Or download specific model
python -m src.pipeline models --download small

Step 4: Configure API Keys

Option A: Environment Variables

# Add to ~/.bashrc or ~/.zshrc
export KIMI_API_KEY="your-kimi-key"
export ANTHROPIC_API_KEY="your-claude-key"  # Optional alternative
export OPENAI_API_KEY="your-openai-key"      # Optional for API transcription

Option B: Interactive Setup

python build.py
# Follow prompts to enter API keys

Build Commands

Python Build Script

# Full interactive setup
python build.py

# Quick setup with defaults
python build.py --quick

# Check system only
python build.py --check

# Clean build artifacts
python build.py --clean

# Download specific models
python build.py --models small medium

Makefile Targets

Command	Description
`make install`	Full interactive installation
`make quick`	Quick setup with defaults
`make check`	Check system requirements
`make models`	Download Whisper models
`make clean`	Clean build artifacts
`make run`	Run interactive mode
`make test`	Run tests
`make lint`	Run linters

Configuration

Configuration File

Location: ~/.config/video-pipeline/config.json

Generated automatically during setup. Edit manually or use:

# View current config
vp config

# Or interactive setup
vp quickstart

Environment Variables

Variable	Purpose	Required
`KIMI_API_KEY`	Kimi Vision API	Yes (or Claude)
`MOONSHOT_API_KEY`	Alternative Kimi key	Optional
`ANTHROPIC_API_KEY`	Claude Vision API	Alternative
`OPENAI_API_KEY`	OpenAI Whisper/LLM	Optional
`SERPER_API_KEY`	Web search	Optional

Whisper Model Selection

Models are downloaded to: ~/.cache/whisper/

Model	Size	RAM	Speed	Command
tiny	39M	0.5GB	32x	`vp models --download tiny`
base	74M	1GB	16x	`vp models --download base`
small	244M	2GB	6x	`vp models --download small`
medium	769M	5GB	2x	`vp models --download medium`
large-v3	1550M	10GB	1x	`vp models --download large-v3`

Post-Installation

Verify Installation

# Check all components
vp --help

# Check models
vp models

# Run interactive mode
vp

First Video Processing

# Quick process
vp process "https://youtube.com/watch?v=..."

# With specific model
vp process "video.mp4" --whisper-model small

# Generate deck
vp process "video.mp4" --deck

# Interactive mode (guided)
vp

Troubleshooting

FFmpeg Not Found

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Verify
ffmpeg -version

CUDA/GPU Not Available

# Install PyTorch with CUDA (optional)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# Or use CPU (slower but works)
# Whisper will automatically use CPU if CUDA unavailable

Model Download Fails

# Manual download
python -c "import whisper; whisper.load_model('small')"

# Check cache
ls -la ~/.cache/whisper/

API Key Issues

# Check if set
echo $KIMI_API_KEY

# Set temporarily
export KIMI_API_KEY="your-key"
vp process "video.mp4"

# Set permanently (add to ~/.bashrc)
echo 'export KIMI_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

Development Setup

# Clone repository
git clone <repository-url>
cd video_analysis_pipeline

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dev dependencies
pip install -r requirements-local.txt
pip install -e ".[dev]"

# Run checks
make check
make test
make lint

# Start development
make dev

Uninstallation

# Clean build artifacts
make clean

# Remove virtual environment
rm -rf .venv

# Remove config and cache
rm -rf ~/.config/video-pipeline
rm -rf ~/.cache/whisper

# Remove installed package
pip uninstall video-to-knowledge-pipeline

System Requirements

Component	Minimum	Recommended
Python	3.9	3.11+
RAM	4GB	8GB+
Disk	5GB	20GB+
CPU	2 cores	4+ cores
GPU	Optional	CUDA-enabled
OS	Linux/macOS/Windows	Linux/macOS

Getting Help

# General help
vp --help

# Command help
vp process --help
vp models --help

# Interactive help
vp
# Then select "Help" option

For more information, see README.md and PROJECT_SUMMARY.md

Quick Start (One Command)​

Option 1: Interactive Setup (Recommended)​

Option 2: Makefile​

Option 3: One-line Installer​

Manual Setup​

Step 1: Prerequisites​

Step 2: Install Dependencies​

Step 3: Download Whisper Models​

Step 4: Configure API Keys​

Build Commands​

Python Build Script​

Makefile Targets​

Configuration​

Configuration File​

Environment Variables​

Whisper Model Selection​

Post-Installation​

Verify Installation​

First Video Processing​

Troubleshooting​

FFmpeg Not Found​

CUDA/GPU Not Available​

Model Download Fails​

API Key Issues​

Development Setup​

Uninstallation​

System Requirements​

Getting Help​