sonilo 0.3.0 → 0.5.0

package/README.md

@@ -9,6 +9,25 @@ Works in Node.js ≥ 18 and modern browsers. Zero runtime dependencies.
 npm install sonilo
 ```
 
+## Authentication
+
+Create an API key in your [Sonilo dashboard](https://platform.sonilo.com/dashboard/api-keys),
+then give it to the client either as an environment variable (recommended) or
+inline:
+
+```bash
+export SONILO_API_KEY=sk_...
+```
+
+```ts
+const sonilo = new SoniloClient();                     // reads SONILO_API_KEY
+// or pass it directly:
+const sonilo = new SoniloClient({ apiKey: "sk_..." });
+```
+
+Keep your key secret — use it only server-side, never commit it, and prefer the
+environment variable over hardcoding it.
+
 ## Quickstart
 
 ```ts
@@ -36,12 +55,14 @@ const track = await sonilo.videoToMusic.generate({
 await sonilo.videoToMusic.generate({ videoUrl: "https://example.com/clip.mp4" });
 ```
 
-### Vocal isolation (async)
+### Preserve speech (async)
 
-Splitting out a vocals-only stem requires the async task API — the plain
-stream above doesn't support it. Submit with `isolateVocals: true` (this
-implies `mode: "async"` if you don't set `mode` yourself) and poll with
-`client.tasks.wait<MusicTaskResult>()`:
+Set `preserveSpeech: true` to keep the source speech/vocals in the result.
+This requires the async task API — the plain stream above doesn't support it —
+so it implies `mode: "async"` if you don't set `mode` yourself. Submit, then
+poll with `client.tasks.wait<MusicTaskResult>()`. The result carries the
+generated `audio` plus a separate speech stem (`vocals`) and a `mux` (the
+generated music mixed with the preserved speech):
 
 ```ts
 import { SoniloClient, download } from "sonilo";
@@ -52,16 +73,108 @@ const client = new SoniloClient();
 const task = await client.videoToMusic.submit({
   video: "./my_video.mp4",
   prompt: "upbeat, energetic",
-  isolateVocals: true,
+  preserveSpeech: true,
 });
 const result = await client.tasks.wait<MusicTaskResult>(task.task_id);
 
-// `audio` is always an array for async video-to-music (one entry per
-// output stream); `vocals` and `mux` are only present with isolateVocals.
+// `audio` is always an array for async video-to-music (one entry per output
+// stream); `vocals` and `mux` are only present when preserveSpeech is set.
 await writeFile("mix.m4a", await download(result.audio[0]!));
 await writeFile("vocals.m4a", await download(result.vocals!));
 ```
 
+### Ducking, speech & output format (async video-to-music)
+
+The async `submit()` path also accepts:
+
+- `preserveSpeech` — keep the source speech/vocals in the result (see
+  [Preserve speech](#preserve-speech-async) above).
+- `ducking` — duck the generated music under the source voice. It is **on by
+  default** in async mode; pass `ducking: false` to opt out. When it runs, the
+  result gains a `ducked` array alongside `audio`.
+- `outputFormat` — `"m4a"` (default) or `"wav"` (requires async mode).
+
+```ts
+const task = await client.videoToMusic.submit({
+  video: "./my_video.mp4",
+  preserveSpeech: true,
+  outputFormat: "wav",
+  // ducking is on by default in async — set `false` to disable
+});
+const result = await client.tasks.wait<MusicTaskResult>(task.task_id);
+if (result.ducked) {
+  await writeFile("ducked.wav", await download(result.ducked[0]!));
+}
+```
+
+## Video to video
+
+Generate a soundtrack or sound effects and get back a **re-hosted video** with
+the audio muxed in — not just an audio file. Both endpoints are async; poll to
+a `VideoResult`:
+
+```ts
+import { SoniloClient, download } from "sonilo";
+import { writeFile } from "node:fs/promises";
+
+const client = new SoniloClient();
+
+// Score music into the video (optionally keep the original speech)
+const music = await client.videoToVideoMusic.generate({
+  video: "./my_video.mp4", // Node path; File/Blob in the browser, or `videoUrl`
+  prompt: "cinematic orchestral swell",
+  preserveSpeech: true,
+});
+await writeFile("scored.mp4", await download(music.video!));
+
+// Sound effects for the video, optionally per time segment
+const sfx = await client.videoToVideoSfx.generate({
+  video: "./my_video.mp4",
+  segments: [{ start: 0, end: 2, prompt: "footsteps on gravel" }],
+});
+await writeFile("with_sfx.mp4", await download(sfx.video!));
+```
+
+## Video to sound
+
+`videoToSound` and `videoToVideoSound` generate a music bed and sound effects
+for the same clip and return them mixed into a single soundtrack — one call,
+one charge, instead of chaining two requests. `videoToSound` returns the mixed
+audio; `videoToVideoSound` returns the source video with that audio muxed in.
+Both are async-only, and both accept the same options.
+
+```ts
+import { SoniloClient, download } from "sonilo";
+import { writeFile } from "node:fs/promises";
+
+const client = new SoniloClient();
+
+const result = await client.videoToSound.generate({
+  videoUrl: "https://example.com/clip.mp4",
+  musicPrompt: "uplifting orchestral score",
+  sfxPrompt: "match the on-screen action",
+});
+
+await writeFile("soundtrack.wav", await download(result.output_url));
+```
+
+The mixed result is `output_url` (`output_type` is `"audio"` here, `"video"`
+for `videoToVideoSound`). The individual stems come back alongside it, so you
+can re-balance the mix yourself:
+
+```ts
+await writeFile("music.m4a", await download(result.music));
+await writeFile("sfx.wav", await download(result.sfx));
+```
+
+`preserveSpeech: true` keeps the speech from the source video, and `ducking`
+(on by default) dips the music under it — pass `ducking: false` to opt out.
+`segments` takes the same `{ start, end, prompt }` list as `videoToSfx`.
+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)`.
+
 ## Configuration
 
 ```ts
@@ -143,6 +256,18 @@ const result = await client.tasks.wait(task.task_id, { pollInterval: 2000, timeo
 task keeps running server-side and can still be polled afterwards. Result URLs
 are presigned and expire; download promptly or re-fetch via `tasks.get`.
 
+## Free trial
+
+Accounts created through self-serve signup start with free runs on every
+endpoint — no card required:
+
+| Free runs | Endpoints |
+| --- | --- |
+| 2 each | text-to-music, text-to-sfx, audio-ducking |
+| 1 each | video-to-music, video-to-sfx, video-to-video-music, video-to-video-sfx, video-to-sound, video-to-video-sound |
+
+Once an endpoint's free runs are used up, calls to it bill at the normal rate.
+
 ## Account
 
 ```ts

package/dist/index.cjs

@@ -336,6 +336,32 @@ var TextToMusic = class {
   generate(params) {
     return collectTrack(this.stream(params));
   }
+  /**
+   * Submit an async text-to-music task; poll with
+   * `client.tasks.wait<MusicTaskResult>(task.task_id)`. Required for
+   * `outputFormat: "wav"`. `stream()`/`generate()` remain the streaming path.
+   */
+  async submit(params) {
+    const mode = params.mode ?? "async";
+    if (mode !== "async") {
+      throw new SoniloError('submit() requires mode: "async"');
+    }
+    const form = new FormData();
+    form.set("prompt", params.prompt);
+    form.set("duration", String(params.duration));
+    if (params.segments !== void 0) {
+      form.set("segments", JSON.stringify(params.segments));
+    }
+    form.set("mode", mode);
+    if (params.outputFormat !== void 0) {
+      form.set("output_format", params.outputFormat);
+    }
+    const res = await this.client.request("/v1/text-to-music", {
+      method: "POST",
+      body: form
+    });
+    return await res.json();
+  }
 };
 
 // src/upload.ts
@@ -418,9 +444,12 @@ var VideoToMusic = class {
       throw new SoniloError("Provide exactly one of video or videoUrl");
     }
     let mode = params.mode;
-    if (params.isolateVocals && mode === void 0) mode = "async";
-    if (params.isolateVocals && mode !== "async") {
-      throw new SoniloError('isolateVocals requires mode: "async"');
+    const needsAsync = params.isolateVocals || params.preserveSpeech || params.ducking !== void 0 || params.outputFormat === "wav";
+    if (mode === void 0) mode = "async";
+    if (needsAsync && mode !== "async") {
+      throw new SoniloError(
+        'isolateVocals/preserveSpeech/ducking/outputFormat "wav" require mode: "async"'
+      );
     }
     const form = new FormData();
     if (params.video !== void 0) {
@@ -433,10 +462,19 @@ var VideoToMusic = class {
     if (params.segments !== void 0) {
       form.set("segments", JSON.stringify(params.segments));
     }
-    if (mode !== void 0) form.set("mode", mode);
+    form.set("mode", mode);
+    if (params.preserveSpeech !== void 0) {
+      form.set("preserve_speech", String(params.preserveSpeech));
+    }
     if (params.isolateVocals !== void 0) {
       form.set("isolate_vocals", String(params.isolateVocals));
     }
+    if (params.outputFormat !== void 0) {
+      form.set("output_format", params.outputFormat);
+    }
+    if (params.ducking !== void 0) {
+      form.set("ducking", String(params.ducking));
+    }
     const res = await this.client.request("/v1/video-to-music", {
       method: "POST",
       body: form
@@ -500,8 +538,135 @@ var VideoToSfx = class {
   }
 };
 
+// src/resources/videoToVideoMusic.ts
+var VideoToVideoMusic = 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.preserveSpeech !== void 0) {
+      form.set("preserve_speech", String(params.preserveSpeech));
+    }
+    if (params.isolateVocals !== void 0) {
+      form.set("isolate_vocals", String(params.isolateVocals));
+    }
+    const res = await this.client.request("/v1/video-to-video-music", {
+      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/videoToVideoSfx.ts
+var VideoToVideoSfx = 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.segments !== void 0) {
+      form.set("segments", JSON.stringify(params.segments));
+    }
+    const res = await this.client.request("/v1/video-to-video-sfx", {
+      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/soundForm.ts
+async function buildSoundForm(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.musicPrompt !== void 0) form.set("music_prompt", params.musicPrompt);
+  if (params.sfxPrompt !== void 0) form.set("sfx_prompt", params.sfxPrompt);
+  if (params.segments !== void 0) {
+    form.set("segments", JSON.stringify(params.segments));
+  }
+  if (params.preserveSpeech !== void 0) {
+    form.set("preserve_speech", String(params.preserveSpeech));
+  }
+  if (params.ducking !== void 0) form.set("ducking", String(params.ducking));
+  return form;
+}
+
+// src/resources/videoToSound.ts
+var VideoToSound = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async submit(params) {
+    const res = await this.client.request("/v1/video-to-sound", {
+      method: "POST",
+      body: await buildSoundForm(params)
+    });
+    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/videoToVideoSound.ts
+var VideoToVideoSound = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async submit(params) {
+    const res = await this.client.request("/v1/video-to-video-sound", {
+      method: "POST",
+      body: await buildSoundForm(params)
+    });
+    return await res.json();
+  }
+  async generate(params, opts) {
+    const task = await this.submit(params);
+    return this.client.tasks.wait(task.task_id, opts);
+  }
+};
+
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.sonilo.com";
@@ -525,6 +690,10 @@ var SoniloClient = class {
     this.videoToMusic = new VideoToMusic(this);
     this.textToSfx = new TextToSfx(this);
     this.videoToSfx = new VideoToSfx(this);
+    this.videoToVideoMusic = new VideoToVideoMusic(this);
+    this.videoToVideoSfx = new VideoToVideoSfx(this);
+    this.videoToSound = new VideoToSound(this);
+    this.videoToVideoSound = new VideoToVideoSound(this);
   }
   /**
    * Perform an authenticated request; throws a typed error on non-2xx.
@@ -557,15 +726,16 @@ var SoniloClient = class {
 
 // src/download.ts
 async function download(media, fetchFn = globalThis.fetch, timeout = DEFAULT_TIMEOUT_MS) {
-  if (!media?.url) {
+  const url = typeof media === "string" ? media : media?.url;
+  if (!url) {
     throw new SoniloError("No media to download");
   }
   let res;
   try {
-    res = await fetchFn(media.url, { signal: AbortSignal.timeout(timeout) });
+    res = await fetchFn(url, { signal: AbortSignal.timeout(timeout) });
   } catch (err) {
     if (isTimeoutSignalError(err)) {
-      throw new RequestTimeoutError(`Download of ${media.url} timed out after ${timeout}ms`);
+      throw new RequestTimeoutError(`Download of ${url} timed out after ${timeout}ms`);
     }
     throw err;
   }