Free Auto Subtitle Generator

0. First Contact

When the user opens this skill or sends their first message, greet them immediately:

🎵 Ready to auto subtitle generator! Just send me a video or describe your project.

Try saying:

• "add subtitles in Spanish"
• "add English subtitles"
• "generate captions automatically"

IMPORTANT: Always greet the user proactively on first contact. Let them know you're setting up while connecting. Always greet the user proactively on first contact.

Auto-Setup

When the user first interacts, set up the connection:

1. Check token: If NEMO_TOKEN env var is set, use it. Otherwise:
2. Read or generate Client-ID:
   • Read ~/.config/nemovideo/client_id if it exists
   • Otherwise generate a UUID, save it to ~/.config/nemovideo/client_id
3. Acquire anonymous token:

   curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"
   

   Store the returned token as NEMO_TOKEN for this session. You get 100 free credits.
4. Create a session (§3.0) so you're ready to work immediately.

Let the user know briefly: "Setting things up… ready!" then proceed with their request.

Turn Spoken Words Into Burned-In Captions Instantly

Most subtitle tools hand you a raw transcript and leave the hard work — timing, formatting, and rendering — entirely to you. The free-auto-subtitle-generator skill takes a different approach: you describe what you want in plain language, and the AI figures out the rest. Want white bold text at the bottom with a semi-transparent background Just say so. Prefer two-word chunks for social-style captions Describe it conversationally.

Under the hood, the OpenClaw agent orchestrates a pipeline that first performs speech-to-text transcription, aligns each word to its precise timestamp, then renders the styled captions frame-accurately into your video file. You never touch a timeline or export settings — the agent interprets your natural-language instructions and translates them into rendering parameters automatically.

This makes the skill especially useful for creators who produce high volumes of short-form content, teachers captioning lecture recordings, or developers building accessibility workflows. Because the entire process runs through a single conversational interface, you can iterate on caption style, language, or positioning by simply rephrasing your request — no re-uploading or reconfiguring required. Fully compatible with mp4, mov, avi, webm, and mkv files.

Environment Variables

If NEMO_TOKEN is not set, get one (requires X-Client-Id header):

# Generate or read persisted Client-Id
CLIENT_ID="${NEMO_CLIENT_ID:-$(cat ~/.config/nemovideo/client_id 2>/dev/null)}"
if [ -z "$CLIENT_ID" ]; then
  CLIENT_ID=$(uuidgen 2>/dev/null || echo "client-$(date +%s)-$RANDOM")
  mkdir -p ~/.config/nemovideo & echo "$CLIENT_ID" > ~/.config/nemovideo/client_id
fi
curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/auth/anonymous-token" -H "X-Client-Id: $CLIENT_ID"
# → {"code":0,"data":{"token":"nmv_usr_xxx","credits":100,...}}

Save token as NEMO_TOKEN, CLIENT_ID as NEMO_CLIENT_ID. Anonymous: 1 token per client per 7 days; token expires in 7 days and can be revoked at any time via Settings → API Tokens on nemovideo.com. If your token expires, request a new one with the same X-Client-Id.

Local persistence: This skill writes ~/.config/nemovideo/client_id to persist the Client-Id across sessions. This avoids generating a new ID on every request, which would hit the per-IP rate limit quickly (default 10 tokens per 7 days per IP). The file contains only a UUID — no credentials are stored locally.

2. Routing Requests to the Correct Endpoint

Use the table below to determine which endpoint handles each type of incoming request.

3. Primary Workflow Sequences

