Proofread

Sonilo Proofread

Transcribe a video and translate the transcript into the target languages, returning one editable .srt per language plus the source-language transcript. Nothing is voiced, nothing is re-rendered, no video comes back.

This is the step before auto-dubbing: the user reads and corrects the translated scripts, and the corrected files then go to dubbing as subtitles, so the dub speaks exactly the approved wording instead of the pipeline's own translation.

Setup: See the setup-api-key skill.

⚠️ Cost — read before calling: this is billed per target language — video seconds × the number of target languages, at $0.001/sec with a 10-second billing floor. A transcript-only request (no languages) counts as one. Self-serve accounts get 2 free-trial runs; after that it bills normally. Confirm the exact language list with the user before calling; do not guess a long list "to be helpful."

When to reach for this

Use it when:

• The user wants to see or fix the translation before it is spoken. "Let me check the Spanish first", "our team has to approve the copy", "the product name keeps getting mangled" — all of it is this call, not a dub followed by a re-dub.
• The user wants editable subtitles or a plain transcript of a video, with no dubbing in sight. Omit languages for the source-language transcript alone.
• A previous dub said the wrong thing. Proofread, correct the script, then dub with subtitles. Re-dubbing without a script just pays for the same translation twice.

Do not use it when the user just wants the video dubbed and has no interest in the wording — that is one dubbing call, and inserting a proofread in front of it is an extra charge they did not ask for.

Transport: MCP or CLI

Pick one at the start of the session and stay on it. Do not mix the two inside a single job, and do not announce the choice.

1. Sonilo MCP tools visible in this session (proofread and friends) — use them. This is the preferred path: it needs no shell, and it is the only one that survives a very long generation. If a call fails to authenticate — rather than failing on its inputs — this transport is not usable in this session: go to 2 instead of retrying it.
2. No usable Sonilo MCP tools, but sonilo account exits 0 — use the CLI commands below. Same API, same account, same credential file. Probe with sonilo account, not sonilo whoami: whoami exits 0 even when signed out, so it cannot tell the two states apart.
3. Neither — stop and run the setup-api-key skill. Do not call api.sonilo.com with curl to work around it; both transports handle uploads, polling and retries that a bare request does not.

One difference between the two MCP servers

proofread takes a local file only on the local server. The hosted (OAuth plugin) server is URL-only: it exposes video_url, languages and source_language and nothing else — no video_path to read a file from, and no output_directory, because it has no filesystem. There the .srt URLs come back on the task and you fetch them yourself. If the user's video is a local file and you are on the hosted server, use the CLI or an SDK instead of trying video_path — it is not a parameter there.

Unlike dubbing, this call is quick: a few-minute clip with a handful of languages typically finishes in well under a minute, so the ordinary timeout is enough and there is no submit-and-poll dance to plan for.

Quick Start

MCP tool call (recommended)

proofread(
    video_path="~/Desktop/product-demo.mp4",
    languages=["es", "fr"]
)

On the hosted server, pass a URL instead — it is the only input there:

proofread(video_url="https://example.com/product-demo.mp4", languages=["es", "fr"])

The transcript alone, with no translation, is the same call with languages left out:

proofread(video_path="~/Desktop/product-demo.mp4")

A hint for the spoken language, for short or noisy audio:

proofread(video_path="~/Desktop/product-demo.mp4", languages=["es"], source_language="en")

On the local server the files are saved for you (see Output Files); output_directory says where.

Python (pip install sonilo)

from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

result = client.proofread.generate(
    video="product-demo.mp4",
    languages=["es", "fr"],
    # Optional hint; omit to have the spoken language detected.
    source_language="en",
)
print(result.source_language, result.cue_count)

# Writes scripts/proofread.<language>.srt — including the source language.
for language, path in result.save_all("./scripts").items():
    print(language, path)

for language, issues in result.warnings.items():
    for issue in issues:
        print(language, issue.cue, issue.code, issue.severity)

JavaScript / TypeScript (npm install sonilo)

import { SoniloClient } from "sonilo";
import type { ProofreadResult } from "sonilo";

const client = new SoniloClient(); // reads SONILO_API_KEY

const result: ProofreadResult = await client.proofread.generate({
  video: "./product-demo.mp4",
  languages: ["es", "fr"],
  sourceLanguage: "en", // optional hint
});
console.log(result.source_language, result.cue_count);

// Presigned .srt URLs — they expire, so fetch them promptly. There are no
// download helpers on this result; use download()/fetch() as elsewhere.
for (const [language, url] of Object.entries(result.subtitles ?? {})) {
  console.log(language, url);
}

CLI (npm install -g sonilo-cli or pip install sonilo-cli)

sonilo proofread --video clip.mp4 --languages es,fr --output scripts/clip.srt
# writes scripts/clip.en.srt (the detected source), scripts/clip.es.srt, scripts/clip.fr.srt

--output is a filename template, not one destination, exactly as it is on sonilo dubbing: the language code is spliced in before the extension, and missing directories are created. It defaults to proofread.srt. After the files, the command prints the detected source language, the cue count, and one line per non-blocking warning.

# Transcript only, from a URL, with a hint for the spoken language.
sonilo proofread --video-url https://example.com/clip.mp4 --source-language en

# --timeout is the CLI's own wait (default 600 seconds). If it does expire, the
# task keeps running server-side.
sonilo proofread --video clip.mp4 --languages ja --timeout 300
sonilo tasks wait <task-id>

cURL (raw REST API, no MCP host)

curl -X POST "https://api.sonilo.com/v1/proofread" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "video=@product-demo.mp4" \
  -F 'languages=["es","fr"]' \
  -F "source_language=en"
# -> 202 {"task_id": "...", "status": "processing"}

curl "https://api.sonilo.com/v1/tasks/<task_id>" -H "Authorization: Bearer $SONILO_API_KEY"

languages is a JSON array string, the same wire shape as dubbing's. video_url is accepted instead of an uploaded file and must be https — the backend fetches the source itself and rejects plain http. Pass one or the other, never both.

Tool

Parameters

What comes back

{
  "task_id": "…",
  "status": "succeeded",
  "source_language": "en",
  "subtitles": {
    "en": "https://…/en.srt",
    "es": "https://…/es.srt",
    "fr": "https://…/fr.srt"
  },
  "cue_count": 65,
  "warnings": {
    "fr": [
      {"cue": 33, "code": "high_text_speed", "severity": "warning", "characters_per_second": 26.92}
    ]
  },
  "duration_seconds": 206.32
}

• subtitles maps a language code to a downloadable .srt URL, and always includes the detected source language on top of every requested target — so a one-language request comes back with two files, and a request with no languages at all still comes back with one. The URLs are presigned and expire: save the files rather than handing the user a link.
• source_language is the language the transcript is in, whatever hint was sent. It is the key the source-language file appears under.
• cue_count is the number of subtitle cues in the source script. Every language has the same count.
• warnings maps a language to non-blocking issues in its script, and is empty when there are none. Each issue carries cue (1-based), code, severity, plus whatever measurement that code brought with it (e.g. characters_per_second on high_text_speed). A warning never withholds a file or fails the task — surface it as something the user may want to tighten while editing, not as an error.