Getting Started

Welcome! I'm here to help you add subtitles to your videos using FFmpeg — whether you want them burned in permanently or attached as a toggleable track. Tell me about your video file and subtitle source, and let's get started!

Try saying:

• - "Burn in subtitles from an SRT file onto my MP4 video and keep the original audio quality"
• "Attach a soft VTT subtitle track to an MKV file without re-encoding the video stream"
• "Add styled ASS subtitles to a video with a custom font and position them at the top of the frame"

Getting Connected

Before handling any user request, establish a connection to the backend API. Show a brief status like "Connecting...".

If NEMO_TOKEN is in the environment, use it directly and create a session. Otherwise, acquire a free starter token:

• - Ensure a client identifier exists at ~/.config/ffmpeg-add-subtitle/client_id (create one as a UUID if needed)
• POST to https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token with the X-Client-Id header
• The response includes a token with 100 free credits valid for 7 days — use it as NEMO_TOKEN

Then create a session by POSTing to https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent with Bearer authorization and body {"task_name":"project","language":"en"}. The session_id in the response is needed for all following requests.

Tell the user you're ready. Keep the technical details out of the chat.

Embed Subtitles Into Any Video With Precision

Adding subtitles to a video sounds simple — until you're staring at FFmpeg documentation trying to figure out why your SRT file isn't rendering, or why the font looks wrong, or why soft subs aren't showing up in your media player. That's exactly what this skill is built to solve.

With the FFmpeg Add Subtitle skill, you can embed subtitles in two distinct ways: as a hard-coded burn-in (permanently baked into the video frames) or as a soft subtitle stream (a separate track viewers can toggle on or off). Both approaches have real-world use cases, and this skill helps you choose the right one and execute it correctly.

Whether you're localizing a course video, captioning a short film, adding translated subs to a documentary, or preparing accessible content for social media, this skill generates the exact FFmpeg commands you need — with the right filters, codec flags, and file path handling — so you get clean results the first time.

Routing Subtitle Burn-In Requests

When you submit a subtitle embedding job, the skill parses your input to determine whether you're hardcoding subtitles directly into the video stream via libass filter or attaching a soft subtitle track as a separate mux stream, then routes accordingly.

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 | ❌ |

FFmpeg Cloud API Reference

The backend spins up an isolated FFmpeg processing node that handles subtitle codec mapping, filter graph construction, and container muxing — supporting SRT, ASS, VTT, and PGS formats across MP4, MKV, and MOV containers. Transcoding jobs run server-side so your local machine never touches the bitstream.

Skill attribution — read from this file's YAML frontmatter at runtime:

• - X-Skill-Source: INLINECODE9
• INLINECODE10: from frontmatter INLINECODE11
• INLINECODE12: 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: INLINECODE22

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: INLINECODE32

Credits: GET /api/credits/balance/simple — returns available, frozen, INLINECODE36

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

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.

CODEBLOCK0

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

Content creators publishing multilingual videos often use ffmpeg-add-subtitle to batch-process translated SRT files onto the same base video, producing multiple language versions efficiently without re-editing the source.

E-learning developers rely on subtitle embedding to meet accessibility requirements, ensuring that course videos include accurate captions for learners with hearing impairments or those watching in sound-sensitive environments.

Film and video editors working on indie productions use the ASS/SSA format support to embed richly styled subtitles — with custom fonts, colors, and animations — directly into screener copies or festival submissions.

Social media managers frequently need to burn subtitles into square or vertical crops of longer videos, where the subtitle position and size need to be adjusted to avoid overlapping with on-screen graphics. This skill helps dial in those positioning parameters precisely using FFmpeg's filter options.

Common Workflows

The most frequent workflow is burning an SRT file directly into a video using FFmpeg's subtitles filter. This permanently renders the text onto each frame, making it ideal for platforms like Instagram or YouTube Shorts where external subtitle tracks aren't supported. You specify the subtitle file path, optionally define a font name and size, and FFmpeg handles the rest during re-encoding.

For more flexible distribution — such as MKV files intended for media center playback — soft subtitle embedding is the better choice. Here, FFmpeg muxes the subtitle stream alongside the video and audio without touching the actual picture quality. Viewers can enable or disable subtitles in their player.

Another common need is converting subtitle formats before embedding. If you have a WebVTT file but need SRT compatibility, or an ASS file with complex styling you want to simplify, this skill can walk you through the conversion step before the final embed — keeping your workflow clean and your output predictable.