AI Shorts

ai-shorts generates short-form video assets from a single topic prompt. The repo now exposes a real Python package, validates generated script JSON before any media step runs, and supports a --dry-run mode that works without an API key.

Modes

Dry Run

Dry run is the safest way to validate the pipeline wiring locally. It:

• does not require OPENAI_API_KEY
• does not call OpenAI
• creates placeholder script.json, image, audio, clip, and final video files
• is ideal for CI, smoke tests, and local setup checks

Example:

python3 generate_short.py "ocean currents" --dry-run --output-dir output/demo

Live Mode

Live mode requires OPENAI_API_KEY (or OPENAI_API) and uses:

• OpenAI for structured script generation
• OpenAI Images for scene art
• gTTS for narration audio
• ffmpeg for clip assembly and concatenation

Example:

python3 generate_short.py "why stars explode" --output-dir output/live-run

Package Layout

• ai_shorts/script.py validates and normalizes script JSON
• ai_shorts/pipeline.py orchestrates providers and artifact creation
• generate_short.py is the CLI entrypoint
• download_music.py remains available for optional future workflow extensions

Validation Rules

Every script must contain:

• a non-empty title
• a non-empty scenes list
• for each scene: non-empty narration, non-empty image_prompt, and positive integer duration

This makes the pipeline fail early with clear errors instead of failing later during audio, image, or video generation.

Python API

from ai_shorts.pipeline import DryRunProvider, run_pipeline
from ai_shorts.script import parse_script_json, validate_script

script = parse_script_json('{"title": "Demo", "scenes": [{"narration": "One", "image_prompt": "Prompt", "duration": 4}]}')
result = run_pipeline("demo topic", "output/demo", DryRunProvider())
print(result.final_video_path)

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run Tests

python3 -m pytest -q

License

MIT. See LICENSE.