sonilo 0.16.5 → 0.18.0

package/README.md

@@ -379,6 +379,15 @@ boolean (default off, free) ducks the background music/effects bed under the
 dubbed voice while it speaks; when off the bed is kept at a constant level.
 Every endpoint's `ducking` is default-off, so this one is no exception.
 
+The optional `lipsync` boolean is the one parameter here that defaults **on**:
+the speaker's mouth is re-rendered to match the dubbed speech. Pass
+`lipsync: false` to leave the picture completely untouched instead — the video
+comes back at its original resolution and frame rate rather than re-rendered,
+and only the audio is replaced, so the mouths keep moving to the original
+language. Reach for it on footage with no on-camera speaker, or when
+preserving the exact original picture matters more than matching lip movement.
+The background bed is rebuilt either way, so `ducking` behaves the same.
+
 Dubbing is async-only, and the source video may be at most 300 seconds long.
 You are billed per language. Dubbing has **no free trial allowance** — unlike
 every other endpoint, every call bills from the first one (see
@@ -388,6 +397,56 @@ The result is a `DubbingResult`, whose `outputs` is a map of language code to
 dubbed `.mp4` URL — not the `audio`/`video`/`output_url` shape the other
 endpoints use.
 
+### Subtitle scripts
+
+`subtitles` supplies the lines to speak, one script per target language:
+
+```ts
+const result = await client.dubbing.generate(
+  {
+    videoUrl: "https://example.com/clip.mp4",
+    languages: ["ja", "es"],
+    subtitles: { ja: "./ja.srt", es: "https://example.com/es.vtt" },
+    exportSrt: true,
+  },
+  { timeout: 7_200_000 },
+);
+console.log(result.subtitles?.ja); // re-timed .srt URL
+```
+
+Rules:
+
+- These are **target-language** scripts, not source-language transcripts.
+- The keys must match `languages` exactly — a missing or extra code is a 422,
+  checked server-side before anything is charged.
+- A value starting with `https://` is a URL; any other string is a local file
+  path (Node.js only). A browser can pass a `File` instead. The filename must
+  end in `.srt` or `.vtt`, and an uploaded script is at most 1 MiB.
+- `exportSrt` requires `subtitles`. With it, each language's delivered audio is
+  force-aligned against its script and a re-timed SRT is returned under
+  `subtitles`, keeping your lines verbatim.
+
+`subtitle_preflight` (what the pipeline made of each script) and
+`subtitle_export` (how each re-timed SRT came out) are maps keyed by language.
+Their numeric fields — `cue_count`, `changes_count`, `alignment_loss` — are
+typed `number | string`, because a finished task carries them as strings; read
+them through `Number(...)`. `report_url` is `string | null` — the key is always
+written, so test the value, not the key. An export whose `status` is `blocked`
+does not fail the task: the dubbed videos are still delivered and `subtitles`
+simply lacks that language.
+
+`submit()` returns a `DubbingTask`: the shared `SfxTask` plus the
+acknowledgement's own `subtitle_preflight`. A `review_required` status there
+means the pipeline **changed lines in the script you submitted**, and
+`changes_count` says how many — worth checking without waiting for the dub:
+
+```ts
+const task = await client.dubbing.submit({ videoUrl, languages, subtitles });
+for (const [language, report] of Object.entries(task.subtitle_preflight ?? {})) {
+  if (report.status !== "ok") console.warn(language, report.status, report.issues);
+}
+```
+
 ## Video analysis
 
 `client.videoAnalysis` analyzes a video and returns a **creative brief** for

package/dist/index.cjs

@@ -756,6 +756,17 @@ var AudioDucking = class {
 };
 
 // src/resources/dubbing.ts
+var SUBTITLE_EXTENSIONS = [".srt", ".vtt"];
+async function toSubtitleBlob(language, value) {
+  const name = typeof value === "string" ? value : value?.name ?? "";
+  const lowered = name.toLowerCase();
+  if (!SUBTITLE_EXTENSIONS.some((ext) => lowered.endsWith(ext))) {
+    throw new SoniloError(
+      `subtitles[${language}]: "${name}" must be an .srt or .vtt file, or an https:// URL`
+    );
+  }
+  return toUploadBlob(value);
+}
 async function buildDubbingForm(params) {
   if (params.video === void 0 === (params.videoUrl === void 0)) {
     throw new SoniloError("Provide exactly one of video or videoUrl");
@@ -779,12 +790,37 @@ async function buildDubbingForm(params) {
   if (params.ducking !== void 0) {
     form.set("ducking", String(params.ducking));
   }
+  if (params.lipsync !== void 0) {
+    form.set("lipsync", String(params.lipsync));
+  }
+  if (params.subtitles !== void 0) {
+    for (const [language, value] of Object.entries(params.subtitles)) {
+      const field = `subtitles[${language}]`;
+      if (typeof value === "string" && value.toLowerCase().startsWith("https://")) {
+        form.set(field, value);
+        continue;
+      }
+      const { blob, filename } = await toSubtitleBlob(language, value);
+      form.set(field, blob, filename);
+    }
+  }
+  if (params.exportSrt !== void 0) {
+    if (params.exportSrt && Object.keys(params.subtitles ?? {}).length === 0) {
+      throw new SoniloError("exportSrt requires subtitles \u2014 there is nothing to align against");
+    }
+    form.set("export_srt", String(params.exportSrt));
+  }
   return form;
 }
 var Dubbing = class {
   constructor(client) {
     this.client = client;
   }
+  /** The acknowledgement carries `subtitle_preflight` when scripts were sent,
+   * which is why this returns `DubbingTask` rather than the shared `SfxTask`:
+   * a `review_required` preflight means the pipeline altered lines in the
+   * script that was submitted, and typing it away hides that from every
+   * caller who only ever sees the 202. */
   async submit(params) {
     const res = await this.client.request("/v1/dubbing", {
       method: "POST",
@@ -831,7 +867,7 @@ var VideoAnalysis = class {
 };
 
 // src/version.ts
-var VERSION = "0.16.5";
+var VERSION = "0.18.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";