sonilo 0.13.0 → 0.15.0

package/README.md

@@ -248,6 +248,42 @@ Input videos may be at most 180 seconds long.
 Use `submit()` instead of `generate()` to get a `task_id` back immediately and
 poll it yourself with `client.tasks.wait<SoundResult>(taskId)`.
 
+## Audio ducking
+
+`client.audioDucking.submit()` / `.generate()` mix an existing music bed under
+an existing voice track, dipping the music wherever the voice speaks and
+lifting it back in the gaps. Nothing is generated — both inputs are yours.
+Reach for it when the music is fixed or external; when the music is being
+generated for the same clip anyway, `videoToSound` or `videoToMusic` with
+`ducking: true` duck internally as part of that one call instead.
+
+```ts
+import { SoniloClient, download } from "sonilo";
+import { writeFile } from "node:fs/promises";
+
+const client = new SoniloClient();
+
+const result = await client.audioDucking.generate({
+  voice: "./interview.mp4", // Node path; File/Blob in the browser, or `voiceUrl`
+  musicUrl: "https://example.com/bed.wav",
+});
+
+await writeFile(
+  result.output_type === "video" ? "ducked.mp4" : "ducked.wav",
+  await download(result.output_url!),
+);
+```
+
+Params: exactly one of `voice` / `voiceUrl` and exactly one of `music` /
+`musicUrl` (a local input and a URL mix freely across the two). The **voice**
+may be audio or video — a video's own audio track becomes the voice, and the
+ducked mix is muxed back into a new video, so the result is a `.mp4` instead
+of a `.wav`. The **music** must be audio: the API never probes it for a video
+stream, so a video there is silently mishandled rather than rejected. Each
+input is capped at 360 seconds. Async-only; the result is a `DuckingResult`
+carrying the same flat `output_url` / `output_type` envelope as
+`videoToSound`, with no stems.
+
 ## Dubbing
 
 `client.dubbing.submit()` / `.generate()` dub a video into one or more target
@@ -302,6 +338,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
@@ -390,7 +467,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

@@ -712,6 +712,43 @@ var VideoToVideoSound = class {
   }
 };
 
+// src/resources/audioDucking.ts
+var AudioDucking = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async submit(params) {
+    if (params.voice === void 0 === (params.voiceUrl === void 0)) {
+      throw new SoniloError("Provide exactly one of voice or voiceUrl");
+    }
+    if (params.music === void 0 === (params.musicUrl === void 0)) {
+      throw new SoniloError("Provide exactly one of music or musicUrl");
+    }
+    const form = new FormData();
+    if (params.voice !== void 0) {
+      const { blob, filename } = await toUploadBlob(params.voice);
+      form.set("voice_file", blob, filename);
+    } else {
+      form.set("voice_url", params.voiceUrl);
+    }
+    if (params.music !== void 0) {
+      const { blob, filename } = await toUploadBlob(params.music);
+      form.set("music_file", blob, filename);
+    } else {
+      form.set("music_url", params.musicUrl);
+    }
+    const res = await this.client.request("/v1/audio-ducking", {
+      method: "POST",
+      body: form
+    });
+    return await res.json();
+  }
+  async generate(params, opts) {
+    const task = await this.submit(params);
+    return this.client.tasks.wait(task.task_id, opts);
+  }
+};
+
 // src/resources/dubbing.ts
 async function buildDubbingForm(params) {
   if (params.video === void 0 === (params.videoUrl === void 0)) {
@@ -755,8 +792,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.13.0";
+var VERSION = "0.15.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";
@@ -787,7 +856,9 @@ var SoniloClient = class {
     this.videoToVideoSfx = new VideoToVideoSfx(this);
     this.videoToSound = new VideoToSound(this);
     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.