Back to VideoVox

README

VideoVox

[](https://github.com/jonathanleahy/VideoVox/actions/workflows/quality-checks.yml) [](https://github.com/jonathanleahy/VideoVox/actions/workflows/e2e-tests.yml) [](https://codecov.io/gh/jonathanleahy/VideoVox) [](https://goreportcard.com/report/github.com/jonathanleahy/VideoVox) [](https://opensource.org/licenses/MIT) [](https://github.com/jonathanleahy/VideoVox)

A comprehensive suite of Go-based tools for video processing, subtitle manipulation, and audio generation. This project provides powerful utilities for content creators, educators, and video editors to enhance their video content with automated editing, subtitle processing, and text-to-speech capabilities.

Project Status

  • ✅ Backend: 80%+ test coverage with comprehensive quality checks
  • ✅ Frontend: Next.js 15 with TypeScript, E2E + Component tests
  • ✅ CI/CD: GitHub Actions with 7 automated quality jobs
  • ✅ Architecture: Hexagonal architecture with event sourcing
  • ✅ Infrastructure: 12-container Docker setup with monitoring

Quick Start with VideoVox Orchestrator

The VideoVox orchestrator provides a unified interface to run all three tools with a single command.

What the Orchestrator Does

When you run videovox process, it automatically:

  • Generates captions from your video (if not already present)
  • Creates AI voice-over from the captions using your chosen TTS provider
  • Removes silence and freeze frames to create a polished final video

    • All controlled by your .env settings!

    bash
    # Copy and configure your settings (creates hidden .env file)
cp .env.template .env
# Edit .env with your API keys and preferences
nano .env  # or use your preferred editor

# Run the full pipeline
go run videovox.go process -i input.mp4

# Run specific tools
go run videovox.go caption -i input.mp4
go run videovox.go voice -i input.mp4
go run videovox.go freeze -i input.mp4

# Run custom pipeline
go run videovox.go pipeline -i input.mp4 -w caption-voice

# Process a specific segment (2 minutes starting at 1:30)
go run videovox.go process -i input.mp4 --start-time 00:01:30 --length 00:02:00

# Process 30 seconds starting at 10 seconds
go run videovox.go caption -i input.mp4 --start-time 10 --length 30

# Multi-language support with translation
go run videovox.go process -i portuguese_video.mp4 -lang pt -translate  # Portuguese to English
go run videovox.go process -i spanish_video.mp4 -lang es -translate     # Spanish to English
go run videovox.go process -i french_video.mp4 -lang fr -translate      # French to English

    Projects

    1. freeze-cut

    A sophisticated video editing tool that automatically removes or speeds up silent and frozen segments in video recordings. Perfect for editing webinars, meetings, lectures, and screen recordings.

    Key Features:

    • Automatic silence and freeze detection
    • Multiple processing modes (delete, fade, blend, speedup)
    • Smart subtitle timing adjustment
    • Visual indicators for edits
    • Parallel processing for performance
    View freeze-cut documentation

    2. voice-over

    Extracts subtitles from MP4 files, enhances them using AI, generates natural speech audio, and creates a final video with multiple audio and subtitle tracks.

    Key Features:

    • Multiple TTS providers (OpenAI, Google, ElevenLabs, Gemini)
    • Gemini 2.5 Pro Preview and Flash Preview models for high-quality TTS
    • AI-powered subtitle enhancement with ChatGPT
    • Intelligent subtitle combining and splitting
    • Multi-track output with original and processed content
    • Batch processing for large subtitle files
    View voice-over documentation

    3. caption-gen

    A modular video processing application that handles audio extraction, subtitle generation, and format conversion with caching support.

    Key Features:

    • Audio extraction from video files
    • AI-powered subtitle generation
    • Multiple subtitle format support (SRT, VTT)
    • Video segmentation for long content
    • Intelligent caching system
    View caption-gen documentation

    Requirements

    • Go 1.19 or later
    • FFmpeg installed and available in PATH
    • API keys for relevant services (OpenAI, Google Cloud, ElevenLabs, Gemini)

    Installation

    Prerequisites

    • Go 1.19 or later installed
    • FFmpeg installed and in your PATH
    • At least one API key (OpenAI required for text processing)

    Step-by-Step Setup

  • Clone the repository:

    • bash
    git clone https://github.com/yourusername/VideoVox.git
cd VideoVox

  • Install dependencies:

    • bash
    # Install orchestrator dependencies
go mod tidy

# Install caption-gen dependencies (uses go.work for workspace)
cd caption-gen && go work sync && cd ..

# Install voice-over dependencies (if needed)
cd voice-over && go mod tidy && cd ..

# Install freeze-cut dependencies (if needed)
cd freeze-cut && go mod tidy && cd ..

  • Configure your environment:

    • bash
    # Copy template to create .env file (note: .env is a hidden file)
cp .env.template .env

# Edit .env with your API keys and settings
nano .env  # or vim .env or your preferred editor

# To view the hidden .env file later:
ls -la | grep .env

  • Build the tools (optional):

    • bash
    # Build orchestrator
go build -o videovox videovox.go

# Build individual tools
go build -o freeze-cut/freeze-cut freeze-cut/cmd/freeze-cut/main.go
go build -o voice-over/voice-over voice-over/main.go

    First Run Example

    Here's a complete example to get you started:

    bash
    # 1. Install all dependencies (one-time setup)
go mod tidy
cd caption-gen && go mod tidy && cd ..

# 2. Create and configure .env file
cp .env.template .env

# 3. Add your OpenAI API key (minimum requirement)
# On Linux/Mac:
echo "OPENAI_API_KEY=sk-your-actual-key-here" >> .env

# On Windows:
# Edit .env file and replace sk-your-openai-key-here with your actual key

# 4. Run the orchestrator
go run videovox.go process -i testing-testing.mp4

# 5. Check the output
ls ./processed/

    Quick Start for SaaS Development

    Production Mode (Optimized Build)

    Start the entire development environment with one command:

    bash
    # First time or if you have port conflicts
./scripts/clean-start.sh

# Or if no conflicts, use the regular start
./scripts/dev-all.sh

# View all service URLs and status
./scripts/dev-all.sh --status

# View logs
./scripts/dev-all.sh --logs

# Stop all services
./scripts/dev-all.sh --stop

    Note: Use clean-start.sh for first-time setup or if you get "port already allocated" errors. It will detect and stop conflicting Docker containers.

    Development Mode (Hot Reload)

    For active development with automatic code reloading:

    bash
    # Start with hot reload for backend and frontend
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# Or just start specific services in dev mode
docker compose -f docker-compose.yml -f docker-compose.dev.yml up frontend backend

# Stop development environment
Ctrl+C
docker compose down

    What you get:

    • Backend (Go + Air): Automatic rebuild and restart on .go file changes
    • Frontend (Next.js): Fast Refresh (HMR) for instant React updates
    • Volume Mounts: Code changes on host immediately reflected in containers
    • No Rebuilds: Save time by eliminating Docker rebuilds during development
    See DEVELOPMENT.md for complete hot reload documentation.

    See scripts/README.md for more development scripts.

    Quick Start for CLI Tools

    Using the Orchestrator (Recommended)

    Process a video through the full pipeline:

    bash
    # Uses settings from .env file
./videovox process -i presentation.mp4

# Or specify output
./videovox process -i presentation.mp4 -o final.mp4

# Process only a specific segment of the video
./videovox process -i lecture.mp4 --start-time 5m --length 2m

# Or use seconds
./videovox process -i lecture.mp4 --start-time 300 --length 120

    Using Individual Tools

    Edit a video to remove silence and freeze frames:

    bash
    cd freeze-cut
./freeze-cut -i input.mp4 -o output.mp4

    Add AI-enhanced audio to subtitled videos:

    bash
    cd voice-over
./voice-over -input video.mp4 -key-openai YOUR_KEY -provider openai

    Generate subtitles for a video:

    bash
    cd caption-gen
go run main_app/subtitler.go video.mp4

    VideoVox Orchestrator

    The orchestrator (videovox) provides a unified interface to all tools:

    Commands

    • process - Run the full pipeline (caption → voice → freeze)
    • caption - Generate captions only
    • voice - Add voice-over only
    • freeze - Remove silence/freeze frames only
    • pipeline - Run a custom pipeline

    Common Parameters

    • -i / --input - Input video file (required)
    • -o / --output - Output video file (optional)
    • --start-time - Start processing at this time (e.g., "5m", "300s", "1h30m")
    • --length - Process only this duration (e.g., "2m", "120s")
    • -v / --verbose - Show detailed processing information
    When using --start-time and --length, the output files will include descriptive suffixes like _start_300_len_120.mp4 to indicate the processed segment.

    Configuration

    All settings are managed through the .env file:

    bash
    # API Keys
OPENAI_API_KEY=your-key-here
GOOGLE_API_KEY=your-key-here
ELEVENLABS_API_KEY=your-key-here
GEMINI_API_KEY=your-key-here

# Workflow settings
ENABLE_CAPTION_GEN=true
ENABLE_VOICE_OVER=true
ENABLE_FREEZE_CUT=true

# Output settings
OUTPUT_DIR=./processed
KEEP_INTERMEDIATE_FILES=false

    See .env.template for all available options.

    License

    MIT License - See individual project directories for specific licensing information.

    Troubleshooting

    "no required module provides package"

    This error means dependencies aren't installed. Install all dependencies:

    bash
    # Install orchestrator dependencies
go mod tidy

# Install tool dependencies
cd caption-gen && go mod tidy && cd ..
cd voice-over && go mod tidy && cd ..
cd freeze-cut && go mod tidy && cd ..

# Then run again:
go run videovox.go process -i input.mp4

    Can't find .env file

    The .env file is hidden (starts with dot). To see it:

    bash
    ls -la | grep .env

    Missing API keys

    At minimum, you need an OpenAI API key for text processing:

    bash
    echo "OPENAI_API_KEY=your-key-here" > .env

    Contributing

    Contributions are welcome! Please feel free to submit a Pull Request.

    FAQ

    Do I need all the API keys?

    No. At minimum you need:
    • OpenAI API key - Required for text processing
    • Other keys are optional based on which TTS provider you want to use

    What video formats are supported?

    Any format that FFmpeg supports (MP4, AVI, MOV, MKV, etc.)

    How long does processing take?

    Depends on video length and enabled features:
    • Caption generation: ~1-2 minutes per 10 minutes of video
    • Voice-over: ~30 seconds per minute of speech
    • Freeze-cut: ~1-2 minutes per 10 minutes of video

    Can I process videos in other languages?

    Yes! The tools support multiple languages:
    • Caption-gen: Most languages (uses AI)
    • Voice-over: Depends on TTS provider (Gemini has best multilingual support)

    Where are the processed videos saved?

    By default in ./processed/ directory. You can change this in .env:

    shell
    OUTPUT_DIR=./my-custom-output

    Support

    For issues, questions, or suggestions, please open an issue in the GitHub repository.

    © 2026 Jonathan Leahy · v0.8.5