sonilo 0.17.0 → 0.18.0

package/dist/index.d.cts

@@ -538,6 +538,65 @@ type DubbingLanguage = "en" | "zh_cn" | "ja" | "ko" | "pt"
  | "es_419" | "de" | "fr" | "it" | "ru" | "th"
 /** Unqualified Arabic, not one of the country dialects. */
  | "ar" | "tr" | "vi" | "id" | (string & {});
+/**
+ * One target-language subtitle script for /v1/dubbing.
+ *
+ * A string starting with `https://` (case-insensitive) travels as a URL; any
+ * other string is a local file path (Node.js only), read and uploaded. The
+ * split is unambiguous — a real path cannot start with `https://` — and it
+ * matches how `video` already accepts a path string. A `File` is accepted for
+ * browsers, where paths do not exist; its `.name` supplies the filename.
+ *
+ * Blobs, byte arrays and streams are deliberately NOT accepted, unlike
+ * `VideoInput`: the server requires an uploaded part's filename to end in
+ * `.srt` or `.vtt`, and those types carry no name to derive one from.
+ */
+type SubtitleInput = string | File;
+/** One language's entry in the `subtitle_preflight` map: what the pipeline
+ * made of that script before anything was charged. The pipeline returns these
+ * numbers as strings on a finished task, so every numeric field is typed
+ * `number | string` — read them through `Number(...)`. */
+interface SubtitlePreflightReport {
+    /** `ok`, `review_required` or `blocked`. Open for values added later. */
+    status?: "ok" | "review_required" | "blocked" | (string & {});
+    cue_count?: number | string;
+    issues?: string[];
+    changes_count?: number | string;
+    /** `null`, not absent, when there is no report to link to: the key is
+     * always written. Test the value, never just the key's presence. */
+    report_url?: string | null;
+    [key: string]: unknown;
+}
+/** One language's entry in the `subtitle_export` map: how the re-timed SRT
+ * for that language came out. A `blocked` export does not fail the task — the
+ * dubbed videos are still delivered, and `subtitles` simply lacks that
+ * language. Numbers may arrive as strings, as in `SubtitlePreflightReport`. */
+interface SubtitleExportReport {
+    /** `exported`, `exported_review_required` or `blocked`. Open for values
+     * added later. */
+    status?: "exported" | "exported_review_required" | "blocked" | (string & {});
+    /** How far the re-timed cues drifted from the delivered audio during forced
+     * alignment. Lower is better. */
+    alignment_loss?: number | string;
+    issues?: string[];
+    error?: string;
+    /** `null`, not absent, when there is no report to link to: the key is
+     * always written. Test the value, never just the key's presence. */
+    report_url?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * The 202 acknowledgement from /v1/dubbing. Additive over the `SfxTask` every
+ * other endpoint returns — that shape is shared and stays untouched — because
+ * this one endpoint answers with a preflight report per submitted script.
+ *
+ * A `review_required` status here means the pipeline altered lines in the
+ * script that was submitted. It is the one moment a caller who never polls
+ * the task can still learn that, so it is worth surfacing.
+ */
+interface DubbingTask extends SfxTask {
+    subtitle_preflight?: Record<string, SubtitlePreflightReport>;
+}
 interface DubbingParams {
     /** Exactly one of `video` / `videoUrl`. */
     video?: VideoInput;
@@ -568,6 +627,24 @@ interface DubbingParams {
      * unaffected.
      */
     lipsync?: boolean;
+    /**
+     * One subtitle script per target language, keyed by language code:
+     * `{ ja: "./ja.srt", es: "https://example.com/es.vtt" }`.
+     *
+     * These are TARGET-language scripts carrying the lines you want spoken, not
+     * source-language transcripts. The key set must match `languages` exactly —
+     * that rule is enforced server-side, before anything is charged, and is
+     * deliberately not duplicated here: a local copy would also break a caller
+     * who relies on the server default `["zh_cn", "es", "fr"]` without passing
+     * `languages` at all.
+     */
+    subtitles?: Record<string, SubtitleInput>;
+    /**
+     * Return a re-timed SRT per language alongside the dubbed videos. Requires
+     * `subtitles`. The delivered audio of each language is force-aligned
+     * against that language's script, keeping its lines verbatim.
+     */
+    exportSrt?: boolean;
 }
 interface DubbingResult extends BaseTaskResult {
     /**
@@ -576,6 +653,15 @@ interface DubbingResult extends BaseTaskResult {
      * `video` slot — a dubbing task renders N artifacts, one per language.
      */
     outputs?: Record<string, string>;
+    /**
+     * One re-timed `.srt` URL per language. Only present when the request set
+     * `exportSrt`, and a language whose export was blocked is simply absent.
+     */
+    subtitles?: Record<string, string>;
+    /** What the pipeline made of each submitted script, keyed by language. */
+    subtitle_preflight?: Record<string, SubtitlePreflightReport>;
+    /** How each language's re-timed SRT came out, keyed by language. */
+    subtitle_export?: Record<string, SubtitleExportReport>;
 }
 interface VideoAnalysisParams {
     /** Exactly one of `video` / `videoUrl`. */
@@ -754,7 +840,12 @@ declare class AudioDucking {
 declare class Dubbing {
     private readonly client;
     constructor(client: SoniloClient);
-    submit(params: DubbingParams): Promise<SfxTask>;
+    /** 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. */
+    submit(params: DubbingParams): Promise<DubbingTask>;
     generate(params: DubbingParams, opts?: WaitOptions): Promise<DubbingResult>;
 }
 
@@ -901,6 +992,6 @@ declare class RequestTimeoutError extends SoniloError {
 declare function download(media: SfxMedia | string | undefined, fetchFn?: typeof globalThis.fetch, timeout?: number): Promise<Uint8Array>;
 
 /** The SDK's own version. Generated by scripts/sync-versions.mjs — do not edit. */
-declare const VERSION = "0.17.0";
+declare const VERSION = "0.18.0";
 
-export { APIError, type AccountServices, type AnalysisSegment, type AnalysisVariation, type AudioChunkEvent, type AudioDuckingParams, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, type DuckingResult, type ErrorEvent, GenerationError, type MusicMediaEntry, type MusicMuxEntry, type MusicTaskResult, type MusicTitle, PaymentRequiredError, RateLimitError, RequestTimeoutError, type Segment, type SegmentLabel, type SfxAudioFormat, type SfxError, type SfxMedia, type SfxResult, type SfxSegment, type SfxTask, SoniloClient, type SoniloClientOptions, SoniloError, type SoundOutputEntry, type SoundResult, type StemsEntry, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoAnalysisParams, type VideoAnalysisResult, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type VideoToVideoSoundParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AnalysisSegment, type AnalysisVariation, type AudioChunkEvent, type AudioDuckingParams, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, type DubbingTask, type DuckingResult, type ErrorEvent, GenerationError, type MusicMediaEntry, type MusicMuxEntry, type MusicTaskResult, type MusicTitle, PaymentRequiredError, RateLimitError, RequestTimeoutError, type Segment, type SegmentLabel, type SfxAudioFormat, type SfxError, type SfxMedia, type SfxResult, type SfxSegment, type SfxTask, SoniloClient, type SoniloClientOptions, SoniloError, type SoundOutputEntry, type SoundResult, type StemsEntry, type StreamEvent, type SubtitleExportReport, type SubtitleInput, type SubtitlePreflightReport, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoAnalysisParams, type VideoAnalysisResult, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type VideoToVideoSoundParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };

package/dist/index.d.ts

@@ -538,6 +538,65 @@ type DubbingLanguage = "en" | "zh_cn" | "ja" | "ko" | "pt"
  | "es_419" | "de" | "fr" | "it" | "ru" | "th"
 /** Unqualified Arabic, not one of the country dialects. */
  | "ar" | "tr" | "vi" | "id" | (string & {});
+/**
+ * One target-language subtitle script for /v1/dubbing.
+ *
+ * A string starting with `https://` (case-insensitive) travels as a URL; any
+ * other string is a local file path (Node.js only), read and uploaded. The
+ * split is unambiguous — a real path cannot start with `https://` — and it
+ * matches how `video` already accepts a path string. A `File` is accepted for
+ * browsers, where paths do not exist; its `.name` supplies the filename.
+ *
+ * Blobs, byte arrays and streams are deliberately NOT accepted, unlike
+ * `VideoInput`: the server requires an uploaded part's filename to end in
+ * `.srt` or `.vtt`, and those types carry no name to derive one from.
+ */
+type SubtitleInput = string | File;
+/** One language's entry in the `subtitle_preflight` map: what the pipeline
+ * made of that script before anything was charged. The pipeline returns these
+ * numbers as strings on a finished task, so every numeric field is typed
+ * `number | string` — read them through `Number(...)`. */
+interface SubtitlePreflightReport {
+    /** `ok`, `review_required` or `blocked`. Open for values added later. */
+    status?: "ok" | "review_required" | "blocked" | (string & {});
+    cue_count?: number | string;
+    issues?: string[];
+    changes_count?: number | string;
+    /** `null`, not absent, when there is no report to link to: the key is
+     * always written. Test the value, never just the key's presence. */
+    report_url?: string | null;
+    [key: string]: unknown;
+}
+/** One language's entry in the `subtitle_export` map: how the re-timed SRT
+ * for that language came out. A `blocked` export does not fail the task — the
+ * dubbed videos are still delivered, and `subtitles` simply lacks that
+ * language. Numbers may arrive as strings, as in `SubtitlePreflightReport`. */
+interface SubtitleExportReport {
+    /** `exported`, `exported_review_required` or `blocked`. Open for values
+     * added later. */
+    status?: "exported" | "exported_review_required" | "blocked" | (string & {});
+    /** How far the re-timed cues drifted from the delivered audio during forced
+     * alignment. Lower is better. */
+    alignment_loss?: number | string;
+    issues?: string[];
+    error?: string;
+    /** `null`, not absent, when there is no report to link to: the key is
+     * always written. Test the value, never just the key's presence. */
+    report_url?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * The 202 acknowledgement from /v1/dubbing. Additive over the `SfxTask` every
+ * other endpoint returns — that shape is shared and stays untouched — because
+ * this one endpoint answers with a preflight report per submitted script.
+ *
+ * A `review_required` status here means the pipeline altered lines in the
+ * script that was submitted. It is the one moment a caller who never polls
+ * the task can still learn that, so it is worth surfacing.
+ */
+interface DubbingTask extends SfxTask {
+    subtitle_preflight?: Record<string, SubtitlePreflightReport>;
+}
 interface DubbingParams {
     /** Exactly one of `video` / `videoUrl`. */
     video?: VideoInput;
@@ -568,6 +627,24 @@ interface DubbingParams {
      * unaffected.
      */
     lipsync?: boolean;
+    /**
+     * One subtitle script per target language, keyed by language code:
+     * `{ ja: "./ja.srt", es: "https://example.com/es.vtt" }`.
+     *
+     * These are TARGET-language scripts carrying the lines you want spoken, not
+     * source-language transcripts. The key set must match `languages` exactly —
+     * that rule is enforced server-side, before anything is charged, and is
+     * deliberately not duplicated here: a local copy would also break a caller
+     * who relies on the server default `["zh_cn", "es", "fr"]` without passing
+     * `languages` at all.
+     */
+    subtitles?: Record<string, SubtitleInput>;
+    /**
+     * Return a re-timed SRT per language alongside the dubbed videos. Requires
+     * `subtitles`. The delivered audio of each language is force-aligned
+     * against that language's script, keeping its lines verbatim.
+     */
+    exportSrt?: boolean;
 }
 interface DubbingResult extends BaseTaskResult {
     /**
@@ -576,6 +653,15 @@ interface DubbingResult extends BaseTaskResult {
      * `video` slot — a dubbing task renders N artifacts, one per language.
      */
     outputs?: Record<string, string>;
+    /**
+     * One re-timed `.srt` URL per language. Only present when the request set
+     * `exportSrt`, and a language whose export was blocked is simply absent.
+     */
+    subtitles?: Record<string, string>;
+    /** What the pipeline made of each submitted script, keyed by language. */
+    subtitle_preflight?: Record<string, SubtitlePreflightReport>;
+    /** How each language's re-timed SRT came out, keyed by language. */
+    subtitle_export?: Record<string, SubtitleExportReport>;
 }
 interface VideoAnalysisParams {
     /** Exactly one of `video` / `videoUrl`. */
@@ -754,7 +840,12 @@ declare class AudioDucking {
 declare class Dubbing {
     private readonly client;
     constructor(client: SoniloClient);
-    submit(params: DubbingParams): Promise<SfxTask>;
+    /** 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. */
+    submit(params: DubbingParams): Promise<DubbingTask>;
     generate(params: DubbingParams, opts?: WaitOptions): Promise<DubbingResult>;
 }
 
@@ -901,6 +992,6 @@ declare class RequestTimeoutError extends SoniloError {
 declare function download(media: SfxMedia | string | undefined, fetchFn?: typeof globalThis.fetch, timeout?: number): Promise<Uint8Array>;
 
 /** The SDK's own version. Generated by scripts/sync-versions.mjs — do not edit. */
-declare const VERSION = "0.17.0";
+declare const VERSION = "0.18.0";
 
-export { APIError, type AccountServices, type AnalysisSegment, type AnalysisVariation, type AudioChunkEvent, type AudioDuckingParams, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, type DuckingResult, type ErrorEvent, GenerationError, type MusicMediaEntry, type MusicMuxEntry, type MusicTaskResult, type MusicTitle, PaymentRequiredError, RateLimitError, RequestTimeoutError, type Segment, type SegmentLabel, type SfxAudioFormat, type SfxError, type SfxMedia, type SfxResult, type SfxSegment, type SfxTask, SoniloClient, type SoniloClientOptions, SoniloError, type SoundOutputEntry, type SoundResult, type StemsEntry, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoAnalysisParams, type VideoAnalysisResult, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type VideoToVideoSoundParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AnalysisSegment, type AnalysisVariation, type AudioChunkEvent, type AudioDuckingParams, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, type DubbingTask, type DuckingResult, type ErrorEvent, GenerationError, type MusicMediaEntry, type MusicMuxEntry, type MusicTaskResult, type MusicTitle, PaymentRequiredError, RateLimitError, RequestTimeoutError, type Segment, type SegmentLabel, type SfxAudioFormat, type SfxError, type SfxMedia, type SfxResult, type SfxSegment, type SfxTask, SoniloClient, type SoniloClientOptions, SoniloError, type SoundOutputEntry, type SoundResult, type StemsEntry, type StreamEvent, type SubtitleExportReport, type SubtitleInput, type SubtitlePreflightReport, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoAnalysisParams, type VideoAnalysisResult, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type VideoToVideoSoundParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };

package/dist/index.js

@@ -714,6 +714,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");
@@ -740,12 +751,34 @@ async function buildDubbingForm(params) {
   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",
@@ -792,7 +825,7 @@ var VideoAnalysis = class {
 };
 
 // src/version.ts
-var VERSION = "0.17.0";
+var VERSION = "0.18.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";