sonilo 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -452,6 +452,34 @@ interface SoundResult extends BaseTaskResult {
     /** One entry per variant; see `SoundOutputEntry`. */
     outputs?: SoundOutputEntry[];
 }
+/** Params for `audioDucking`: mix an existing music bed under an existing
+ * voice track, ducking the music wherever the voice speaks. Exactly one of
+ * `voice`/`voiceUrl` and exactly one of `music`/`musicUrl`; a local input and
+ * a URL may be mixed across the two.
+ *
+ * The voice may be audio or video (`VideoInput` is the SDK's generic media
+ * input union) — a video's own audio track becomes the voice, and the ducked
+ * mix is re-muxed back into a new video. The music must be audio: the backend
+ * never probes it for a video stream, so a video there would be silently
+ * mishandled. Each input is capped at 360 seconds server-side. */
+interface AudioDuckingParams {
+    voice?: VideoInput;
+    voiceUrl?: string;
+    music?: VideoInput;
+    musicUrl?: string;
+}
+/** Result of an `audioDucking` task (`tasks.get`) or its final state
+ * (`generate`). Same flat envelope as `SoundResult`, but a ducking task
+ * renders exactly one artifact and no stems: a `.wav` (`output_type`
+ * "audio"), or a `.mp4` with the ducked mix re-muxed in (`output_type`
+ * "video") when the voice input was a video. Pass `output_url` to
+ * `download()`. */
+interface DuckingResult extends BaseTaskResult {
+    output_url?: string;
+    output_type?: "audio" | "video";
+    output_bytes?: number;
+    duration_seconds?: number;
+}
 /**
  * A target language for /v1/dubbing. The union stays open (`string & {}`) so a
  * language added server-side still type-checks against an older SDK — the
@@ -483,6 +511,50 @@ interface DubbingResult extends BaseTaskResult {
      */
     outputs?: Record<string, string>;
 }
