@profullstack/viral-video

Generate 60‑sec Viral Video Kits

Generate a complete short‑video kit from a topic: script, scene images, captions, voiceover, and an optional rendered MP4. Built for Node.js 20+ using modern ESM.

Core files:

• CLI entry: bin/viral.js
• Main runtime: run()
• Image generation helper: generateImage()
• CLI helpers: usage(), setupCommand(), prompt()

Features

• 1080×1920 vertical target with smooth zoom pan
• Script+captions tailored to the requested duration
• Per‑scene image prompts; styles: cartoon, realistic, ai-generated
• Voiceover via OpenAI TTS (ElevenLabs key persisted for future TTS integration)
• Config precedence: environment > user config > defaults

Requirements

• Node.js 20+
• pnpm 9+
• ffmpeg (optional, for auto‑render)

Install

pnpm add -D @profullstack/viral-video
# or run without installing:
pnpm dlx @profullstack/viral-video viral --help

Optionally link CLI globally:

pnpm add -g @profullstack/viral-video
# or from a local checkout:
pnpm link --global
# then you can run: viral ...

Setup

Use interactive mode to save API keys at ~/.config/viral-video/config.json (0600 perms):

viral setup

Or non‑interactive:

viral setup --openai-key sk-... --elevenlabs-key el-... --voice luna --video-sec 60

Create a video kit

viral create --topic "How to make money while you sleep" --male --cartoon

Flags

• --topic "..." required
• --male | --female sets TTS voice preset
• --cartoon | --realistic | --ai-generated image style
• --dry-run validate flow without calling APIs or ffmpeg

What gets generated

Inside build/your-topic/:

• vertical/
  • scenes/sceneXX.png: portrait frames (generated at 1024×1536, upscaled to 1080×1920 on render)
  • audio/voiceover.mp3 (copied)
  • captions.ass
  • storyboard.csv
  • build/: intermediate segments and rendered artifacts
  • output.mp4: final portrait video (when ffmpeg available)
• horizontal/
  • scenes/sceneXX.png: landscape frames (generated at 1536×1024, upscaled to 1920×1080 on render)
  • audio/voiceover.mp3 (copied)
  • captions.ass
  • storyboard.csv
  • build/: intermediate segments and rendered artifacts
  • output.mp4: final landscape video (when ffmpeg available)
• audio/voiceover.mp3: root voiceover source
• README.md: per‑video instructions

Rendering details

The pipeline scales frames using ffmpeg to 1080×1920:

• We request OpenAI images at 1024×1536 (portrait) due to API constraints, then upscale to 1080×1920 during render.
• If ffmpeg is installed, rendering runs automatically:
  • macOS: brew install ffmpeg
  • Ubuntu: sudo apt-get update && sudo apt-get install -y ffmpeg

Configuration

Precedence: env > user config > defaults. The config loader lives in run() and the setup logic is in setupCommand().

Environment variables

• OPENAI_API_KEY: required unless DRY_RUN=1
• ELEVENLABS_API_KEY: optional (future TTS)
• TEXT_MODEL (default gpt-5)
• IMAGE_MODEL (default gpt-image-1)
• TTS_MODEL (default gpt-4o-mini-tts)
• TTS_VOICE (default alloy; use luna for female)
• VIDEO_SEC (default 60)
• SCENES_COUNT (default 6)

User config file

• Path: ~/.config/viral-video/config.json or $XDG_CONFIG_HOME/viral-video/config.json
• Written by setupCommand() with chmod 600

Examples

Validate without APIs:

DRY_RUN=1 viral create --topic "SEC Bitcoin ETF timeline" --ai-generated

Female realistic style:

viral create --topic "Dollar-cost averaging explained" --female --realistic

Troubleshooting

• Missing OPENAI_API_KEY: run viral setup or export OPENAI_API_KEY.
• “Unsupported image size”: fixed by generating 1024×1536 and scaling during render in generateImage().
• Interactive setup “hang”: resolved by releasing stdin in prompt().

Development

pnpm test
pnpm lint
pnpm format

License

MIT