sonilo 0.15.0 → 0.16.0

package/dist/index.d.cts

@@ -64,6 +64,16 @@ interface TextToMusicParams {
      * meaningful via `submit()`; `stream()`/`generate()` never send it, since
      * they always request a plain stream. */
     variantsNum?: number;
+    /** Also split the generated track into four separated stems — `drums`,
+     * `bass`, `vocals`, `other` — delivered on the task result's `stems`
+     * array. Free of charge. Requires `mode: "async"` (the backend rejects it
+     * on the plain stream with a 400), so it is only meaningful via
+     * `submit()`; `stream()`/`generate()` never send it. Separation runs after
+     * generation and typically adds 2-6 minutes to the wait (it gives up after
+     * 30), so raise `tasks.wait`'s `timeout` accordingly. See `StemsEntry` for
+     * the result shape, and `MusicTaskResult.stems_error` for how failures are
+     * reported. */
+    stems?: boolean;
     /** Bounds the stream: aborting this cancels the in-flight generation.
      * Passed straight through to `fetch` — it is never rewrapped as
      * RequestTimeoutError, since the client's own absolute timeout does not
@@ -118,6 +128,17 @@ interface VideoToMusicParams {
      * default applies; `0` is a meaningful value and is sent. Out-of-range
      * values are rejected server-side with a 422. */
     promptInfluence?: number;
+    /** Also split the generated music into four separated stems — `drums`,
+     * `bass`, `vocals`, `other` — delivered on the task result's `stems`
+     * array. It splits the GENERATED music, never the source video's own
+     * audio. Free of charge. Requires `mode: "async"` (auto-selected by
+     * `submit()`; the backend rejects it on the plain stream with a 400), so
+     * it is only meaningful via `submit()` — `stream()`/`generate()` never
+     * send it. Separation runs after generation and typically adds 2-6
+     * minutes to the wait (it gives up after 30), so raise `tasks.wait`'s
+     * `timeout` accordingly. See `StemsEntry` for the result shape, and
+     * `MusicTaskResult.stems_error` for how failures are reported. */
+    stems?: boolean;
 }
 /** One service's free-trial allowance. `remaining` is already floored at 0,
  * so it is safe to compare directly. */
@@ -244,6 +265,21 @@ interface MusicTitle {
     summary?: string;
     display_tags?: string[];
 }
+/** The four separated stems of one generated stream, present when the
+ * request set `stems: true`. Each stem is an ordinary media object
+ * (`url` / `content_type` / `file_size`), so any of them can be passed to
+ * `download()`. The stems normally follow the request's `outputFormat`;
+ * each stem's own `content_type` reports what was actually delivered. */
+interface StemsEntry {
+    /** Which `audio` entry this stems set belongs to. Match on this field,
+     * never on array position — `stems` carries only the streams that
+     * separated successfully, so it can be shorter than `audio`. */
+    stream_index: number;
+    drums: SfxMedia;
+    bass: SfxMedia;
+    vocals: SfxMedia;
+    other: SfxMedia;
+}
 /** State of an async video-to-music task (`tasks.get`) or its final result
  * (`tasks.wait<MusicTaskResult>()`). Only reachable via `videoToMusic.submit()`
  * with `mode: "async"`. */
