Compose video

Create explainer videos with Arka, stock media, charts, TTS, and custom script APIs.

Arka’s video composer builds narrated explainers from a topic, JSON script, LLM, or custom script API. Hybrid mode is the default: voiceover plays, no on-screen text is burned in, and each scene uses stock video or photo B-roll depending on what fits the narration.

arka compose_video compose --topic "AI infrastructure" --llm
arka compose_video compose --topic "AI infrastructure" --text   # legacy captions
arka compose_video compose --topic "AI infrastructure" --mode photos
arka compose_video --script scenes.json

Hybrid mode (default)

Setting	Default	Meaning
VIDEO_MODE	hybrid	Mix stock video + photos per scene
On-screen text	off	TTS/voiceover only unless --text
Per-scene media	AI/heuristic	media_type: video or image in scene JSON

Use --text or VIDEO_BURN_TEXT=1 to restore title/caption overlays. Use --mode photos for image-only slideshows (legacy). Use --mode video for all stock video B-roll.

VIDEO_MODE=hybrid arka compose_video compose --topic "cinematic mountains"
VIDEO_BURN_TEXT=1 arka compose_video compose --topic "AI trends" --llm

Bring your own API

Use a custom HTTP API when you want your own model, workflow, brand system, or script generator to produce the video scenes:

arka compose_video \
  --topic "AI infrastructure" \
  --script-provider custom \
  --api-url https://example.com/arka/video-script

You can configure it once in .env:

VIDEO_SCRIPT_PROVIDER=custom
VIDEO_SCRIPT_API_URL=https://example.com/arka/video-script
VIDEO_SCRIPT_API_KEY=...

If your key lives under another env var:

VIDEO_SCRIPT_API_KEY_ENV=MY_COMPANY_VIDEO_API_KEY

Arka sends a JSON POST body with:

{
  "topic": "AI infrastructure",
  "topic_raw": "ai infrastructure",
  "scenes": 6,
  "target_duration_sec": 300,
  "schema": {
    "type": "array"
  }
}

Your API should return either a scene array or an object with a scenes array:

{
  "scenes": [
    {
      "title": "Why AI infrastructure matters",
      "narration": "AI infrastructure is the stack behind modern models.",
      "body": "The stack behind AI",
      "captions": ["Models need compute", "Data and serving matter"],
      "image_keywords": ["gpu server", "data center"],
      "duration": 8
    }
  ]
}

Arka still validates and enriches the scene JSON locally, then uses the normal renderer, stock-media lookup, chart rendering, TTS, and ffmpeg pipeline. If the custom API fails, Arka falls back to the built-in template so a video command does not fail just because the script provider is unavailable.

Useful flags:

arka compose_video --topic "AI infra" --script-provider custom --api-header "X-Team: demo"
arka compose_video --topic "AI infra" --script-provider custom --api-key-env MY_VIDEO_KEY
arka compose_video check