sonilo 0.14.0 → 0.16.0

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,
@@ -338,6 +385,47 @@ 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.
 
+## Video analysis
+
+`client.videoAnalysis` analyzes a video and returns a **creative brief** for
+scoring it. Nothing is generated: no audio, no video, no file to download.
+The result is the work order — a time-aligned `segments` plan plus one
+`prompt` per requested variation, each ready to hand straight to
+`videoToMusic`, `videoToSfx`, `videoToSound` or their video-to-video
+counterparts.
+
+Pass exactly one of `video` / `videoUrl`, plus optional `prompt` (guidance
+for the analysis, at most 2000 characters) and `variantsNum` (1-5, default
+1 — billed per brief). Source videos may be at most 600 seconds long, and
+billing has a 10-second floor, so a very short clip still costs the same as a
+10-second one.
+
+```ts
+const brief = await client.videoAnalysis.analyze({
+  video: "trailer.mp4",
+  prompt: "focus on the chase",
+  variantsNum: 2,
+});
+
+for (const segment of brief.segments ?? []) {
+  console.log(`${segment.start}-${segment.end}s [${segment.label}] ${segment.prompt}`);
+}
+
+// Feed a variation's prompt straight into a generation call.
+const task = await client.videoToMusic.submit({
+  video: "trailer.mp4",
+  prompt: brief.variations![0]!.prompt,
+});
+```
+
+The method is `analyze`, not `generate`, for the same reason there is no
+download helper on the result: every other resource returns something you
+save, and this one never does. Both `segments` and `variations` are optional
+on the type because a `processing` or `failed` poll carries neither. Use
+`submit()` instead of `analyze()` to get a `task_id` back immediately and
+poll it yourself with
+`client.tasks.wait<VideoAnalysisResult>(taskId)`.
+
 ## Configuration
 
 ```ts
@@ -426,7 +514,7 @@ endpoints — no card required:
 
 | Free runs | Endpoints |
 | --- | --- |
-| 2 each | text-to-music, text-to-sfx, audio-ducking |
+| 2 each | text-to-music, text-to-sfx, audio-ducking, video-analysis |
 | 1 each | video-to-music, video-to-sfx, video-to-video-music, video-to-video-sfx, video-to-sound, video-to-video-sound |
 | 0 | dubbing |
 

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));
     }
@@ -792,8 +798,40 @@ var Dubbing = class {
   }
 };
 
+// src/resources/videoAnalysis.ts
+var VideoAnalysis = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async submit(params) {
+    if (params.video === void 0 === (params.videoUrl === void 0)) {
+      throw new SoniloError("Provide exactly one of video or videoUrl");
+    }
+    const form = new FormData();
+    if (params.video !== void 0) {
+      const { blob, filename } = await toUploadBlob(params.video);
+      form.set("video", blob, filename);
+    } else {
+      form.set("video_url", params.videoUrl);
+    }
+    if (params.prompt !== void 0) form.set("prompt", params.prompt);
+    if (params.variantsNum !== void 0) {
+      form.set("variants_num", String(params.variantsNum));
+    }
+    const res = await this.client.request("/v1/video-analysis", {
+      method: "POST",
+      body: form
+    });
+    return await res.json();
+  }
+  async analyze(params, opts) {
+    const task = await this.submit(params);
+    return this.client.tasks.wait(task.task_id, opts);
+  }
+};
+
 // src/version.ts
-var VERSION = "0.14.0";
+var VERSION = "0.16.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";
@@ -826,6 +864,7 @@ var SoniloClient = class {
     this.videoToVideoSound = new VideoToVideoSound(this);
     this.audioDucking = new AudioDucking(this);
     this.dubbing = new Dubbing(this);
+    this.videoAnalysis = new VideoAnalysis(this);
   }
   /**
    * Perform an authenticated request; throws a typed error on non-2xx.