sonilo 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -51,10 +51,13 @@ interface TextToMusicParams {
     prompt: string;
     duration: number;
     segments?: Segment[];
-    /** "stream" (default) or "async" (required by `submit()` and `output_format: "wav"`). */
+    /** "stream" (default) or "async" (required by `submit()` and by any
+     * `outputFormat` other than the m4a default). */
     mode?: "stream" | "async";
-    /** Container for the async result. `wav` requires `mode: "async"`. Defaults to m4a server-side. */
-    outputFormat?: "m4a" | "wav";
+    /** Container for the async result. `wav` and `mp3` (320 kbps) are
+     * finalize-time transcodes and require `mode: "async"`; m4a is what the
+     * stream itself carries. Defaults to m4a server-side. */
+    outputFormat?: "m4a" | "wav" | "mp3";
     /** How many distinct music variants to generate in one request (1-10,
      * default 1). Cost scales linearly, and values above 1 are never covered
      * by the free trial. Values above 1 require `mode: "async"` — only
@@ -93,8 +96,9 @@ interface VideoToMusicParams {
      * `isolateVocals`; both are accepted and OR'd server-side. Requires
      * `mode: "async"` (auto-selected by `submit()`). */
     preserveSpeech?: boolean;
-    /** Container for the async result. `wav` requires async. Defaults to m4a. */
-    outputFormat?: "m4a" | "wav";
+    /** Container for the async result. `wav` and `mp3` (320 kbps) are
+     * finalize-time transcodes and require async. Defaults to m4a. */
+    outputFormat?: "m4a" | "wav" | "mp3";
     /** Duck the generated music under the source voice at finalize time.
      * Default-ON server-side in async mode: leave unset to keep it on, pass
      * `false` to opt out. Free, best-effort; only valid on `submit()`. */
@@ -269,10 +273,35 @@ interface VideoResult extends BaseTaskResult {
     video?: SfxMedia;
     duration_seconds?: number;
 }
+/** Params for `videoToVideoMusic`.
+ *
+ * The delivered video's audio depends on `ducking` and `preserveSpeech`:
+ *
+ * | Request | Audio in the returned video |
+ * | --- | --- |
+ * | neither set | source speech + music ducked under it |
+ * | `ducking: false` | music only |
+ * | `preserveSpeech: true` | isolated vocals + music ducked under them |
+ * | both (`ducking: false`) | static vocal-forward mix of vocals + music |
+ *
+ * The source picture is copied without re-encoding, so the input must carry
+ * H.264, H.265/HEVC, VP9 or AV1 video in an mp4, mov, m4v or webm container —
+ * animated gif and VP8 webm are rejected. Maximum input duration is 360
+ * seconds. */
 interface VideoToVideoMusicParams {
     video?: VideoInput;
     videoUrl?: string;
     prompt?: string;
+    /** How the music should develop over time. Same shape as
+     * `videoToMusic`'s: the first `start` must be 0. Supplying these skips the
+     * prompt-service plan the server would otherwise derive from `prompt`. */
+    segments?: Segment[];
+    /** Duck the generated music under the source's speech — or, with
+     * `preserveSpeech`, under the isolated vocals. Default-ON server-side:
+     * leave unset to keep it on, pass `false` for music-only audio. Free and
+     * best-effort; silently falls back to music-only if the source has no
+     * usable audio track, voice isolation fails, or the duck mix fails. */
+    ducking?: boolean;
     /** Keep the source speech/vocals in the output. Both this and the legacy
      * `isolateVocals` are accepted and OR'd server-side. */
     preserveSpeech?: boolean;
@@ -290,9 +319,13 @@ interface VideoToVideoSfxParams {
     prompt?: string;
     segments?: SfxSegment[];
 }
-/** Params for `videoToSound` and `videoToVideoSound`. Both endpoints take the
- * identical form, so they share one params type. */
-interface VideoToSoundParams {
+/** Params for `videoToVideoSound`, and the base every `videoToSound` param
+ * also has. The two endpoints are identical except that only the audio one
+ * accepts `outputFormat` — `videoToVideoSound` always muxes the mix into an
+ * mp4 — so `VideoToSoundParams` extends this rather than the two sharing a
+ * single type, and passing `outputFormat` to the video endpoint is a
+ * compile error instead of a value the server silently ignores. */
+interface VideoToVideoSoundParams {
     video?: VideoInput;
     videoUrl?: string;
     /** Style hint for the generated music bed. */
@@ -313,6 +346,15 @@ interface VideoToSoundParams {
      * one entry per variant. */
     variantsNum?: number;
 }
+/** Params for `videoToSound`. Everything `videoToVideoSound` takes, plus the
+ * delivery container for the combined track. */
+interface VideoToSoundParams extends VideoToVideoSoundParams {
+    /** Container for the combined music + SFX track. Defaults to `wav`;
+     * `mp3` is 320 kbps. Applies to the combined output only — the `music`
+     * and `sfx` stems keep their native formats. Not available on
+     * `videoToVideoSound`, which always returns an mp4. */
+    outputFormat?: "wav" | "m4a" | "mp3";
+}
 /** One variant's outputs on a `videoToSound` / `videoToVideoSound` result.
  * Present even at the default `variantsNum` of 1, as a single-entry array. */
 interface SoundOutputEntry {
@@ -365,6 +407,12 @@ interface DubbingParams {
     videoUrl?: string;
     /** Omit to get the server default, `["zh_cn", "es", "fr"]`. */
     languages?: DubbingLanguage[];
+    /**
+     * Duck the background music/effects bed under the dubbed voice. Default
+     * OFF server-side (the opposite of video-to-music's `ducking`): the bed
+     * is always kept, at a constant level unless this is `true`. Free.
+     */
+    ducking?: boolean;
 }
 interface DubbingResult extends BaseTaskResult {
     /**
@@ -415,7 +463,7 @@ declare class TextToMusic {
     /**
      * Submit an async text-to-music task; poll with
      * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-     * `outputFormat: "wav"` and `variantsNum` above 1. `stream()`/`generate()`
+     * a non-m4a `outputFormat` and `variantsNum` above 1. `stream()`/`generate()`
      * remain the streaming path.
      */
     submit(params: TextToMusicParams): Promise<SfxTask>;
@@ -429,7 +477,7 @@ declare class VideoToMusic {
     /**
      * Submit an async video-to-music task; poll its result with
      * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-     * `isolateVocals`/`preserveSpeech`, `outputFormat: "wav"`, and
+     * `isolateVocals`/`preserveSpeech`, a non-m4a `outputFormat`, and
      * `variantsNum` above 1 — the backend rejects all of these on the plain
      * stream, and they only ever run in async mode.
      */
@@ -483,8 +531,8 @@ declare class VideoToSound {
 declare class VideoToVideoSound {
     private readonly client;
     constructor(client: SoniloClient);
-    submit(params: VideoToSoundParams): Promise<SfxTask>;
-    generate(params: VideoToSoundParams, opts?: WaitOptions): Promise<SoundResult>;
+    submit(params: VideoToVideoSoundParams): Promise<SfxTask>;
+    generate(params: VideoToVideoSoundParams, opts?: WaitOptions): Promise<SoundResult>;
 }
 
 /** Dub a video into one or more target languages. Async only; the result
@@ -615,6 +663,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.8.0";
+declare const VERSION = "0.10.0";
 
-export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, 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 StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, 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 StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, 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

@@ -51,10 +51,13 @@ interface TextToMusicParams {
     prompt: string;
     duration: number;
     segments?: Segment[];
-    /** "stream" (default) or "async" (required by `submit()` and `output_format: "wav"`). */
+    /** "stream" (default) or "async" (required by `submit()` and by any
+     * `outputFormat` other than the m4a default). */
     mode?: "stream" | "async";
-    /** Container for the async result. `wav` requires `mode: "async"`. Defaults to m4a server-side. */
-    outputFormat?: "m4a" | "wav";
+    /** Container for the async result. `wav` and `mp3` (320 kbps) are
+     * finalize-time transcodes and require `mode: "async"`; m4a is what the
+     * stream itself carries. Defaults to m4a server-side. */
+    outputFormat?: "m4a" | "wav" | "mp3";
     /** How many distinct music variants to generate in one request (1-10,
      * default 1). Cost scales linearly, and values above 1 are never covered
      * by the free trial. Values above 1 require `mode: "async"` — only
@@ -93,8 +96,9 @@ interface VideoToMusicParams {
      * `isolateVocals`; both are accepted and OR'd server-side. Requires
      * `mode: "async"` (auto-selected by `submit()`). */
     preserveSpeech?: boolean;
-    /** Container for the async result. `wav` requires async. Defaults to m4a. */
-    outputFormat?: "m4a" | "wav";
+    /** Container for the async result. `wav` and `mp3` (320 kbps) are
+     * finalize-time transcodes and require async. Defaults to m4a. */
+    outputFormat?: "m4a" | "wav" | "mp3";
     /** Duck the generated music under the source voice at finalize time.
      * Default-ON server-side in async mode: leave unset to keep it on, pass
      * `false` to opt out. Free, best-effort; only valid on `submit()`. */
@@ -269,10 +273,35 @@ interface VideoResult extends BaseTaskResult {
     video?: SfxMedia;
     duration_seconds?: number;
 }
+/** Params for `videoToVideoMusic`.
+ *
+ * The delivered video's audio depends on `ducking` and `preserveSpeech`:
+ *
+ * | Request | Audio in the returned video |
+ * | --- | --- |
+ * | neither set | source speech + music ducked under it |
+ * | `ducking: false` | music only |
+ * | `preserveSpeech: true` | isolated vocals + music ducked under them |
+ * | both (`ducking: false`) | static vocal-forward mix of vocals + music |
+ *
+ * The source picture is copied without re-encoding, so the input must carry
+ * H.264, H.265/HEVC, VP9 or AV1 video in an mp4, mov, m4v or webm container —
+ * animated gif and VP8 webm are rejected. Maximum input duration is 360
+ * seconds. */
 interface VideoToVideoMusicParams {
     video?: VideoInput;
     videoUrl?: string;
     prompt?: string;
+    /** How the music should develop over time. Same shape as
+     * `videoToMusic`'s: the first `start` must be 0. Supplying these skips the
+     * prompt-service plan the server would otherwise derive from `prompt`. */
+    segments?: Segment[];
+    /** Duck the generated music under the source's speech — or, with
+     * `preserveSpeech`, under the isolated vocals. Default-ON server-side:
+     * leave unset to keep it on, pass `false` for music-only audio. Free and
+     * best-effort; silently falls back to music-only if the source has no
+     * usable audio track, voice isolation fails, or the duck mix fails. */
+    ducking?: boolean;
     /** Keep the source speech/vocals in the output. Both this and the legacy
      * `isolateVocals` are accepted and OR'd server-side. */
     preserveSpeech?: boolean;
@@ -290,9 +319,13 @@ interface VideoToVideoSfxParams {
     prompt?: string;
     segments?: SfxSegment[];
 }
-/** Params for `videoToSound` and `videoToVideoSound`. Both endpoints take the
- * identical form, so they share one params type. */
-interface VideoToSoundParams {
+/** Params for `videoToVideoSound`, and the base every `videoToSound` param
+ * also has. The two endpoints are identical except that only the audio one
+ * accepts `outputFormat` — `videoToVideoSound` always muxes the mix into an
+ * mp4 — so `VideoToSoundParams` extends this rather than the two sharing a
+ * single type, and passing `outputFormat` to the video endpoint is a
+ * compile error instead of a value the server silently ignores. */
+interface VideoToVideoSoundParams {
     video?: VideoInput;
     videoUrl?: string;
     /** Style hint for the generated music bed. */
@@ -313,6 +346,15 @@ interface VideoToSoundParams {
      * one entry per variant. */
     variantsNum?: number;
 }
+/** Params for `videoToSound`. Everything `videoToVideoSound` takes, plus the
+ * delivery container for the combined track. */
+interface VideoToSoundParams extends VideoToVideoSoundParams {
+    /** Container for the combined music + SFX track. Defaults to `wav`;
+     * `mp3` is 320 kbps. Applies to the combined output only — the `music`
+     * and `sfx` stems keep their native formats. Not available on
+     * `videoToVideoSound`, which always returns an mp4. */
+    outputFormat?: "wav" | "m4a" | "mp3";
+}
 /** One variant's outputs on a `videoToSound` / `videoToVideoSound` result.
  * Present even at the default `variantsNum` of 1, as a single-entry array. */
 interface SoundOutputEntry {
@@ -365,6 +407,12 @@ interface DubbingParams {
     videoUrl?: string;
     /** Omit to get the server default, `["zh_cn", "es", "fr"]`. */
     languages?: DubbingLanguage[];
+    /**
+     * Duck the background music/effects bed under the dubbed voice. Default
+     * OFF server-side (the opposite of video-to-music's `ducking`): the bed
+     * is always kept, at a constant level unless this is `true`. Free.
+     */
+    ducking?: boolean;
 }
 interface DubbingResult extends BaseTaskResult {
     /**
@@ -415,7 +463,7 @@ declare class TextToMusic {
     /**
      * Submit an async text-to-music task; poll with
      * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-     * `outputFormat: "wav"` and `variantsNum` above 1. `stream()`/`generate()`
+     * a non-m4a `outputFormat` and `variantsNum` above 1. `stream()`/`generate()`
      * remain the streaming path.
      */
     submit(params: TextToMusicParams): Promise<SfxTask>;
@@ -429,7 +477,7 @@ declare class VideoToMusic {
     /**
      * Submit an async video-to-music task; poll its result with
      * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-     * `isolateVocals`/`preserveSpeech`, `outputFormat: "wav"`, and
+     * `isolateVocals`/`preserveSpeech`, a non-m4a `outputFormat`, and
      * `variantsNum` above 1 — the backend rejects all of these on the plain
      * stream, and they only ever run in async mode.
      */
@@ -483,8 +531,8 @@ declare class VideoToSound {
 declare class VideoToVideoSound {
     private readonly client;
     constructor(client: SoniloClient);
-    submit(params: VideoToSoundParams): Promise<SfxTask>;
-    generate(params: VideoToSoundParams, opts?: WaitOptions): Promise<SoundResult>;
+    submit(params: VideoToVideoSoundParams): Promise<SfxTask>;
+    generate(params: VideoToVideoSoundParams, opts?: WaitOptions): Promise<SoundResult>;
 }
 
 /** Dub a video into one or more target languages. Async only; the result
@@ -615,6 +663,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.8.0";
+declare const VERSION = "0.10.0";
 
-export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, 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 StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, 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 StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, 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

@@ -305,7 +305,7 @@ var TextToMusic = class {
   /**
    * Submit an async text-to-music task; poll with
    * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-   * `outputFormat: "wav"` and `variantsNum` above 1. `stream()`/`generate()`
+   * a non-m4a `outputFormat` and `variantsNum` above 1. `stream()`/`generate()`
    * remain the streaming path.
    */
   async submit(params) {
@@ -406,7 +406,7 @@ var VideoToMusic = class {
   /**
    * Submit an async video-to-music task; poll its result with
    * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-   * `isolateVocals`/`preserveSpeech`, `outputFormat: "wav"`, and
+   * `isolateVocals`/`preserveSpeech`, a non-m4a `outputFormat`, and
    * `variantsNum` above 1 — the backend rejects all of these on the plain
    * stream, and they only ever run in async mode.
    */
@@ -415,11 +415,14 @@ var VideoToMusic = class {
       throw new SoniloError("Provide exactly one of video or videoUrl");
     }
     let mode = params.mode;
-    const needsAsync = params.isolateVocals || params.preserveSpeech || params.ducking !== void 0 || params.outputFormat === "wav" || params.variantsNum !== void 0 && params.variantsNum > 1;
+    const needsAsync = params.isolateVocals || params.preserveSpeech || params.ducking !== void 0 || // Any non-m4a container is a finalize-time transcode, so it needs
+    // async. Checking != "m4a" rather than == "wav" keeps this correct
+    // as formats are added (mp3 landed after the original check).
+    params.outputFormat !== void 0 && params.outputFormat !== "m4a" || params.variantsNum !== void 0 && params.variantsNum > 1;
     if (mode === void 0) mode = "async";
     if (needsAsync && mode !== "async") {
       throw new SoniloError(
-        'isolateVocals/preserveSpeech/ducking/outputFormat "wav"/variantsNum > 1 require mode: "async"'
+        'isolateVocals/preserveSpeech/ducking/outputFormat other than "m4a"/variantsNum > 1 require mode: "async"'
       );
     }
     const form = new FormData();
@@ -529,6 +532,10 @@ var VideoToVideoMusic = class {
       form.set("video_url", params.videoUrl);
     }
     if (params.prompt !== void 0) form.set("prompt", params.prompt);
+    if (params.segments !== void 0) {
+      form.set("segments", JSON.stringify(params.segments));
+    }
+    if (params.ducking !== void 0) form.set("ducking", String(params.ducking));
     if (params.preserveSpeech !== void 0) {
       form.set("preserve_speech", String(params.preserveSpeech));
     }
@@ -603,6 +610,9 @@ async function buildSoundForm(params) {
     form.set("preserve_speech", String(params.preserveSpeech));
   }
   if (params.ducking !== void 0) form.set("ducking", String(params.ducking));
+  if (params.outputFormat !== void 0) {
+    form.set("output_format", params.outputFormat);
+  }
   if (params.variantsNum !== void 0) {
     form.set("variants_num", String(params.variantsNum));
   }
@@ -666,6 +676,9 @@ async function buildDubbingForm(params) {
   if (params.languages !== void 0) {
     form.set("languages", JSON.stringify(params.languages));
   }
+  if (params.ducking !== void 0) {
+    form.set("ducking", String(params.ducking));
+  }
   return form;
 }
 var Dubbing = class {
@@ -686,7 +699,7 @@ var Dubbing = class {
 };
 
 // src/version.ts
-var VERSION = "0.8.0";
+var VERSION = "0.10.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";