auto-video

Stitch timestamped images with audio into a video using ffmpeg.

Images are matched by timestamp patterns like [MM-SS] in their filenames. Each image plays until the next timestamp, and the audio track is overlaid.

Requirements

• Node.js >= 18
• ffmpeg (with ffprobe) on PATH

Install

# Run on demand (no install)
npx auto-video [options] [project-dir]

# Global install
npm install -g auto-video
# or
pnpm add -g auto-video

# Then run from anywhere
auto-video [options] [project-dir]

Usage

Options

| Flag | Description | | --------------------- | --------------------------------------------------- | | -p, --project <dir> | Project directory (default: .) | | -i, --images <dir> | Images directory (default: <project>/clips) | | -a, --audio <file> | Audio file (default: <project>/voice_over.mp3) | | -o, --output <file> | Output video file (default: <project>/output.mp4) | | --orientation <rat> | Aspect ratio 16:9 or 9:16 (default: 16:9) | | --width <px> | Video width (overrides orientation preset) | | --height <px> | Video height (overrides orientation preset) | | --version | Show version | | -h, --help | Show help |

Examples

# Use clips/ and voice_over.mp3 in current dir
npx auto-video

# Portrait (9:16) for TikTok/Shorts
npx auto-video --orientation 9:16

# Specify a project directory
npx auto-video ./my-talk

# Custom paths and orientation
npx auto-video -i ./slides -a ./narration.mp3 -o ./final.mp4 --orientation 9:16

# Custom resolution (overrides orientation)
npx auto-video --width 1440 --height 2560

Project structure (default)

<ProjectRoot>/
├── clips/
│   ├── intro [00-05].jpg
│   ├── welcome [00-10].jpg
│   └── ...
├── voice_over.mp3
└── output.mp4   (generated)

Publishing

npm publish
# or
pnpm publish