vidscribe 0.1.8

CLI tool for automatic video summarization using Whisper and LLMs

Video Summarizer

A CLI tool for automatic video summarization using local Whisper transcription and LLM-based summarization.

Quick Start

# Install
pip install vidscribe

# Create configuration file
vidscribe getenv

# Edit .env and set your API key (optional for transcription only)
# OPENAI_API_KEY=your-key-here

# Summarize a video
vidscribe summarize video.mp4
vidscribe summarize https://www.bilibili.com/video/xxx
vidscribe summarize https://www.youtube.com/watch?v=xxx

Note: Transcription works without an API key. Summarization requires OPENAI_API_KEY.

Features

• Flexible Transcription: Native mode (no Docker) or Docker mode
• LLM Summarization: Configurable OpenAI-compatible API
• Video Platform Support: YouTube, Bilibili, and 1000+ sites via yt-dlp
• Rich CLI: Beautiful terminal output

Installation

pip install vidscribe

Prerequisites

• Python: 3.10, 3.11, or 3.12 (3.13+ not supported)

FFmpeg is automatically bundled with the package—no manual installation required.

GPU Support (Optional)

GPU acceleration is configured via .env file:

• Native backend: Set NATIVE_DEVICE=cuda in .env
• Speaches backend: Set SPEACHES_USE_GPU=true in .env

Configuration

Run vidscribe getenv to create a .env file. Key settings:

# Transcription backend (default: native, no Docker required)
TRANSCRIPTION_BACKEND=native  # or "speaches" for Docker mode

# Native backend settings (faster-whisper)
NATIVE_MODEL=small  # tiny, base, small, medium, large-v1, large-v2, large-v3
NATIVE_DEVICE=auto  # auto, cpu, cuda

# Speaches backend settings (Docker)
SPEACHES_MODEL=Systran/faster-distil-whisper-small.en
SPEACHES_USE_GPU=false  # Set to true for GPU acceleration

# OpenAI API (optional - transcription works without it)
OPENAI_API_KEY=your-key-here
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o

# Summary style (default: concise)
OPENAI_SUMMARY_STYLE=concise  # Options: brief, detailed, bullet-points, concise

# Custom summary prompt (overrides style preset)
OPENAI_CUSTOM_SUMMARY_PROMPT="Summarize focusing on technical details"

For all options, see the .env file created by vidscribe getenv.

CLI Commands

summarize - Summarize a video

vidscribe summarize INPUT [OPTIONS]

Arguments:

• INPUT - Video file path or URL

Options:

• -o, --output PATH - Save summary to file
• --summary-style STYLE - Style: brief, detailed, bullet-points, concise
• --model MODEL - Override LLM model
• --save-transcript - Also save raw transcript

Examples:

vidscribe summarize video.mp4
vidscribe summarize https://www.youtube.com/watch?v=xxx --save-transcript
vidscribe summarize video.mp4 --summary-style bullet-points --output summary.md

getenv - Create .env configuration file

vidscribe getenv

Creates a .env file in your current directory from the built-in template.

list-models - List available Whisper models

vidscribe list-models

Lists available Whisper models for the configured backend:

• Native backend: Shows built-in faster-whisper models
• Speaches backend: Shows models downloaded in your Speaches container

Container Management (Docker mode only)

• vidscribe container-start - Start Speaches container
• vidscribe container-stop - Stop Speaches container
• vidscribe container-status - Check container status

Note: Container is auto-managed during summarization.

Global Options

• --config PATH - Path to custom configuration file (default: .env)
• --verbose - Enable verbose/debug logging

Troubleshooting

"ffprobe not found" Warning

This warning can be safely ignored. Duration detection automatically falls back to the Mutagen library if ffprobe is unavailable. Transcription will work normally.

Transcription Fails on Long Files

Reduce chunk size in .env:

SPEACHES_CHUNK_DURATION_SEC=30
SPEACHES_CHUNK_DURATION_THRESHOLD=60

Container Won't Start (Docker mode)

• Verify Docker is running: docker ps
• Check logs: docker logs speaches
• Restart: vidscribe container-stop && vidscribe container-start

OpenAI API Errors

• Verify API key in .env
• Check API base URL for custom providers
• Verify model name: OPENAI_MODEL=your-custom-model

Development

Use make to setup development environment.

License

This project is licensed under the Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0).