sonilo 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -51,6 +51,10 @@ interface TextToMusicParams {
     prompt: string;
     duration: number;
     segments?: Segment[];
+    /** "stream" (default) or "async" (required by `submit()` and `output_format: "wav"`). */
+    mode?: "stream" | "async";
+    /** Container for the async result. `wav` requires `mode: "async"`. Defaults to m4a server-side. */
+    outputFormat?: "m4a" | "wav";
     /** 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
@@ -79,6 +83,16 @@ interface VideoToMusicParams {
      * "async" automatically. Only usable via `submit()` — the backend
      * rejects it on the plain stream. */
     isolateVocals?: boolean;
+    /** Keep the source speech/vocals in the async result. Current name for
+     * `isolateVocals`; both are accepted and OR'd server-side. Requires
+     * `mode: "async"` (auto-selected by `submit()`). */
+    preserveSpeech?: boolean;
+    /** Container for the async result. `wav` requires async. Defaults to m4a. */
+    outputFormat?: "m4a" | "wav";
+    /** Duck the generated music under the source voice at finalize time.
+     * Default-ON server-side in async mode: leave unset to keep it on, pass
+     * `false` to opt out. Free, best-effort; only valid on `submit()`. */
+    ducking?: boolean;
 }
 interface AccountServices {
     available_services: string[];
@@ -192,6 +206,8 @@ interface MusicTaskResult extends BaseTaskResult {
     vocals?: SfxMedia;
     /** Muxed output per stream; present only when `isolateVocals` was requested. */
     mux?: MusicMuxEntry[];
+    /** Music ducked under the source voice; present only when `ducking` ran. */
+    ducked?: MusicMediaEntry[];
     title?: MusicTitle;
     duration_seconds?: number;
 }
@@ -201,6 +217,63 @@ interface WaitOptions {
     /** Overall deadline in milliseconds. Default 600000. */
     timeout?: number;
 }
+/** Result of an async video-to-video task (`videoToVideoMusic`/`videoToVideoSfx`):
+ * a re-hosted video with generated music or SFX muxed in. */
+interface VideoResult extends BaseTaskResult {
+    video?: SfxMedia;
+    duration_seconds?: number;
+}
+interface VideoToVideoMusicParams {
+    video?: VideoInput;
+    videoUrl?: string;
+    prompt?: string;
+    /** Keep the source speech/vocals in the output. Both this and the legacy
+     * `isolateVocals` are accepted and OR'd server-side. */
+    preserveSpeech?: boolean;
+    /** @deprecated Legacy alias for `preserveSpeech`. */
+    isolateVocals?: boolean;
+}
+interface VideoToVideoSfxParams {
+    video?: VideoInput;
+    videoUrl?: string;
+    prompt?: string;
+    segments?: SfxSegment[];
+}
+/** Params for `videoToSound` and `videoToVideoSound`. Both endpoints take the
+ * identical form, so they share one params type. */
+interface VideoToSoundParams {
+    video?: VideoInput;
+    videoUrl?: string;
+    /** Style hint for the generated music bed. */
+    musicPrompt?: string;
+    /** Description of the sound effects layered over the music. */
+    sfxPrompt?: string;
+    /** Per-segment SFX descriptions; must start at 0 and be contiguous. */
+    segments?: SfxSegment[];
+    /** Keep the source speech in the result. */
+    preserveSpeech?: boolean;
+    /** Duck the generated music under the source speech. Default-ON
+     * server-side: leave unset to keep it on, pass `false` to opt out. */
+    ducking?: boolean;
+}
+/** Result of a `videoToSound` / `videoToVideoSound` task (`tasks.get`) or its
+ * final state (`generate`).
+ *
+ * The combined music+SFX result is `output_url` — a bare presigned URL rather
+ * than a media object, since these endpoints render one artifact whose kind is
+ * announced by `output_type` ("audio" for video-to-sound, "video" for
+ * video-to-video-sound). `music`, `music_processed` and `sfx` are the
+ * individual stems; pass any of them, or `output_url` itself, to `download()`. */
+interface SoundResult extends BaseTaskResult {
+    output_url?: string;
+    output_type?: "audio" | "video";
+    output_bytes?: number;
+    music?: SfxMedia;
+    /** Present only when `preserveSpeech`/`ducking` altered the music bed. */
+    music_processed?: SfxMedia;
+    sfx?: SfxMedia;
+    duration_seconds?: number;
+}
 
 declare class Account {
     private readonly client;
@@ -239,6 +312,12 @@ declare class TextToMusic {
     stream(params: TextToMusicParams): AsyncGenerator<StreamEvent, void, undefined>;
     /** Generate and buffer the whole track; throws GenerationError on stream errors. */
     generate(params: TextToMusicParams): Promise<Track>;
+    /**
+     * 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.
+     */
+    submit(params: TextToMusicParams): Promise<SfxTask>;
 }
 
 declare class VideoToMusic {
@@ -269,6 +348,43 @@ declare class VideoToSfx {
     generate(params: VideoToSfxParams, opts?: WaitOptions): Promise<SfxResult>;
 }
 
+/** Generate an original score for a video and get back a re-hosted video with
+ * the music muxed in. Async only: `submit()` returns a task ack; poll with
+ * `client.tasks.wait<VideoResult>(id)`, or use `generate()` to do both. */
+declare class VideoToVideoMusic {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: VideoToVideoMusicParams): Promise<SfxTask>;
+    generate(params: VideoToVideoMusicParams, opts?: WaitOptions): Promise<VideoResult>;
+}
+
+/** Generate sound effects for a video and get back a re-hosted video with the
+ * SFX muxed in. Async only. */
+declare class VideoToVideoSfx {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: VideoToVideoSfxParams): Promise<SfxTask>;
+    generate(params: VideoToVideoSfxParams, opts?: WaitOptions): Promise<VideoResult>;
+}
+
+/** Generate a combined music + sound-effects track for a video and get back
+ * the mixed audio. Async only. */
+declare class VideoToSound {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: VideoToSoundParams): Promise<SfxTask>;
+    generate(params: VideoToSoundParams, opts?: WaitOptions): Promise<SoundResult>;
+}
+
+/** Generate a combined music + sound-effects track for a video and get back a
+ * re-hosted video with that track muxed in. Async only. */
+declare class VideoToVideoSound {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: VideoToSoundParams): Promise<SfxTask>;
+    generate(params: VideoToSoundParams, opts?: WaitOptions): Promise<SoundResult>;
+}
+
 interface SoniloClientOptions {
     /** Defaults to the SONILO_API_KEY environment variable (Node.js only). */
     apiKey?: string;
@@ -292,6 +408,10 @@ declare class SoniloClient {
     readonly videoToMusic: VideoToMusic;
     readonly textToSfx: TextToSfx;
     readonly videoToSfx: VideoToSfx;
+    readonly videoToVideoMusic: VideoToVideoMusic;
+    readonly videoToVideoSfx: VideoToVideoSfx;
+    readonly videoToSound: VideoToSound;
+    readonly videoToVideoSound: VideoToVideoSound;
     constructor(options?: SoniloClientOptions);
     /**
      * Perform an authenticated request; throws a typed error on non-2xx.
@@ -357,9 +477,13 @@ declare class TaskTimeoutError extends SoniloError {
 declare class RequestTimeoutError extends SoniloError {
 }
 
-/** Fetch a result media file. The URL is presigned — no API key is sent. */
-declare function download(media: SfxMedia | undefined, fetchFn?: typeof globalThis.fetch, timeout?: number): Promise<Uint8Array>;
+/** Fetch a result media file. The URL is presigned — no API key is sent.
+ *
+ * Accepts either a media object (`result.audio`, `result.music`, …) or a bare
+ * URL string, which is what the combined video-to-sound endpoints return as
+ * `output_url`. */
+declare function download(media: SfxMedia | string | undefined, fetchFn?: typeof globalThis.fetch, timeout?: number): Promise<Uint8Array>;
 
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.4.0";
 
-export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, 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 StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoToMusicParams, type VideoToSfxParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, 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 SoundResult, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };

package/dist/index.js

@@ -295,6 +295,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
@@ -377,9 +403,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) {
@@ -392,10 +421,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
@@ -459,8 +497,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";
@@ -484,6 +649,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.
@@ -516,15 +685,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;
   }