@@ -259,6 +295,16 @@ interface MusicTaskResult extends BaseTaskResult {
     /** Music ducked under the source voice (per variant when `variantsNum` is
      * above 1); present only when `ducking` ran. */
     ducked?: MusicMediaEntry[];
+    /** Separated stems, one entry per stream that separated successfully;
+     * only appears when the request set `stems: true`. Look entries up by
+     * `stream_index`, never by array position — the array can be shorter than
+     * `audio` when separation failed for some streams (see `stems_error`). */
+    stems?: StemsEntry[];
+    /** Why stem separation failed wholly or in part, or was skipped. It can
+     * appear ALONGSIDE a partial `stems` array, so never treat its presence as
+     * "no stems" — check `stems` itself for what did arrive. Independent of
+     * the task's own `status`/`error`: the generation is intact either way. */
+    stems_error?: string;
     /** Variant 0's title — the top-level field always names the first variant,
      * even when `variantsNum` produced others with their own titles on
      * `audio[]`. */
@@ -596,8 +642,8 @@ declare class TextToMusic {
     /**
      * Submit an async text-to-music task; poll with
      * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-     * a non-m4a `outputFormat` and `variantsNum` above 1. `stream()`/`generate()`
-     * remain the streaming path.
+     * a non-m4a `outputFormat`, `variantsNum` above 1, and `stems`.
+     * `stream()`/`generate()` remain the streaming path.
      */
     submit(params: TextToMusicParams): Promise<SfxTask>;
 }
@@ -610,9 +656,9 @@ 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`, 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.
+     * `isolateVocals`/`preserveSpeech`, a non-m4a `outputFormat`,
+     * `variantsNum` above 1, and `stems` — the backend rejects all of these on
+     * the plain stream, and they only ever run in async mode.
      */
     submit(params: VideoToMusicParams): Promise<SfxTask>;
 }
@@ -835,6 +881,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.15.0";
+declare const VERSION = "0.16.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 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 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 };

package/dist/index.d.ts

@@ -64,6 +64,16 @@ interface TextToMusicParams {
      * meaningful via `submit()`; `stream()`/`generate()` never send it, since
      * they always request a plain stream. */
     variantsNum?: number;
+    /** Also split the generated track into four separated stems — `drums`,
+     * `bass`, `vocals`, `other` — delivered on the task result's `stems`
+     * array. Free of charge. Requires `mode: "async"` (the backend rejects it
+     * on the plain stream with a 400), so it is only meaningful via
+     * `submit()`; `stream()`/`generate()` never send it. Separation runs after
+     * generation and typically adds 2-6 minutes to the wait (it gives up after
+     * 30), so raise `tasks.wait`'s `timeout` accordingly. See `StemsEntry` for
+     * the result shape, and `MusicTaskResult.stems_error` for how failures are
+     * reported. */
+    stems?: boolean;
     /** Bounds the stream: aborting this cancels the in-flight generation.
      * Passed straight through to `fetch` — it is never rewrapped as
      * RequestTimeoutError, since the client's own absolute timeout does not
@@ -118,6 +128,17 @@ interface VideoToMusicParams {
      * default applies; `0` is a meaningful value and is sent. Out-of-range
      * values are rejected server-side with a 422. */
     promptInfluence?: number;
+    /** Also split the generated music into four separated stems — `drums`,
+     * `bass`, `vocals`, `other` — delivered on the task result's `stems`
+     * array. It splits the GENERATED music, never the source video's own
+     * audio. Free of charge. Requires `mode: "async"` (auto-selected by
+     * `submit()`; the backend rejects it on the plain stream with a 400), so
+     * it is only meaningful via `submit()` — `stream()`/`generate()` never
+     * send it. Separation runs after generation and typically adds 2-6
+     * minutes to the wait (it gives up after 30), so raise `tasks.wait`'s
+     * `timeout` accordingly. See `StemsEntry` for the result shape, and
+     * `MusicTaskResult.stems_error` for how failures are reported. */
+    stems?: boolean;
 }
 /** One service's free-trial allowance. `remaining` is already floored at 0,
  * so it is safe to compare directly. */
@@ -244,6 +265,21 @@ interface MusicTitle {
     summary?: string;
     display_tags?: string[];
 }
+/** The four separated stems of one generated stream, present when the
+ * request set `stems: true`. Each stem is an ordinary media object
+ * (`url` / `content_type` / `file_size`), so any of them can be passed to
+ * `download()`. The stems normally follow the request's `outputFormat`;
+ * each stem's own `content_type` reports what was actually delivered. */
+interface StemsEntry {
+    /** Which `audio` entry this stems set belongs to. Match on this field,
+     * never on array position — `stems` carries only the streams that
+     * separated successfully, so it can be shorter than `audio`. */
+    stream_index: number;
+    drums: SfxMedia;
+    bass: SfxMedia;
+    vocals: SfxMedia;
+    other: SfxMedia;
+}
 /** State of an async video-to-music task (`tasks.get`) or its final result
  * (`tasks.wait<MusicTaskResult>()`). Only reachable via `videoToMusic.submit()`
  * with `mode: "async"`. */
@@ -259,6 +295,16 @@ interface MusicTaskResult extends BaseTaskResult {
     /** Music ducked under the source voice (per variant when `variantsNum` is
      * above 1); present only when `ducking` ran. */
     ducked?: MusicMediaEntry[];
+    /** Separated stems, one entry per stream that separated successfully;
+     * only appears when the request set `stems: true`. Look entries up by
+     * `stream_index`, never by array position — the array can be shorter than
+     * `audio` when separation failed for some streams (see `stems_error`). */
+    stems?: StemsEntry[];
+    /** Why stem separation failed wholly or in part, or was skipped. It can
+     * appear ALONGSIDE a partial `stems` array, so never treat its presence as
+     * "no stems" — check `stems` itself for what did arrive. Independent of
+     * the task's own `status`/`error`: the generation is intact either way. */
+    stems_error?: string;
     /** Variant 0's title — the top-level field always names the first variant,
      * even when `variantsNum` produced others with their own titles on
      * `audio[]`. */
@@ -596,8 +642,8 @@ declare class TextToMusic {
     /**
      * Submit an async text-to-music task; poll with
      * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-     * a non-m4a `outputFormat` and `variantsNum` above 1. `stream()`/`generate()`
-     * remain the streaming path.
+     * a non-m4a `outputFormat`, `variantsNum` above 1, and `stems`.
+     * `stream()`/`generate()` remain the streaming path.
      */
     submit(params: TextToMusicParams): Promise<SfxTask>;
 }
@@ -610,9 +656,9 @@ 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`, 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.
+     * `isolateVocals`/`preserveSpeech`, a non-m4a `outputFormat`,
+     * `variantsNum` above 1, and `stems` — the backend rejects all of these on
+     * the plain stream, and they only ever run in async mode.
      */
     submit(params: VideoToMusicParams): Promise<SfxTask>;
 }
