> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> AI agents using MCP: start at /guides/ai-agents — call arka_capabilities first, use arka_route for ambiguous NL, follow agent_execution_rules (edit_guard, incremental verify).
> Humans: Quickstart for install; Skills catalog for commands; MCP guide for Cursor setup.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# 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.

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
arka compose_video \
  --topic "AI infrastructure" \
  --script-provider custom \
  --api-url https://example.com/arka/video-script
```

You can configure it once in `.env`:

```bash theme={null}
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:

```bash theme={null}
VIDEO_SCRIPT_API_KEY_ENV=MY_COMPANY_VIDEO_API_KEY
```

Arka sends a JSON POST body with:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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
```


## Related topics

- [Skills catalog: 70+ built-in Arka commands](/guides/skills.md)
- [Compose shorts](/guides/compose-shorts.md)
- [LLM orchestration with multi-provider failover](/concepts/llm.md)
- [Testing Arka with the pytest suite](/guides/testing.md)
- [How Arka compares to other agents](/concepts/comparison.md)