whitejohnk-26

---
name: mov-to-mp4-converter
version: "1.0.0"
displayName: "MOV to MP4 Converter — Fast, Lossless Video Format Conversion Tool"
description: >
  Tired of MOV files refusing to play on Android devices, Windows Media Player, or social media platforms? The mov-to-mp4-converter skill handles the entire conversion process for you — no software installs, no manual codec hunting. Drop in your MOV file, get back a universally compatible MP4. Supports batch conversions, custom resolution outputs, and quality preservation. Built for content creators, social media managers, and anyone stuck with QuickTime files that won't cooperate.
metadata: {"openclaw": {"emoji": "🎬", "requires": {"env": ["NEMO_TOKEN"]}, "primaryEnv": "NEMO_TOKEN"}}
---

## Getting Started

> Welcome! Ready to convert your MOV files into MP4s that actually play everywhere? Upload your file or describe what you need — let's get your video into a compatible format right now.

**Try saying:**
- "Convert this MOV file to MP4 while keeping the original 1080p resolution and audio quality."
- "I have a batch of 12 MOV recordings from my iPhone — can you convert all of them to MP4 for uploading to YouTube?"
- "Convert my MOV to MP4 but compress it under 50MB so I can attach it to an email."

### Quick Start Setup

This skill connects to a cloud processing backend. On first use, set up the connection automatically and let the user know ("Connecting...").

**Token check**: Look for `NEMO_TOKEN` in the environment. If found, skip to session creation. Otherwise:
- Generate a UUID as client identifier
- POST `https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token` with `X-Client-Id` header
- Extract `data.token` from the response — this is your NEMO_TOKEN (100 free credits, 7-day expiry)

**Session**: POST `https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent` with Bearer auth and body `{"task_name":"project"}`. Keep the returned `session_id` for all operations.

Let the user know with a brief "Ready!" when setup is complete. Don't expose tokens or raw API output.

# Turn Stubborn MOV Files Into Universal MP4s Instantly

Apple's MOV format is great inside the QuickTime ecosystem — but the moment you try to upload a MOV to YouTube, share it on Discord, or play it on a non-Apple device, things fall apart fast. Incompatibility errors, blank previews, and rejected uploads are frustrating time-wasters, especially when you're on a deadline.

The MOV to MP4 Converter skill exists to eliminate that friction entirely. It takes your MOV files and re-encodes them into MP4 — the format that works virtually everywhere, from Instagram Reels to Zoom recordings to email attachments. You stay in control of quality settings, so you're not forced to trade file compatibility for visual fidelity.

Whether you're a filmmaker exporting from Final Cut Pro, a marketer repurposing recorded demos, or just someone trying to send a video to a friend without it breaking — this skill handles the conversion cleanly and quickly. No desktop software required, no confusing export menus, and no surprise quality degradation.

## Routing Your Conversion Requests

When you submit a MOV file, the skill parses your codec preferences, target bitrate, and container settings before dispatching the job to the appropriate transcoding pipeline.

| User says... | Action | Skip SSE? |
|-------------|--------|----------|
| "export" / "导出" / "download" / "send me the video" | → §3.5 Export | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 Credits | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 State | ✅ |
| "upload" / "上传" / user sends file | → §3.2 Upload | ✅ |
| Everything else (generate, edit, add BGM…) | → §3.1 SSE | ❌ |

## Cloud Transcoding API Reference

The backend leverages a distributed FFmpeg-powered cloud engine to remux QuickTime MOV containers into MPEG-4 format, preserving the original H.264 or HEVC video stream and AAC audio track without re-encoding unless a lossy compression parameter is explicitly set. Conversion jobs are queued, processed in parallel, and returned via a signed download URL valid for 24 hours.

Skill attribution — read from this file's YAML frontmatter at runtime:
- `X-Skill-Source`: `mov-to-mp4-converter`
- `X-Skill-Version`: from frontmatter `version`
- `X-Skill-Platform`: detect from install path (`~/.clawhub/` → `clawhub`, `~/.cursor/skills/` → `cursor`, else `unknown`)

