Metadata-Version: 2.4
Name: vidscribe
Version: 0.1.8
Summary: CLI tool for automatic video summarization using Whisper and LLMs
Project-URL: Homepage, https://github.com/yeyuan98/video_summarizer
Project-URL: Repository, https://github.com/yeyuan98/video_summarizer
Project-URL: Issues, https://github.com/yeyuan98/video_summarizer/issues
Author: yeyuan98
License: CC-BY-NC-ND-4.0
License-File: LICENSE.md
Keywords: cli,summarization,transcription,video,whisper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.10
Requires-Dist: click
Requires-Dist: docker
Requires-Dist: faster-whisper>=1.0.0
Requires-Dist: httpx
Requires-Dist: imageio-ffmpeg>=0.6.0
Requires-Dist: loguru
Requires-Dist: moviepy
Requires-Dist: mutagen
Requires-Dist: openai
Requires-Dist: pydantic
Requires-Dist: pydantic-settings
Requires-Dist: python-dotenv
Requires-Dist: rich-click
Requires-Dist: yt-dlp
Description-Content-Type: text/markdown

# Video Summarizer

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

## Quick Start

```bash
# 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

```bash
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:

```bash
# 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

```bash
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:**
```bash
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

```bash
vidscribe getenv
```

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

### `list-models` - List available Whisper models

```bash
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`:
```bash
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)](https://creativecommons.org/licenses/by-nc-nd/4.0/).
