video-composer 0.4.0

AI-powered social video automation tool for generating vertical short-form marketing videos with TTS, subtitles, and stock footage

Video Composer

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

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

pip install video-composer

Requirements

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

Installing FFmpeg

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt update && sudo apt install ffmpeg

Windows: Download from ffmpeg.org or use:

choco install ffmpeg

Quick Start

1. Set Up API Keys

Create a .env file in your project directory:

# 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

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

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

# 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

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

Transcribe Audio

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

Search Stock Footage

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

View Configuration

video-composer config

Version Information

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

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

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:

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

# 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:

ffmpeg -version

API Key Errors

Verify your API keys are set correctly:

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

# 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

# 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 file for details.

Acknowledgments

• OpenAI for TTS and Whisper APIs
• Pexels for free stock video footage
• Pixabay for free stock video footage
• MoviePy for video processing
• Typer for the CLI framework
• Rich for beautiful terminal output

Links

• PyPI Package
• GitHub Repository
• Issue Tracker
• Changelog