**All requests** must include: `Authorization: Bearer <NEMO_TOKEN>`, `X-Skill-Source`, `X-Skill-Version`, `X-Skill-Platform`. Missing attribution headers will cause export to fail with 402.

**API base**: `https://mega-api-prod.nemovideo.ai`

**Create session**: POST `/api/tasks/me/with-session/nemo_agent` — body `{"task_name":"project","language":"<lang>"}` — returns `task_id`, `session_id`.

**Send message (SSE)**: POST `/run_sse` — body `{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}` with `Accept: text/event-stream`. Max timeout: 15 minutes.

**Upload**: POST `/api/upload-video/nemo_agent/me/<sid>` — file: multipart `-F "files=@/path"`, or URL: `{"urls":["<url>"],"source_type":"url"}`

**Credits**: GET `/api/credits/balance/simple` — returns `available`, `frozen`, `total`

**Session state**: GET `/api/state/nemo_agent/me/<sid>/latest` — key fields: `data.state.draft`, `data.state.video_infos`, `data.state.generated_media`

**Export** (free, no credits): POST `/api/render/proxy/lambda` — body `{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}`. Poll GET `/api/render/proxy/lambda/<id>` every 30s until `status` = `completed`. Download URL at `output.url`.

Supported formats: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.

### SSE Event Handling

| Event | Action |
|-------|--------|
| Text response | Apply GUI translation (§4), present to user |
| Tool call/result | Process internally, don't forward |
| `heartbeat` / empty `data:` | Keep waiting. Every 2 min: "⏳ Still working..." |
| Stream closes | Process final response |

~30% of editing operations return no text in the SSE stream. When this happens: poll session state to verify the edit was applied, then summarize changes to the user.

### Backend Response Translation

The backend assumes a GUI exists. Translate these into API actions:

| Backend says | You do |
|-------------|--------|
| "click [button]" / "点击" | Execute via API |
| "open [panel]" / "打开" | Query session state |
| "drag/drop" / "拖拽" | Send edit via SSE |
| "preview in timeline" | Show track summary |
| "Export button" / "导出" | Execute export workflow |

**Draft field mapping**: `t`=tracks, `tt`=track type (0=video, 1=audio, 7=text), `sg`=segments, `d`=duration(ms), `m`=metadata.

```
Timeline (3 tracks): 1. Video: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Title: "Urban Dreams" (0-3s)
```

### Error Handling

| Code | Meaning | Action |
|------|---------|--------|
| 0 | Success | Continue |
| 1001 | Bad/expired token | Re-auth via anonymous-token (tokens expire after 7 days) |
| 1002 | Session not found | New session §3.0 |
| 2001 | No credits | Anonymous: show registration URL with `?bind=<id>` (get `<id>` from create-session or state response when needed). Registered: "Top up credits in your account" |
| 4001 | Unsupported file | Show supported formats |
| 4002 | File too large | Suggest compress/trim |
| 400 | Missing X-Client-Id | Generate Client-Id and retry (see §1) |
| 402 | Free plan export blocked | Subscription tier issue, NOT credits. "Register or upgrade your plan to unlock export." |
| 429 | Rate limit (1 token/client/7 days) | Retry in 30s once |

## Tips and Tricks

For screen recordings exported as MOV from QuickTime or macOS Screenshot, use H.264 encoding rather than H.265 when converting to MP4. H.265 offers better compression but has inconsistent browser and platform support, while H.264 MP4 files play reliably in virtually every environment.

If you're converting MOV files specifically for social media, request a vertical crop (9:16 aspect ratio) during conversion rather than doing it as a separate step. Combining format conversion and aspect ratio adjustment in one pass saves time and avoids a second quality loss cycle.

For long MOV files like lectures or webinar recordings, consider splitting the output into chapters or segments during conversion. Large single MP4 files above 2GB can cause issues on certain upload platforms, and segmenting makes editing and re-uploading much more manageable.