@@ -835,6 +881,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.15.0";
+declare const VERSION = "0.16.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 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 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 };

package/dist/index.js

@@ -305,8 +305,8 @@ var TextToMusic = class {
   /**
    * Submit an async text-to-music task; poll with
    * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
-   * a non-m4a `outputFormat` and `variantsNum` above 1. `stream()`/`generate()`
-   * remain the streaming path.
+   * a non-m4a `outputFormat`, `variantsNum` above 1, and `stems`.
+   * `stream()`/`generate()` remain the streaming path.
    */
   async submit(params) {
     const mode = params.mode ?? "async";
@@ -326,6 +326,9 @@ var TextToMusic = class {
     if (params.variantsNum !== void 0) {
       form.set("variants_num", String(params.variantsNum));
     }
+    if (params.stems !== void 0) {
+      form.set("stems", String(params.stems));
+    }
     const res = await this.client.request("/v1/text-to-music", {
       method: "POST",
       body: form
@@ -409,9 +412,9 @@ 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`, 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.
+   * `isolateVocals`/`preserveSpeech`, a non-m4a `outputFormat`,
+   * `variantsNum` above 1, and `stems` — the backend rejects all of these on
+   * the plain stream, and they only ever run in async mode.
    */
   async submit(params) {
     if (params.video === void 0 === (params.videoUrl === void 0)) {
@@ -421,11 +424,11 @@ var VideoToMusic = class {
     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;
+    params.outputFormat !== void 0 && params.outputFormat !== "m4a" || params.variantsNum !== void 0 && params.variantsNum > 1 || params.stems !== void 0;
     if (mode === void 0) mode = "async";
     if (needsAsync && mode !== "async") {
       throw new SoniloError(
-        'isolateVocals/preserveSpeech/ducking/outputFormat other than "m4a"/variantsNum > 1 require mode: "async"'
+        'isolateVocals/preserveSpeech/ducking/stems/outputFormat other than "m4a"/variantsNum > 1 require mode: "async"'
       );
     }
     const form = new FormData();
@@ -455,6 +458,9 @@ var VideoToMusic = class {
     if (params.variantsNum !== void 0) {
       form.set("variants_num", String(params.variantsNum));
     }
+    if (params.stems !== void 0) {
+      form.set("stems", String(params.stems));
+    }
     if (params.promptInfluence !== void 0) {
       form.set("prompt_influence", String(params.promptInfluence));
     }
@@ -783,7 +789,7 @@ var VideoAnalysis = class {
 };
 
 // src/version.ts
-var VERSION = "0.15.0";
+var VERSION = "0.16.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";