shawty

Overview

Shawty automates the tedious process of creating short-form video content. It bridges the gap between a text script and a rendered video file.

By combining Edge TTS for high-quality voiceovers and FFmpeg for media processing, Shawty allows you to define a video in a simple JSON format. It handles:

• Generating high-quality speech from text.
• Calculating scene duration based on audio length.
• Cycling through images evenly during each scene.
• Burning subtitles (or generating SRT files).
• Mixing background music with auto-ducking.

Installation

Shawty requires Python 3.12+ and FFmpeg installed on your system.

git clone https://github.com/Phillip-England/shawty.git
cd shawty
pip install .

Core Commands

Generating Audio

Generate standalone MP3 files from text using high-quality neural voices.

shawty audio "Hello world, this is a test." output.mp3

Project Initialization

Scaffold a new movie project with example assets and a `script.json` file.

shawty init my_new_movie

This creates dummy images and audio files using FFmpeg filters so you can render a test video immediately.

Making Movies

The core command. Reads a project directory, processes the `script.json`, and outputs a finished video.

shawty movie ./my_new_movie output.mp4

Script Format

The `script.json` file controls every aspect of the video generation.

{
  "format": "full",  // or "short" (1080x1920)
  "background_track": "music/chill.mp3",
  "background_volume": 0.1,
  "subtitles": {
    "burn": true,
    "size": 32,
    "position": "center"
  },
  "scenes": [
    {
      "text": "This is the first scene. The duration is calculated by TTS.",
      "voice": "en-US-GuyNeural",
      "speed": "+10%",
      "images": ["img/intro_1.jpg", "img/intro_2.jpg"]
    },
    {
      "audio": "audio/voiceover.mp3",
      "images": ["img/chart.png"]
    }
  ]
}

Project Structure

shawty/
├── shawty/
│   ├── cli.py (Entry point)
│   └── commands/
│       ├── audio.py (Edge TTS integration)
│       ├── init.py (Project scaffolding)
│       └── movie.py (FFmpeg pipeline)
├── pyproject.toml
└── Makefile