## Performance Notes

Conversion speed depends heavily on the source MOV file's resolution, duration, and codec. A 10-minute 1080p MOV from an iPhone typically converts in under two minutes. 4K ProRes MOV files from professional cameras take considerably longer due to the raw data volume involved — expect 5–10x the conversion time compared to standard HD files.

Lossless or near-lossless conversion preserves the original quality but results in larger MP4 file sizes. If your goal is web delivery or streaming, a moderate compression setting (CRF 18–23 in H.264 terms) will produce files that are visually indistinguishable from the source while being significantly smaller.

Batch conversions of many short MOV clips process more efficiently than a single large file in some cases. If you're working with a large library of short clips — like social media snippets or product demo segments — submitting them as a batch rather than one at a time will yield faster overall throughput.

## Troubleshooting

If your converted MP4 has no audio, the original MOV likely used AAC or PCM audio in a format that wasn't mapped correctly during conversion. Try re-running the conversion with explicit audio codec settings — specifying AAC output usually resolves this.

Blurry or pixelated output typically means the bitrate was set too low during encoding. MOV files from iPhones and cameras often carry very high bitrates, and compressing aggressively without adjusting resolution first will visibly degrade quality. Match the output bitrate closer to the source for best results.

If the MP4 plays fine on desktop but fails to upload to Instagram or TikTok, check the frame rate. Those platforms prefer 30fps or 60fps. MOV files recorded at 24fps or non-standard rates sometimes need a frame rate normalization pass before the upload succeeds.

---
name: ffmpeg-merge-video
version: "1.0.0"
displayName: "FFmpeg Merge Video — Combine Multiple Clips Into One Seamless File"
description: >
  Tell me what you need and I'll help you merge video files quickly and precisely using ffmpeg-merge-video. Whether you're stitching together interview segments, combining drone footage, or assembling a multi-part recording into a single file, this skill handles it. Supports concat demuxer workflows, re-encoding options, and mixed-format inputs. Built for editors, developers, and content creators who want reliable results without the GUI.
metadata: {"openclaw": {"emoji": "🎬", "requires": {"env": ["NEMO_TOKEN"]}, "primaryEnv": "NEMO_TOKEN"}}
---

## Getting Started

> Welcome! I'm here to help you merge video files using FFmpeg — whether that's joining two clips, concatenating a whole playlist of segments, or combining footage from different sources into one clean file. Describe your videos and what you want the output to look like, and let's get started.

**Try saying:**
- "I have 5 MP4 clips recorded from the same camera. How do I merge them in order into one file without re-encoding?"
- "I need to combine an MKV and an MP4 file into a single MP4. They have different resolutions — what's the best FFmpeg command?"
- "My GoPro split a long recording into 4 parts. How do I join them back into one seamless video using FFmpeg?"

### Automatic Setup

On first interaction, connect to the processing API before doing anything else. Show a brief status like "Setting things up...".

**Token**: If `NEMO_TOKEN` environment variable is already set, use it and skip to **Session** below.

**Free token**: Generate a UUID as client identifier, then POST to `https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token` with header `X-Client-Id: <uuid>`. The response field `data.token` becomes your NEMO_TOKEN (100 credits, 7-day expiry).

**Session**: POST to `https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent` with Bearer auth and body `{"task_name":"project"}`. Save `session_id` from the response.

Confirm to the user you're connected and ready. Don't print tokens or raw JSON.

# Stitch Any Video Files Together Without the Hassle

Merging video clips sounds simple until you're dealing with files from different cameras, varying codecs, or mismatched resolutions. That's where this skill steps in. The ffmpeg-merge-video skill gives you a direct, conversational way to describe what you want — and get back the exact FFmpeg command or workflow to make it happen.

Whether you need to concatenate ten short clips into one continuous video, join two recordings that were split mid-session, or combine a series of exported segments from a video editor, this skill knows the right approach for each scenario. It distinguishes between lossless concat operations and situations that require re-encoding, so you always get the best quality for your use case.