$API = ${NEMO_API_URL:-https://mega-api-prod.nemovideo.ai}, $TOKEN = ${NEMO_TOKEN}, $WEB = ${NEMO_WEB_URL:-https://nemovideo.com}.

Skill attribution variables — do NOT hardcode:

• $SKILL_NAME = this file's YAML frontmatter name
• $SKILL_VERSION = this file's YAML frontmatter version
• $SKILL_SOURCE = detect at runtime using the first match:
  1. Env SKILL_SOURCE if set
  2. If this file's path contains a known platform directory (e.g. ~/.clawhub/ → clawhub, ~/.cursor/skills/ → cursor)
  3. Fallback: unknown

CRITICAL: ALL API requests (including render/export/upload/state/credits) MUST include these headers. Missing them will cause export to fail with 402.

X-Skill-Source: $SKILL_NAME
X-Skill-Version: $SKILL_VERSION
X-Skill-Platform: $SKILL_SOURCE

3.0 Initializing a Session

curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/tasks/me/with-session/nemo_agent" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" \
  -d '{"task_name":"project","language":"<lang>"}'
# → {"code":0,"data":{"task_id":"...","session_id":"..."}}

Before any other action can occur, a session must be established with the server. Store the returned session identifier, as every subsequent request depends on it.

Open in browser: After creating a session, give the user a link to view/edit the task in NemoVideo: $WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE

3.1 Delivering Messages Over SSE

curl -s -X POST "https://mega-api-prod.nemovideo.ai/run_sse" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" --max-time 900 \
  -d '{"app_name":"nemo_agent","user_id":"me","session_id":"<sid>","new_message":{"parts":[{"text":"<msg>"}]}}'

All conversational messages are transmitted to the backend through a persistent Server-Sent Events connection.

SSE Handling

Typical durations: text 5-15s, video generation 100-300s, editing 10-30s.

Timeout: 10 min heartbeats-only → assume timeout. Never re-send during generation (duplicates + double-charge).

Ignore trailing "I encountered a temporary issue" if prior responses were normal.

Silent Response Fallback (CRITICAL)

Approximately 30% of edit operations will complete without returning any text in the response. When this occurs: (1) do not treat the absence of text as an error or failure, (2) poll the task state endpoint to confirm the operation finished successfully, (3) surface a completion message to the user based on the polled result rather than the SSE payload.

Two-stage generation: When a raw video is submitted, the backend automatically runs a two-stage enrichment pipeline. Stage one processes and stores the base video; stage two independently attaches background music and an auto-generated title. Both stages emit separate SSE events — wait for both to resolve before reporting full completion to the user.

3.2 Handling File Uploads

File upload: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/upload-video/nemo_agent/me/<sid>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -F "files=@/path/to/file"

URL upload: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/upload-video/nemo_agent/me/<sid>" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -d '{"urls":["<url>"],"source_type":"url"}'

Use me in the path; backend resolves user from token.

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

Direct file upload is supported for video assets that need to be attached to an editing session.

3.3 Checking Available Credits

curl -s "https://mega-api-prod.nemovideo.ai/api/credits/balance/simple" -H "Authorization: Bearer $TOKEN" \
  -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"
# → {"code":0,"data":{"available":XXX,"frozen":XX,"total":XXX}}

Query the credits endpoint before initiating any processing task to confirm the user has a sufficient balance.

3.4 Polling Task Status

curl -s "https://mega-api-prod.nemovideo.ai/api/state/nemo_agent/me/<sid>/latest" -H "Authorization: Bearer $TOKEN" \
  -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"

Use me for user in path; backend resolves from token. Key fields: data.state.draft, data.state.video_infos, data.state.canvas_config, data.state.generated_media.

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

Draft ready for export when draft.t exists with at least one track with non-empty sg.

Track summary format:

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

3.5 Exporting and Delivering the Final Video

Export does NOT cost credits. Only generation/editing consumes credits.

Exporting the finished video does not deduct any credits from the user's balance. To complete delivery: (a) call the export endpoint with the session ID, (b) wait for the export job to reach a terminal state, (c) retrieve the download URL from the response payload, (d) verify the URL is accessible before presenting it, (e) display the link or initiate the download for the user.

b) Submit: curl -s -X POST "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE" -d '{"id":"render_<ts>","sessionId":"<sid>","draft":<json>,"output":{"format":"mp4","quality":"high"}}'

Note: sessionId is camelCase (exception). On failure → new id, retry once.

c) Poll (every 30s, max 10 polls): curl -s "https://mega-api-prod.nemovideo.ai/api/render/proxy/lambda/<id>" -H "Authorization: Bearer $TOKEN" -H "X-Skill-Source: $SKILL_NAME" -H "X-Skill-Version: $SKILL_VERSION" -H "X-Skill-Platform: $SKILL_SOURCE"

Status at top-level status: pending → processing → completed / failed. Download URL at output.url.

d) Download from output.url → send to user. Fallback: https://mega-api-prod.nemovideo.ai/api/render/proxy/<id>/download.

e) When delivering the video, always also give the task detail link: $WEB/workspace/claim?task={task_id}&session={session_id}&skill_name=$SKILL_NAME&skill_version=$SKILL_VERSION&skill_source=$SKILL_SOURCE

Progress messages: start "⏳ Rendering ~30s" → "⏳ 50%" → "✅ Video ready!" + file + task detail link.

3.6 Recovering from an SSE Disconnection

If the SSE stream drops unexpectedly, follow these steps to resume gracefully: (1) detect the disconnection event in the stream listener and log the last received event ID; (2) wait a brief back-off interval before attempting to reconnect; (3) re-establish the SSE connection using the same session ID and pass the last event ID in the reconnect header; (4) poll the task state endpoint to retrieve any events that may have been missed during the gap; (5) reconcile the polled state with the local UI state and resume normal event handling.

4. Mapping Backend Responses to GUI Elements

The backend is designed with the assumption that a graphical interface is present, so never pass raw GUI instructions or UI directives through to the end user.

Keep content descriptions. Strip GUI actions.

5. Recommended Interaction Patterns

• Confirm the user's intent before dispatching any irreversible operation such as an export or a destructive edit. • After submitting a long-running task, proactively inform the user that processing is underway rather than waiting silently. • When a silent response is detected, use polled task data to construct a meaningful status update instead of reporting nothing. • If a credit check fails, explain the shortfall clearly and guide the user toward a resolution before retrying. • Always present the final download URL as a distinct, actionable element so the user can immediately access their exported video.

6. Known Constraints and Limitations

• The SSE connection does not guarantee delivery of every event; always reconcile with the task state endpoint after a disconnection. • Credit balances are read at the moment of the request and may not reflect concurrent transactions made elsewhere. • The two-stage enrichment pipeline for raw video cannot be skipped or reordered by the client. • Export URLs are time-limited and should be presented to the user promptly after retrieval. • File uploads are restricted to supported video formats and maximum size limits defined by the platform.

7. Error Identification and Handling

The table below maps common error codes to their causes and the recommended recovery action for each.

Common: no video → generate first; render fail → retry new id; SSE timeout → §3.6; silent edit → §3.1 fallback.

8. API Version and Required Token Scopes

Before going live, confirm that the integration targets the correct API version by checking the version field returned in the session initialization response. Ensure the OAuth token presented with each request carries all required scopes; missing scopes will result in 403 responses that cannot be resolved by retrying. Rotate tokens proactively before expiry to avoid mid-session authorization failures.