+interface VideoAnalysisParams {
+    /** Exactly one of `video` / `videoUrl`. */
+    video?: VideoInput;
+    /** Exactly one of `video` / `videoUrl`. */
+    videoUrl?: string;
+    /** Optional guidance for the analysis, at most 2000 characters. */
+    prompt?: string;
+    /**
+     * How many independent creative briefs to author for the same video
+     * (1-5, default 1). Billed per brief.
+     */
+    variantsNum?: number;
+}
+/** One time-aligned section of the analyzed video, with the scoring
+ * direction for that stretch. Bounds are whole seconds — the backend
+ * truncates any fractional upstream bound before it reaches the envelope. */
+interface AnalysisSegment {
+    start: number;
+    end: number;
+    /** The backend always emits one, defaulting to the string `"none"`. */
+    label: string;
+    prompt: string;
+}
+/** One independent creative brief for the whole video. Only the generation
+ * prompt is public — the upstream's title/summary/tags are internal display
+ * copy the API deliberately does not resell. */
+interface AnalysisVariation {
+    prompt: string;
+}
+/**
+ * The only Sonilo result with no media artifact at all: video-analysis
+ * generates nothing and there is nothing to download. The payload is the
+ * work order — `segments` for a time-aligned plan, and one `prompt` per
+ * requested variation, each ready to pass to videoToMusic, videoToSfx,
+ * videoToSound or their video-to-video counterparts.
+ *
+ * Both lists are optional because a `processing` or `failed` poll carries
+ * neither.
+ */
+interface VideoAnalysisResult extends BaseTaskResult {
+    segments?: AnalysisSegment[];
+    variations?: AnalysisVariation[];
+    duration_seconds?: number;
+}
 
 declare class Account {
     private readonly client;
@@ -596,6 +668,21 @@ declare class VideoToVideoSound {
     generate(params: VideoToVideoSoundParams, opts?: WaitOptions): Promise<SoundResult>;
 }
 
+/** Duck an existing music bed under a voice track. Async only (202 + poll).
+ *
+ * Both inputs are user-supplied — nothing is generated here. The voice may be
+ * audio OR a video: the backend extracts a video's audio track, ducks the
+ * music under it, and re-muxes the ducked mix back into a new video (the
+ * result's `output_type` announces which came back). The music must be audio —
+ * the backend never probes it for a video stream, so a video there would be
+ * silently mishandled. */
+declare class AudioDucking {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: AudioDuckingParams): Promise<SfxTask>;
+    generate(params: AudioDuckingParams, opts?: WaitOptions): Promise<DuckingResult>;
+}
+
 /** Dub a video into one or more target languages. Async only; the result
  * carries a language → dubbed-video-URL map under `outputs`. */
 declare class Dubbing {
@@ -605,6 +692,28 @@ declare class Dubbing {
     generate(params: DubbingParams, opts?: WaitOptions): Promise<DubbingResult>;
 }
 
+/** Analyze a video and get back a creative brief for scoring it. Async only.
+ *
+ * This endpoint generates nothing — no audio, no video, no artifact to
+ * download. The result is the work order: `segments` (a time-aligned section
+ * plan) plus one `prompt` per requested variation, each ready to hand
+ * straight to videoToMusic, videoToSfx, videoToSound or their
+ * video-to-video counterparts.
+ *
+ * The method is `analyze`, not `generate`, for that reason: every other
+ * resource's `generate` returns something you download, and this one never
+ * does.
+ *
+ * The 1-5 bound on `variantsNum` and the 2000-character bound on `prompt`
+ * are deliberately not checked here — the backend owns them, and a hardcoded
+ * copy would make this SDK reject values a later API widens. */
+declare class VideoAnalysis {
+    private readonly client;
+    constructor(client: SoniloClient);
+    submit(params: VideoAnalysisParams): Promise<SfxTask>;
+    analyze(params: VideoAnalysisParams, opts?: WaitOptions): Promise<VideoAnalysisResult>;
+}
+
 interface SoniloClientOptions {
     /** Defaults to the SONILO_API_KEY environment variable (Node.js only). */
     apiKey?: string;
@@ -642,7 +751,9 @@ declare class SoniloClient {
     readonly videoToVideoSfx: VideoToVideoSfx;
     readonly videoToSound: VideoToSound;
     readonly videoToVideoSound: VideoToVideoSound;
+    readonly audioDucking: AudioDucking;
     readonly dubbing: Dubbing;
+    readonly videoAnalysis: VideoAnalysis;
     constructor(options?: SoniloClientOptions);
     /**
      * Perform an authenticated request; throws a typed error on non-2xx.
@@ -724,6 +835,6 @@ declare class RequestTimeoutError extends SoniloError {
 declare function download(media: SfxMedia | string | undefined, fetchFn?: typeof globalThis.fetch, timeout?: number): Promise<Uint8Array>;
 
 /** The SDK's own version. Generated by scripts/sync-versions.mjs — do not edit. */
-declare const VERSION = "0.13.0";
+declare const VERSION = "0.15.0";
 
-export { APIError, type AccountServices, type AudioChunkEvent, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, 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 SoundOutputEntry, type SoundResult, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type VideoToVideoSoundParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };
+export { APIError, type AccountServices, type AnalysisSegment, type AnalysisVariation, type AudioChunkEvent, type AudioDuckingParams, AuthenticationError, BadRequestError, type BaseTaskResult, type CompleteEvent, type CostEvent, type CostInfo, DEFAULT_TIMEOUT_MS, type DailyUsage, type DubbingLanguage, type DubbingParams, type DubbingResult, type DuckingResult, 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 SoundOutputEntry, type SoundResult, type StreamEvent, TaskFailedError, TaskTimeoutError, type TextToMusicParams, type TextToSfxParams, type TitleEvent, type Track, TrialExhaustedError, type TrialQuota, type UnknownEvent, type UsageResponse, type UsageSummary, VERSION, type VideoAnalysisParams, type VideoAnalysisResult, type VideoInput, type VideoResult, type VideoToMusicParams, type VideoToSfxParams, type VideoToSoundParams, type VideoToVideoMusicParams, type VideoToVideoSfxParams, type VideoToVideoSoundParams, type WaitOptions, download, isAudioChunkEvent, isErrorEvent };

package/dist/index.js

@@ -670,6 +670,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)) {
@@ -713,8 +750,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";
@@ -745,7 +814,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.