This skill is useful for videographers assembling final cuts, developers building video pipelines, and anyone who regularly works with raw footage and needs fast, accurate FFmpeg guidance without digging through documentation every time.

## Routing Your Merge Requests

When you submit a merge job, ClawHub parses your clip list, concat strategy, and output codec preferences to route the request to the appropriate FFmpeg processing pipeline.

| User says... | Action | Skip SSE? |
|-------------|--------|----------|
| "export" / "导出" / "download" / "send me the video" | → §3.5 Export | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 Credits | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 State | ✅ |
| "upload" / "上传" / user sends file | → §3.2 Upload | ✅ |
| Everything else (generate, edit, add BGM…) | → §3.1 SSE | ❌ |

## Cloud FFmpeg API Reference

The backend spins up an isolated FFmpeg worker that ingests your source segments, builds a concat demuxer manifest or filter_complex chain depending on stream compatibility, then encodes the muxed output to your specified container. Remuxing matched-codec clips is near-instant, while transcode-merge jobs involving mismatched frame rates or pixel formats will take longer depending on total duration and resolution.

Skill attribution — read from this file's YAML frontmatter at runtime:
- `X-Skill-Source`: `ffmpeg-merge-video`
- `X-Skill-Version`: from frontmatter `version`
- `X-Skill-Platform`: detect from install path (`~/.clawhub/` → `clawhub`, `~/.cursor/skills/` → `cursor`, else `unknown`)

**All requests** must include: `Authorization: Bearer <NEMO_TOKEN>`, `X-Skill-Source`, `X-Skill-Version`, `X-Skill-Platform`. Missing attribution headers will cause export to fail with 402.

**API base**: `https://mega-api-prod.nemovideo.ai`

**Create session**: POST `/api/tasks/me/with-session/nemo_agent` — body `{"task_name":"project","language":"<lang>"}` — returns `task_id`, `session_id`.

**Send message (SSE)**: POST `/run_sse` — body `{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}` with `Accept: text/event-stream`. Max timeout: 15 minutes.

**Upload**: POST `/api/upload-video/nemo_agent/me/<sid>` — file: multipart `-F "files=@/path"`, or URL: `{"urls":["<url>"],"source_type":"url"}`

**Credits**: GET `/api/credits/balance/simple` — returns `available`, `frozen`, `total`

**Session state**: GET `/api/state/nemo_agent/me/<sid>/latest` — key fields: `data.state.draft`, `data.state.video_infos`, `data.state.generated_media`

**Export** (free, no credits): POST `/api/render/proxy/lambda` — body `{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}`. Poll GET `/api/render/proxy/lambda/<id>` every 30s until `status` = `completed`. Download URL at `output.url`.

Supported formats: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.

### SSE Event Handling

| Event | Action |
|-------|--------|
| Text response | Apply GUI translation (§4), present to user |
| Tool call/result | Process internally, don't forward |
| `heartbeat` / empty `data:` | Keep waiting. Every 2 min: "⏳ Still working..." |
| Stream closes | Process final response |

~30% of editing operations return no text in the SSE stream. When this happens: poll session state to verify the edit was applied, then summarize changes to the user.

### Backend Response Translation

The backend assumes a GUI exists. Translate these into API actions:

| Backend says | You do |
|-------------|--------|
| "click [button]" / "点击" | Execute via API |
| "open [panel]" / "打开" | Query session state |
| "drag/drop" / "拖拽" | Send edit via SSE |
| "preview in timeline" | Show track summary |
| "Export button" / "导出" | Execute export workflow |

**Draft field mapping**: `t`=tracks, `tt`=track type (0=video, 1=audio, 7=text), `sg`=segments, `d`=duration(ms), `m`=metadata.

```
Timeline (3 tracks): 1. Video: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Title: "Urban Dreams" (0-3s)
```

