sonilo 0.15.0 → 0.16.1

package/README.md

@@ -127,6 +127,53 @@ if (result.ducked) {
 }
 ```
 
+### Stems (async)
+
+Set `stems: true` to also split the generated track into four separated
+stems — `drums`, `bass`, `vocals`, `other`. It is **free of charge**, and
+available on `textToMusic` and `videoToMusic`. It requires the async task API
+(`mode: "async"` — the backend rejects it on the plain stream with a 400), so
+it is only meaningful via `submit()`; on `videoToMusic` it splits the
+**generated** music, never the source video's own audio.
+
+When separation succeeds, the result gains a `stems` array with one entry per
+stream: `{ stream_index, drums, bass, vocals, other }`, each stem an ordinary
+media object (`url`, `content_type`, `file_size`) you can pass to
+`download()`. **Look entries up by `stream_index`, never by array position** —
+`stems` carries only the streams that separated successfully, so it can be
+shorter than `audio`.
+
+Failures land in `stems_error`, a string present when separation failed wholly
+or in part, or was skipped. It can appear **alongside a partial `stems`
+array**, so never treat it as "no stems" — check `stems` itself for what did
+arrive. Either way the generated `audio` is unaffected.
+
+Separation runs after generation and typically adds 2-6 minutes to the wait
+(it gives up after 30), so raise `tasks.wait`'s `timeout` beyond the 10-minute
+default. The stems normally follow the request's `outputFormat`; each stem's
+own `content_type` reports what was actually delivered.
+
+```ts
+const task = await client.textToMusic.submit({
+  prompt: "warm lo-fi piano",
+  duration: 30,
+  stems: true, // free — adds drums/bass/vocals/other alongside the mix
+});
+const result = await client.tasks.wait<MusicTaskResult>(task.task_id, {
+  timeout: 2_400_000, // separation can add up to 30 minutes
+});
+
+if (result.stems_error) console.warn(result.stems_error); // may be partial
+for (const track of result.audio ?? []) {
+  const split = result.stems?.find((s) => s.stream_index === track.stream_index);
+  if (!split) continue; // this stream did not separate — see stems_error
+  await writeFile("drums.m4a", await download(split.drums));
+  await writeFile("bass.m4a", await download(split.bass));
+  await writeFile("vocals.m4a", await download(split.vocals));
+  await writeFile("other.m4a", await download(split.other));
+}
+```
+
 ### Variants (async)
 
 `variantsNum` generates several distinct music variants in one request (1-10,
@@ -329,7 +376,7 @@ 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.
 
-Dubbing is async-only, and the source video may be at most 180 seconds long.
+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
 [Free trial](#free-trial)).

package/dist/index.cjs

@@ -347,8 +347,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";
@@ -368,6 +368,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
@@ -451,9 +454,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)) {
@@ -463,11 +466,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();
@@ -497,6 +500,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));
     }
@@ -825,7 +831,7 @@ var VideoAnalysis = class {
 };
 
 // src/version.ts
-var VERSION = "0.15.0";
+var VERSION = "0.16.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";