video-composer 0.4.0
AI-powered social video automation tool for generating vertical short-form marketing videos with TTS, subtitles, and stock footage
License: MIT
Requires Python: >=3.11
Keywords: ai, automation, content-creation, marketing, openai, pexels, reels, short-form, shorts, social-media, subtitles, text-to-speech, tiktok, tts, vertical-video, video, whisper

# Video Composer

AI-powered social video automation tool for generating vertical short-form marketing videos for TikTok, YouTube Shorts, and Instagram Reels.

[![PyPI version](https://badge.fury.io/py/video-composer.svg)](https://badge.fury.io/py/video-composer)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **AI-Powered Voiceover**: Generate natural-sounding voiceovers using OpenAI TTS (text-to-speech) with multiple voice options
- **Word-Level Transcription**: Accurate transcription with word-level timestamps using OpenAI Whisper
- **AI Video Validation**: Validate stock footage relevance using GPT-4 Vision
- **Multiple Stock Providers**: Fetch relevant vertical videos from Pexels or Pixabay based on keywords
- **Karaoke-Style Subtitles**: Animated subtitles with word-by-word highlighting in ASS format
- **9:16 Aspect Ratio**: Optimized for TikTok, YouTube Shorts, and Instagram Reels
- **YAML Configuration**: Define videos in YAML for batch processing
- **Rich CLI**: Beautiful command-line interface with progress indicators

## Installation

```bash
pip install video-composer
```

### Requirements

- Python 3.11 or higher
- FFmpeg (must be installed and available in PATH)

#### Installing FFmpeg

**macOS:**
```bash
brew install ffmpeg
```

**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install ffmpeg
```

**Windows:**
Download from [ffmpeg.org](https://ffmpeg.org/download.html) or use:
```bash
choco install ffmpeg
```

## Quick Start

### 1. Set Up API Keys

Create a `.env` file in your project directory:

```bash
# Required
OPENAI_API_KEY=sk-your-openai-api-key

# Stock footage provider (choose one or both)
PEXELS_API_KEY=your-pexels-api-key
PIXABAY_API_KEY=your-pixabay-api-key

# Optional: Set preferred provider (default: pexels)
STOCK_PROVIDER=pexels  # or "pixabay"
```

Get your API keys:
- OpenAI: https://platform.openai.com/api-keys
- Pexels: https://www.pexels.com/api/
- Pixabay: https://pixabay.com/api/docs/

### 2. Create Your First Video

```bash
video-composer create \
  --script "Welcome to the future of content creation. AI makes everything possible." \
  --keyword technology \
  --keyword innovation \
  --keyword future
```

## CLI Commands

### Create a Video

```bash
video-composer create \
  --script "Your marketing script here" \
  --keyword keyword1 \
  --keyword keyword2 \
  --output my_video \
  --verbose
```

**Options:**
- `-s, --script`: The marketing script text to convert to video (required)
- `-k, --keyword`: Keywords for stock footage (can specify multiple, required)
- `-o, --output`: Output filename without extension (optional)
- `-c, --context`: Additional context for video validation (optional)
- `--subtitle-font`: Subtitle font family (optional)
- `--subtitle-font-size`: Subtitle font size (optional)
- `--subtitle-primary-color`: Subtitle primary color (`#RRGGBB` or ASS) (optional)
- `--subtitle-highlight-color`: Subtitle highlight color (`#RRGGBB` or ASS) (optional)
- `--subtitle-outline-color`: Subtitle outline color (`#RRGGBB` or ASS) (optional)
- `--subtitle-outline-width`: Subtitle outline width (optional)
- `--subtitle-shadow-depth`: Subtitle shadow depth (optional)
- `--subtitle-position`: Subtitle position (`top`, `center`, `bottom`) (optional)
- `--subtitle-margin`: Subtitle bottom margin in pixels (optional)
- `--subtitle-words-per-line`: Maximum words per subtitle line (optional)
- `--subtitles-enabled/--no-subtitles`: Enable or disable subtitle rendering (optional)
- `--keep-temp`: Keep temporary files after processing
- `-v, --verbose`: Enable verbose logging

### Generate from YAML Configuration

```bash
# Create a sample configuration
video-composer init-config

# Or create a batch configuration
video-composer init-config --batch -o batch_videos.yaml

# Generate videos from configuration
video-composer from-yaml videos.yaml
```

### Text-to-Speech Only

```bash
video-composer tts --script "Hello world" --output speech.mp3
```

### Transcribe Audio

```bash
video-composer transcribe --audio input.mp3 --output transcription.json
```

### Search Stock Footage

```bash
video-composer search-footage --keyword nature --keyword sunset --output-dir ./footage
```

### View Configuration

```bash
video-composer config
```

### Version Information

```bash
video-composer version
```

## YAML Configuration

Video Composer supports YAML configuration files for defining videos. This is ideal for batch processing or reproducible video generation.

Subtitle colors support hex values (`#RRGGBB`) or ASS color strings (`&H00BBGGRR`).

### Single Video Configuration

```yaml
script: |
  Every successful person started exactly where you are right now.
  The difference? They didn't give up.
  Your dreams are valid. Your goals are achievable.

keywords:
  - sunrise motivation
  - person working hard
  - success celebration

voice:
  model: tts-1-hd
  voice: nova
  speed: 1.0

subtitles:
  enabled: true
  font: Arial
  font_size: 48
  primary_color: "#FFFFFF"
  highlight_color: "#FFFF00"
  outline_color: "#000000"
  outline_width: 3
  shadow_depth: 2
  position: bottom
  margin: 150
  words_per_line: 4

video:
  width: 1080
  height: 1920
  fps: 30

output_filename: motivation_video
output_dir: ./output
```

### Batch Video Configuration

```yaml
version: "1.0"

# Global defaults
voice:
  model: tts-1-hd
  voice: nova

subtitles:
  enabled: true
  font: Arial
  font_size: 48
  primary_color: "#FFFFFF"
  highlight_color: "#FFFF00"
  outline_color: "#000000"
  outline_width: 3
  shadow_depth: 2
  position: bottom
  margin: 150
  words_per_line: 4

output_dir: ./output

# Multiple videos
videos:
  - name: motivation_monday
    script: "Start your week with purpose..."
    keywords:
      - sunrise
      - motivation

  - name: tech_tips
    script: "Three tips to boost productivity..."
    keywords:
      - technology
      - workspace
    voice:
      voice: onyx  # Override default voice
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OPENAI_API_KEY` | Yes | - | OpenAI API key for TTS and Whisper |
| `PEXELS_API_KEY` | Conditional | - | Pexels API key (required if using Pexels) |
| `PIXABAY_API_KEY` | Conditional | - | Pixabay API key (required if using Pixabay) |
| `STOCK_PROVIDER` | No | pexels | Stock footage provider (`pexels` or `pixabay`) |
| `VIDEO_WIDTH` | No | 1080 | Output video width |
| `VIDEO_HEIGHT` | No | 1920 | Output video height |
| `VIDEO_FPS` | No | 30 | Output video frame rate |
| `TTS_MODEL` | No | tts-1-hd | OpenAI TTS model |
| `TTS_VOICE` | No | nova | TTS voice (alloy, echo, fable, onyx, nova, shimmer) |
| `TTS_SPEED` | No | 1.0 | TTS playback speed |
| `VISION_MODEL` | No | gpt-4o | Model for video validation |
| `SUBTITLE_FONT` | No | Arial | Subtitle font family |
| `SUBTITLE_FONT_SIZE` | No | 48 | Subtitle font size |
| `SUBTITLE_PRIMARY_COLOR` | No | &H00FFFFFF | Subtitle primary color (ASS format) |
| `SUBTITLE_HIGHLIGHT_COLOR` | No | &H0000FFFF | Subtitle highlight color (ASS format) |
| `SUBTITLE_OUTLINE_COLOR` | No | &H00000000 | Subtitle outline color (ASS format) |
| `SUBTITLE_OUTLINE_WIDTH` | No | 3 | Subtitle outline width |
| `SUBTITLE_SHADOW_DEPTH` | No | 2 | Subtitle shadow depth |
| `SUBTITLE_POSITION` | No | bottom | Subtitle position (`top`, `center`, `bottom`) |
| `SUBTITLE_MARGIN_BOTTOM` | No | 150 | Subtitle bottom margin in pixels |
| `SUBTITLE_WORDS_PER_LINE` | No | 4 | Maximum words per subtitle line |
| `SUBTITLES_ENABLED` | No | true | Enable subtitle generation |
| `TEMP_DIR` | No | ./temp | Temporary files directory |
| `OUTPUT_DIR` | No | ./output | Output directory |

## Python API

Video Composer can also be used as a Python library:

```python
import asyncio
from video_composer import VideoComposer

async def create_video():
    async with VideoComposer() as composer:
        result = await composer.create_video(
            script="Your marketing script here",
            keywords=["technology", "innovation"],
            output_filename="my_video",
        )

        if result.success:
            print(f"Video created: {result.output_path}")
            print(f"Duration: {result.duration}s")
        else:
            print(f"Error: {result.error}")

asyncio.run(create_video())
```

### Available Methods

```python
# Full video creation
result = await composer.create_video(script, keywords, output_filename, validation_context)

# Text-to-speech only
audio_path = await composer.generate_tts_only(script, output_path)

# Transcription only
transcription = await composer.transcribe_audio_only(audio_path)
```

## Output

Videos are generated in MP4 format with:

- **Resolution**: 1080x1920 (9:16 vertical)
- **Frame Rate**: 30 FPS
- **Audio**: AAC codec
- **Video**: H.264 codec
- **Subtitles**: Burned-in ASS subtitles with karaoke-style highlighting

## Project Structure

```
your-project/
├── .env                 # API keys (not committed)
├── .env.example         # Example environment file
├── videos.yaml          # Video configuration
├── output/              # Generated videos
│   └── my_video.mp4
└── temp/                # Temporary files (auto-cleaned)
```

## Troubleshooting

### FFmpeg Not Found

Ensure FFmpeg is installed and in your PATH:
```bash
ffmpeg -version
```

### API Key Errors

Verify your API keys are set correctly:
```bash
video-composer config
```

### Memory Issues with Long Videos

For longer scripts, consider:
1. Breaking the script into smaller segments
2. Increasing system swap space
3. Using a machine with more RAM

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/youhanasheriff/video-composer.git
cd video-composer

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

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src/
mypy src/
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=video_composer --cov-report=html

# Run specific test file
pytest tests/test_subtitles.py -v
```

## Contributing

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

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [OpenAI](https://openai.com/) for TTS and Whisper APIs
- [Pexels](https://www.pexels.com/) for free stock video footage
- [Pixabay](https://pixabay.com/) for free stock video footage
- [MoviePy](https://zulko.github.io/moviepy/) for video processing
- [Typer](https://typer.tiangolo.com/) for the CLI framework
- [Rich](https://rich.readthedocs.io/) for beautiful terminal output

## Links

- [PyPI Package](https://pypi.org/project/video-composer/)
- [GitHub Repository](https://github.com/youhanasheriff/video-composer)
- [Issue Tracker](https://github.com/youhanasheriff/video-composer/issues)
- [Changelog](https://github.com/youhanasheriff/video-composer/blob/main/CHANGELOG.md)