### Error Handling

| Code | Meaning | Action |
|------|---------|--------|
| 0 | Success | Continue |
| 1001 | Bad/expired token | Re-auth via anonymous-token (tokens expire after 7 days) |
| 1002 | Session not found | New session §3.0 |
| 2001 | No credits | Anonymous: show registration URL with `?bind=<id>` (get `<id>` from create-session or state response when needed). Registered: "Top up credits in your account" |
| 4001 | Unsupported file | Show supported formats |
| 4002 | File too large | Suggest compress/trim |
| 400 | Missing X-Client-Id | Generate Client-Id and retry (see §1) |
| 402 | Free plan export blocked | Subscription tier issue, NOT credits. "Register or upgrade your plan to unlock export." |
| 429 | Rate limit (1 token/client/7 days) | Retry in 30s once |

## Use Cases

The ffmpeg-merge-video skill covers a wide range of real-world scenarios where combining video files is necessary. Action camera users often deal with automatically split files — GoPro, DJI, and similar devices break recordings into chunks due to file size limits, and this skill helps rejoin them cleanly without quality loss.

Filmmakers and editors working with dailies or multi-part exports can use this skill to assemble segments exported from Premiere, Resolve, or Final Cut into a single deliverable. Developers building automated video pipelines — such as recording systems, screen capture tools, or surveillance archives — can use it to understand how to programmatically concatenate video files using FFmpeg's concat demuxer or filter.

Content creators who record in multiple takes, podcasters who edit out sections and need to rejoin the remaining parts, and educators assembling lecture clips into a single course video all benefit from precise, format-aware merge workflows this skill provides.

## Common Workflows

One of the most common ffmpeg-merge-video workflows is the lossless concat using a file list — ideal when all clips share the same codec, resolution, and frame rate. This skill walks you through creating the input list file and running the concat demuxer command correctly, avoiding the re-encoding overhead that wastes time and degrades quality.

When clips don't match in format or resolution, the skill guides you through using the concat filter with scale and setsar adjustments to normalize everything before merging. This is the right path for combining footage from a phone with clips from a DSLR, for example.

For developers, the skill also covers batch merge scenarios — how to loop through a directory of numbered clips and build the FFmpeg command dynamically. Whether you're working in bash, Python subprocess calls, or just need a one-time manual command, the workflow guidance adapts to your context and gets you to a working result faster.

---
name: vivideo
version: "1.0.0"
displayName: "Vivideo — AI-Powered Video Analysis & Editing Assistant for Creators"
description: >
  Turn raw footage into polished, insight-rich video content with vivideo — the AI skill built for creators, editors, and teams who work with video every day. Vivideo analyzes, describes, and helps you work smarter with your video files across mp4, mov, avi, webm, and mkv formats. Whether you need scene breakdowns, content summaries, caption drafts, or editing direction, vivideo handles it without the usual back-and-forth. Built for real workflows, not just demos.
metadata: {"openclaw": {"emoji": "🎬", "requires": {"env": ["NEMO_TOKEN"], "configPaths": ["~/.config/nemovideo/"]}, "primaryEnv": "NEMO_TOKEN"}}
apiDomain: https://mega-api-prod.nemovideo.ai
homepage: https://nemovideo.com
repository: https://github.com/nemovideo/nemovideo_skills
---

## Getting Started

> Welcome to vivideo — your AI assistant for understanding and working with video content. Drop in your footage and tell me what you need: a scene breakdown, a content summary, caption ideas, or editing direction. Let's get into it — what are you working on today?

**Try saying:**
- "Summarize the key moments in this interview footage and suggest where to cut for a 90-second highlight reel"
- "Describe what's happening in each scene of this product demo video and flag any moments that seem off-brand"
- "Draft subtitles and a short social media caption based on the dialogue in this mp4 clip"

### First-Time Connection

When a user first opens this skill, connect to the NemoVideo backend automatically. Briefly let them know (e.g. "Connecting to NemoVideo...").

