vid2text

CLI tool for extracting searchable transcriptions from YouTube videos, local files, and M3U8 streams using local Whisper models.

Features

• Multi-source: YouTube, local videos (.mp4, .avi, .mov, .mkv, .m4v), M3U8 streams
• Local transcription: MLX Whisper (macOS) or OpenAI Whisper (cross-platform)
• SQLite storage: Searchable database with Datasette web interface
• Batch processing: YAML configuration for multiple videos

Installation

Prerequisites: Python 3.9+, FFmpeg

Install FFmpeg

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

Install vid2text

pipx install vid2text
pipx upgrade vid2text

Usage

Single Video

vid2text youtube "https://youtu.be/VIDEO_ID"
vid2text local "/path/to/video.mp4"
vid2text local "/path/to/folder"        # Process all videos in folder (recursive)
vid2text m3u8 "https://example.com/stream.m3u8"

# With options
vid2text --model small.en --verbose youtube "https://youtu.be/..."
vid2text --dry-run local video.mp4  # Preview only

Batch Processing

Create config.yaml:

videos:
  youtube:
    - url: "https://youtu.be/dQw4w9WgXcQ"
    - url: "https://youtu.be/jNQXAC9IVRw"
      title: "Custom Title"  # Optional
  local:
    - path: "/path/to/video.mp4"
    - path: "/path/to/folder/"  # Process all videos in folder (recursive)
      title: "Folder Videos"
  m3u8:
    - url: "https://example.com/video.m3u8"
      title: "Live Stream"
      order: 1

settings:  # Optional
  whisper_model: "small.en"  # Override default model
  log_level: "DEBUG"

Process:

vid2text process config.yaml
vid2text --dry-run process config.yaml  # Preview

Notes:

• local entries can be a file or a folder; folders are scanned recursively for supported video types.
• If a title is provided for a folder with multiple files, each item is stored as Title - filename.

Database Operations

vid2text stats                           # Show video count
vid2text --db-path custom.db stats       # Custom database
vid2text view                            # Launch web interface (requires datasette)
vid2text view --port 8080                # Custom port

Configuration

Environment Variables

Variable	Default	Description
VIDEO_DB_PATH	~/.vid2text/knowledge.db	Database file location
LOG_LEVEL	INFO	Logging verbosity
TRANSCRIPTION_ENGINE	Auto-detected	mlx-whisper or openai-whisper
WHISPER_MODEL	Auto-selected	Model name (see below)

Whisper Models

macOS (Apple Silicon) - MLX Whisper:

• mlx-community/whisper-medium.en-mlx (default) - Good balance
• mlx-community/whisper-large-v3-mlx - Best accuracy, slower
• mlx-community/whisper-small.en-mlx - Faster, less accurate

Cross-platform - OpenAI Whisper:

• base.en (default) - Good balance
• tiny.en - Fastest
• small.en - Better accuracy
• medium.en - High accuracy
• large - Best accuracy

CLI Options

• --db-path PATH - Custom database location
• --model MODEL - Override Whisper model
• --verbose/-v - Increase logging (use -vv for debug)
• --dry-run - Preview operations without processing

Examples

# Custom model and database
WHISPER_MODEL=small.en vid2text --db-path ./videos.db youtube "https://youtu.be/..."

# Debug processing issues
vid2text -vv local problematic_video.mp4

# Batch process with custom settings
VIDEO_DB_PATH=./project.db LOG_LEVEL=DEBUG vid2text process videos.yaml

# Quick stats check
vid2text stats | grep "Total videos"

Troubleshooting

FFmpeg not found:

# Verify installation
ffmpeg -version
# Add to PATH if needed

Out of memory during transcription:

• Try smaller Whisper model: --model tiny.en
• Close other applications
• Use MLX Whisper on Apple Silicon for better memory efficiency

Database locked error:

• Close any open Datasette instances
• Check if another vid2text process is running

Commands Reference

• vid2text youtube <url> - Process YouTube video
• vid2text local <path> - Process local video/folder
• vid2text m3u8 <url> - Process M3U8 stream
• vid2text process <config.yaml> - Batch process from YAML
• vid2text stats - Show database statistics
• vid2text view [--port PORT] - Launch Datasette web interface

Development

git clone https://github.com/yourusername/vid2text.git
cd vid2text
python -m venv venv && source venv/bin/activate
pip install -e ".[test]"

# Run CLI
vid2text --help

# Run tests
pytest

Release

Release is automated by GitHub Actions. Creating a GitHub Release triggers tests and publishes to PyPI.

Steps:

1. Bump versions in pyproject.toml and vid2text/cli.py.
2. Push the version change to main.
3. Create a GitHub Release (tag like v0.1.1).
4. The Publish to PyPI workflow runs tests and publishes if green.