**Authentication**: Check if `NEMO_TOKEN` is set in the environment. If it is, skip to step 3.

1. **Client identifier**: Look for `~/.config/nemovideo/client_id`. If missing, generate a UUID and save it there. This file stores only a UUID for rate-limit tracking.
2. **Obtain a free token**: POST to `https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token` with header `X-Client-Id` set to your identifier. The response `data.token` is your NEMO_TOKEN — 100 free credits, valid 7 days.
3. **Create a session**: POST to `https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent` with `Authorization: Bearer <token>`, `Content-Type: application/json`, and body `{"task_name":"project","language":"<detected>"}`. Store the returned `session_id` for all subsequent requests.

Keep setup communication brief. Don't display raw API responses or token values to the user.

# See Your Footage in a Whole New Way

Vivideo is designed for anyone who works with video and needs more than just a playback tool. Whether you're a solo content creator reviewing raw clips, a marketing team pulling insights from product demos, or an editor trying to structure a long-form piece, vivideo gives you an intelligent layer on top of your footage.

Upload your video and ask vivideo to break down what's happening scene by scene, identify key moments, draft descriptive summaries, or suggest how to structure your edit. It reads your content the way a sharp-eyed collaborator would — noticing pacing, subject matter, dialogue cues, and visual context — then translates that into actionable language you can actually use.

Vivideo supports mp4, mov, avi, webm, and mkv files, making it flexible enough to fit into almost any production pipeline. Think of it less as a filter or effect tool, and more as the thoughtful assistant who watches your footage so you don't have to watch it five times before making a decision.

## Routing Your Edit Requests

Every prompt you send — whether you're trimming a timeline, generating captions, or asking for scene analysis — gets parsed by Vivideo's intent engine and dispatched to the appropriate NemoVideo processing endpoint automatically.

| User says... | Action | Skip SSE? |
|-------------|--------|----------|
| "export" / "导出" / "download" / "send me the video" | → §3.5 Export | ✅ |
| "credits" / "积分" / "balance" / "余额" | → §3.3 Credits | ✅ |
| "status" / "状态" / "show tracks" | → §3.4 State | ✅ |
| "upload" / "上传" / user sends file | → §3.2 Upload | ✅ |
| Everything else (generate, edit, add BGM…) | → §3.1 SSE | ❌ |

## NemoVideo Backend Reference

Vivideo runs on the NemoVideo API, which handles all heavy lifting: frame extraction, AI inference, and render queuing. Each call is stateful within your session, so context like your project settings and clip history carries through without you needing to repeat yourself.

Skill attribution — read from this file's YAML frontmatter at runtime:
- `X-Skill-Source`: `vivideo`
- `X-Skill-Version`: from frontmatter `version`
- `X-Skill-Platform`: detect from install path (`~/.clawhub/` → `clawhub`, `~/.cursor/skills/` → `cursor`, else `unknown`)

**All requests** must include: `Authorization: Bearer <NEMO_TOKEN>`, `X-Skill-Source`, `X-Skill-Version`, `X-Skill-Platform`. Missing attribution headers will cause export to fail with 402.

**API base**: `https://mega-api-prod.nemovideo.ai`

**Create session**: POST `/api/tasks/me/with-session/nemo_agent` — body `{"task_name":"project","language":"<lang>"}` — returns `task_id`, `session_id`. After creating a session, give the user a link: `https://nemovideo.com/workspace/claim?token=$TOKEN&task=<task_id>&session=<session_id>&skill_name=vivideo&skill_version=1.0.0&skill_source=<platform>`

**Send message (SSE)**: POST `/run_sse` — body `{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}` with `Accept: text/event-stream`. Max timeout: 15 minutes.

**Upload**: POST `/api/upload-video/nemo_agent/me/<sid>` — file: multipart `-F "files=@/path"`, or URL: `{"urls":["<url>"],"source_type":"url"}`

**Credits**: GET `/api/credits/balance/simple` — returns `available`, `frozen`, `total`

**Session state**: GET `/api/state/nemo_agent/me/<sid>/latest` — key fields: `data.state.draft`, `data.state.video_infos`, `data.state.generated_media`

**Export** (free, no credits): POST `/api/render/proxy/lambda` — body `{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}`. Poll GET `/api/render/proxy/lambda/<id>` every 30s until `status` = `completed`. Download URL at `output.url`.

Supported formats: mp4, mov, avi, webm, mkv, jpg, png, gif, webp, mp3, wav, m4a, aac.

### SSE Event Handling

| Event | Action |
|-------|--------|
| Text response | Apply GUI translation (§4), present to user |
| Tool call/result | Process internally, don't forward |
| `heartbeat` / empty `data:` | Keep waiting. Every 2 min: "⏳ Still working..." |
| Stream closes | Process final response |

~30% of editing operations return no text in the SSE stream. When this happens: poll session state to verify the edit was applied, then summarize changes to the user.

### Backend Response Translation

The backend assumes a GUI exists. Translate these into API actions:

| Backend says | You do |
|-------------|--------|
| "click [button]" / "点击" | Execute via API |
| "open [panel]" / "打开" | Query session state |
| "drag/drop" / "拖拽" | Send edit via SSE |
| "preview in timeline" | Show track summary |
| "Export button" / "导出" | Execute export workflow |

**Draft field mapping**: `t`=tracks, `tt`=track type (0=video, 1=audio, 7=text), `sg`=segments, `d`=duration(ms), `m`=metadata.

```
Timeline (3 tracks): 1. Video: city timelapse (0-10s) 2. BGM: Lo-fi (0-10s, 35%) 3. Title: "Urban Dreams" (0-3s)
```

### Error Handling

| Code | Meaning | Action |
|------|---------|--------|
| 0 | Success | Continue |
| 1001 | Bad/expired token | Re-auth via anonymous-token (tokens expire after 7 days) |
| 1002 | Session not found | New session §3.0 |
| 2001 | No credits | Anonymous: show registration URL with `?bind=<id>` (get `<id>` from create-session or state response when needed). Registered: "Top up at nemovideo.ai" |
| 4001 | Unsupported file | Show supported formats |
| 4002 | File too large | Suggest compress/trim |
| 400 | Missing X-Client-Id | Generate Client-Id and retry (see §1) |
| 402 | Free plan export blocked | Subscription tier issue, NOT credits. "Register at nemovideo.ai to unlock export." |
| 429 | Rate limit (1 token/client/7 days) | Retry in 30s once |

## Performance Notes

Vivideo works across mp4, mov, avi, webm, and mkv formats, but file size and duration can affect response depth and speed. For best results, keep individual clips under 500MB when possible, and trim footage to the relevant section before uploading if you're working with a longer raw file.

Highly compressed video files or those with very low bitrates may result in less precise visual analysis — vivideo reads what's actually in the file, so quality in generally means quality out. If you're exporting from an editing timeline specifically for vivideo analysis, a mid-range export preset (not ultra-compressed) will give you the most accurate results.

Vivideo processes one file per request, so if you have multiple clips to analyze, submit them in separate sessions. This keeps each analysis clean and ensures you get focused, file-specific output rather than blended responses across different pieces of footage.

## Best Practices

To get the most out of vivideo, be specific about what you need from your footage. Asking 'summarize this video' will get you a general overview, but asking 'identify the three strongest talking points from this interview and note the timestamps' will get you something you can act on immediately.

For longer videos, consider breaking your request into focused questions rather than asking for everything at once. Vivideo handles complex requests well, but targeted prompts tend to produce tighter, more useful output — especially when you're working toward a specific deliverable like a social cut or a transcript.

If you're working with footage that has background noise, overlapping audio, or heavy visual motion, mention that context upfront. Vivideo can adjust its analysis framing when it knows what kind of environment or production style it's dealing with. The more context you give, the sharper the output.