songbrain 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,570 @@
+/**
+ * Response types of the Songbrain API, schema `songbrain.song/1`.
+ *
+ * Based on a real response from https://api.songbrain.ai/v1/examples/old-truck-home.
+ * New fields can appear at any time; existing fields don't change meaning.
+ * All times are seconds from the start of the song unless the name says
+ * otherwise (`start_in_clip`).
+ */
+type SongStatus = "processing" | "done" | "failed";
+/** One of the sections a song document has. Use with `include`. */
+type SectionName = "song_dna" | "timeline" | "best_moments" | "lyrics" | "scores" | "story" | "shot_plan";
+interface Billing {
+    /** "free" or "credits". */
+    type: "free" | "credits" | (string & {});
+    credits: number;
+}
+interface SongInfo {
+    title: string | null;
+    artist: string | null;
+    duration_sec: number | null;
+    language: string | null;
+    has_vocals: boolean | null;
+}
+interface KeyChange {
+    at_sec: number;
+    to: string;
+}
+interface Instrument {
+    name: string;
+    confidence: number;
+}
+interface LoudnessCheck {
+    loudness_ok: boolean;
+    delta_lufs: number;
+}
+interface SoundsLike {
+    artist: string;
+    track: string;
+}
+interface SongDNA {
+    genre: string;
+    /** One of 37 subgenres. */
+    subgenre: string;
+    genre_confidence: number;
+    style?: string | null;
+    tempo_bpm: number;
+    tempo_confidence: number;
+    /** e.g. "C minor". */
+    key: string;
+    key_confidence: number;
+    key_changes: KeyChange[];
+    /** e.g. ["epic", "powerful", "melancholic"]. */
+    mood: string[];
+    /** Vocal style, or "instrumental". */
+    vocals: string;
+    /** Instruments with confidence >= 0.25. */
+    instruments: Instrument[];
+    /** 0-1. */
+    energy: number;
+    /** 0-1. */
+    brightness: number;
+    /** Integrated loudness (EBU R128). */
+    loudness_lufs: number;
+    true_peak_dbfs: number;
+    /** Per platform: spotify, youtube, apple. */
+    streaming_loudness: Record<string, LoudnessCheck>;
+    tagline?: string | null;
+    description?: string | null;
+    sounds_like?: SoundsLike[];
+}
+interface Section {
+    start_sec: number;
+    end_sec: number;
+    /** Same letter = same music, e.g. A, B, A. */
+    label: string;
+    /** 0-1, relative to the song's loudest part. */
+    energy: number;
+}
+interface VocalChange {
+    at_sec: number;
+    label: string;
+}
+interface LyricHook {
+    at_sec: number;
+    line: string;
+    role: string;
+    strength: number;
+}
+interface Timeline {
+    /** Every beat in seconds. In view=summary this is a short placeholder string. */
+    beats: number[] | string;
+    /** First beat of each bar. In view=summary this is a short placeholder string. */
+    downbeats: number[] | string;
+    time_signature: string;
+    sections: Section[];
+    vocal_timeline: VocalChange[];
+    lyric_hooks: LyricHook[] | null;
+}
+interface PlatformFit {
+    tiktok: number;
+    instagram_reels: number;
+    youtube_shorts: number;
+}
+interface CaptionIdeas {
+    curiosity?: string;
+    hype?: string;
+    storytelling?: string;
+}
+interface BestMoment {
+    /** 1 = strongest. */
+    rank: number;
+    start_sec: number;
+    peak_sec: number;
+    end_sec: number;
+    duration_sec: number;
+    kind: string;
+    /** 0-100. */
+    score: number;
+    why: string;
+    explanation: string;
+    judge_note: string;
+    /** The words sung inside the window. */
+    sung: string | null;
+    platform_fit: PlatformFit;
+    /** Beats inside the window. Omitted in view=summary. */
+    beat_grid_sec?: number[];
+    caption_ideas: CaptionIdeas | null;
+    hashtags: string[] | null;
+}
+interface Word {
+    w: string;
+    start: number;
+    end: number;
+}
+interface LyricLine {
+    start: number;
+    end: number;
+    text: string;
+    /** Omitted in view=summary. */
+    words?: Word[];
+}
+interface Lyrics {
+    language?: string | null;
+    lines?: LyricLine[];
+    /** true for recognised commercial recordings; then `lines` is absent. */
+    hidden?: boolean;
+    reason?: string;
+}
+interface ScoreBlock {
+    /** 0-100. */
+    score: number;
+    breakdown: Record<string, number>;
+    note?: string;
+}
+interface WhatWorks {
+    title: string;
+    detail: string;
+}
+interface WhatToFix {
+    title: string;
+    problem: string;
+    fix: string;
+}
+interface Scores {
+    /** Song strength for short-form video. Not a view prediction. */
+    virality: ScoreBlock;
+    quality: ScoreBlock;
+    lyrics: ScoreBlock;
+    summary: string;
+    what_works: WhatWorks[];
+    what_to_fix: WhatToFix[];
+    audience: string[];
+}
+interface StoryElement {
+    /** The one object the video is about. */
+    thing: string;
+    before: string;
+    event: string;
+    after: string;
+}
+interface StoryBeats {
+    setup: string;
+    turn: string;
+    payoff: string;
+}
+interface Story {
+    meaning: string;
+    why_these_visuals: string;
+    confidence: number;
+    /** One place for every shot. */
+    world: string;
+    protagonist: string | null;
+    carrier: string;
+    recurring_presence: string | null;
+    props: string[];
+    lyric_evidence: string[];
+    /** Three colours for every shot. */
+    palette: string[];
+    element: StoryElement;
+    story_beats: StoryBeats;
+}
+interface ShotStyle {
+    palette: string[] | null;
+    /** Append to your own prompts to stay in the look. */
+    prompt_suffix: string | null;
+    world: string | null;
+}
+interface Phases {
+    tease_end?: number;
+    payoff_start?: number;
+    payoff_end?: number;
+    outro_start?: number;
+}
+type SceneKind = "tease" | "build" | "cutaway" | "burst" | "strobe" | "hero" | "outro" | (string & {});
+type Act = "setup" | "turn" | "payoff" | (string & {});
+interface Scene {
+    index: number;
+    /** tease, build, cutaway, burst, strobe (about 4 frames), hero, outro. */
+    kind: SceneKind;
+    act: Act;
+    role: string;
+    /** Absolute seconds in the song. Cuts sit on beats. */
+    start_sec: number;
+    end_sec: number;
+    /** Relative to clip.window_sec[0]. */
+    start_in_clip: number;
+    duration_sec: number;
+    beats_in_scene: number;
+    transition_in: string;
+    motion: string;
+    /** A ready image/video prompt with world, palette and style. */
+    prompt: string | null;
+    /** The readable part of the prompt, without the style tail. */
+    visual: string | null;
+    framing: string | null;
+    emotion: string | null;
+    symbol: string | null;
+    story_beat: string | null;
+    /** The words sung during the scene. */
+    sung: string | null;
+}
+interface Clip {
+    /** [start, end] of the clip in the song. */
+    window_sec: [number, number];
+    aspect_ratio: string;
+    /** Tempo of the cut grid; can run at double time. */
+    grid_bpm: number | null;
+    /** Beats inside the window. Omitted in view=summary. */
+    beats_sec?: number[];
+    /** The repeated sung line the payoff lands on. */
+    hook_line: string | null;
+    phases_sec: Phases;
+    scenes: Scene[];
+}
+interface FullSongSection {
+    start_sec: number;
+    end_sec: number;
+    section: string;
+    energy: number;
+    energy_rank: number;
+    act: Act;
+    cut_every_beats: number;
+    /** Cut points on the song's own beats. Omitted in view=summary. */
+    cuts_sec?: number[] | null;
+    role: string;
+    visual: string | null;
+    prompt?: string | null;
+    sung: string | null;
+}
+interface FullSong {
+    note: string;
+    sections: FullSongSection[];
+}
+interface ShotPlan {
+    status: "ready" | "pending" | "unavailable" | (string & {});
+    /** Set when status is "unavailable". */
+    reason?: string;
+    engine?: string;
+    style?: ShotStyle;
+    /** A beat-synced edit of the best moment (about 15 s, 9:16). */
+    clip?: Clip;
+    /** Section-level plan for a full-length video. */
+    full_song?: FullSong | null;
+}
+interface ErrorInfo {
+    code: string;
+    message: string;
+}
+/**
+ * The song document. While processing, only `id`, `status`, `progress` and
+ * `eta_sec` are set. With `include`, only the named sections are present.
+ */
+interface Song {
+    object: "song";
+    schema?: string;
+    id: string;
+    status: SongStatus;
+    progress?: number;
+    eta_sec?: number;
+    /** Set when status is "failed". */
+    error?: ErrorInfo;
+    song?: SongInfo;
+    song_dna?: SongDNA;
+    timeline?: Timeline;
+    best_moments?: BestMoment[];
+    lyrics?: Lyrics;
+    scores?: Scores;
+    story?: Story;
+    shot_plan?: ShotPlan;
+    created_at?: string | null;
+    external_ref?: string | null;
+    billing?: Billing;
+}
+/** The 202 body of POST /songs. */
+interface SongCreated {
+    object: "song";
+    id: string;
+    status: "processing";
+    eta_sec: number;
+    billing: Billing;
+    external_ref?: string | null;
+    url: string;
+}
+/** GET /songs/{id}/shot-plan and GET /examples/{id}/shot-plan. */
+interface SongShotPlan {
+    id: string;
+    status?: SongStatus;
+    song?: SongInfo;
+    story?: Story;
+    shot_plan?: ShotPlan;
+}
+interface SongListItem {
+    id: string;
+    status: string;
+    external_ref: string | null;
+    created_at: string | null;
+    billing: Billing;
+}
+interface SongList {
+    object: "list";
+    data: SongListItem[];
+}
+interface DeleteResult {
+    id: string;
+    deleted: boolean;
+}
+interface ExampleSummary {
+    id: string;
+    title: string;
+    artist: string;
+    genre: string;
+    subgenre: string;
+    tempo_bpm: number;
+    key: string;
+    duration_sec: number;
+    has_vocals: boolean;
+    about: string;
+    scenes: number;
+    url: string;
+    shot_plan_url: string;
+}
+interface ExampleList {
+    object: "list";
+    data: ExampleSummary[];
+}
+interface Account {
+    credits: number;
+    free_songs_per_month: number;
+    free_songs_used: number;
+    free_songs_left: number;
+    price_per_song_credits: number;
+    price_per_song_usd: number;
+    songs_this_month: number;
+    buy_credits_url: string;
+    songs_left_from_credits?: number;
+    low_balance?: boolean;
+    low_balance_threshold_songs?: number;
+    key?: {
+        id: string;
+        name: string | null;
+    };
+}
+interface Pricing {
+    free_songs_per_month: number;
+    price_per_song_credits: number;
+    price_per_song_usd: number;
+    credit_packs: {
+        credits: number;
+        usd: number;
+    }[];
+    included_per_song: string[];
+    volume: string;
+    limits: Record<string, number>;
+    examples_are_free: boolean;
+}
+/** A webhook event body. */
+interface WebhookEvent<T = Record<string, unknown>> {
+    type: "song.done" | "song.failed" | "account.low_balance" | (string & {});
+    /** Unix seconds. */
+    created: number;
+    data: T;
+}
+
+declare const DEFAULT_BASE_URL = "https://api.songbrain.ai/v1";
+/** A Blob/File, a Buffer or bytes, or a local file path (Node). */
+type FileInput = Blob | Uint8Array | ArrayBuffer | string;
+interface SongbrainOptions {
+    /** Your key (`sb_live_…`). Defaults to `process.env.SONGBRAIN_API_KEY`. The example endpoints work without a key. */
+    apiKey?: string;
+    /** Defaults to `process.env.SONGBRAIN_BASE_URL` or https://api.songbrain.ai/v1. */
+    baseUrl?: string;
+    /** Timeout for each HTTP request in ms (uploads included). Default 60 000. */
+    timeoutMs?: number;
+    /** How often to retry 429 and 5xx responses, with backoff. Default 3. */
+    maxRetries?: number;
+    /** A custom fetch implementation. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+}
+interface AnalyzeOptions {
+    /** A Blob/File, a Buffer or bytes, or a local file path. Pass this or `audioUrl`. */
+    file?: FileInput;
+    /** A public http(s) URL of the audio file. Pass this or `file`. */
+    audioUrl?: string;
+    title?: string;
+    artist?: string;
+    /** Receives `song.done` / `song.failed`. */
+    webhookUrl?: string;
+    /** Your own id, echoed back in responses and webhooks. */
+    externalRef?: string;
+    /** File name for an upload. Its extension must match the audio format. Taken from the path or File name, or guessed from the bytes. */
+    filename?: string;
+    /** Wait until the song is done and return the full document (default true). */
+    wait?: boolean;
+    /** Time between status checks while waiting. Default 5 000. */
+    pollIntervalMs?: number;
+    /** Total time to wait before throwing `WaitTimeout`. Default 300 000. */
+    timeoutMs?: number;
+}
+interface WaitOptions {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}
+interface GetSongOptions {
+    /** "summary" drops word timings and beat arrays (about 3x smaller). */
+    view?: "full" | "summary";
+    /** Only these sections, e.g. ["song_dna", "shot_plan"]. */
+    include?: SectionName[] | string;
+}
+/**
+ * Client for the Songbrain API. Every method resolves to the JSON body of
+ * the response.
+ *
+ * ```ts
+ * const sb = new Songbrain(); // reads SONGBRAIN_API_KEY
+ * const song = await sb.analyze({ file: "song.mp3" });
+ * for (const s of song.shot_plan?.clip?.scenes ?? []) console.log(s.start_sec, s.prompt);
+ * ```
+ */
+declare class Songbrain {
+    readonly apiKey: string | undefined;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    private readonly fetchImpl;
+    /** @internal Overridable in tests. */
+    _sleep: (ms: number) => Promise<void>;
+    constructor(options?: SongbrainOptions);
+    /**
+     * Analyse a song from a file or a public URL. Pass exactly one of `file` or `audioUrl`.
+     * Typically 60-90 s. With `wait: true` (default) resolves to the full document;
+     * with `wait: false` to the 202 body `{ id, status: "processing", eta_sec, billing }`.
+     */
+    analyze(options: AnalyzeOptions & {
+        wait: false;
+    }): Promise<SongCreated>;
+    analyze(options: AnalyzeOptions & {
+        wait?: true;
+    }): Promise<Song>;
+    analyze(options: AnalyzeOptions): Promise<Song | SongCreated>;
+    /** Poll GET /songs/{id} until the song is done. Throws `AnalysisFailed` or `WaitTimeout`. */
+    waitFor(songId: string, options?: WaitOptions): Promise<Song>;
+    /** Status while processing, then the full document. */
+    getSong(songId: string, options?: GetSongOptions): Promise<Song>;
+    /** Only the story and the shot plan: `{ id, status, song, story, shot_plan }`. */
+    shotPlan(songId: string): Promise<SongShotPlan>;
+    /** Your songs, newest first. `limit` is 1-100 (default 20). */
+    listSongs(options?: {
+        limit?: number;
+    }): Promise<SongList>;
+    /** Delete a song's audio and analysis now. 409 `still_processing` while it runs. */
+    deleteSong(songId: string): Promise<DeleteResult>;
+    /** Free songs left this month, credit balance and price per song. */
+    account(): Promise<Account>;
+    /** Prices and limits. No key needed. */
+    pricing(): Promise<Pricing>;
+    /** Example analyses of Songbrain's own songs. No key needed. */
+    examples(): Promise<ExampleList>;
+    /** A full example document, in the same format as `getSong`. No key needed. */
+    example(exampleId: string, options?: GetSongOptions): Promise<Song>;
+    /** An example story and shot plan, in the same format as `shotPlan`. No key needed. */
+    exampleShotPlan(exampleId: string): Promise<SongShotPlan>;
+    private backoffMs;
+    private request;
+}
+
+/**
+ * Every API error has the shape `{ error: { code, message } }`. The client
+ * turns it into a `SongbrainError` (or a subclass) with `status`, `code` and
+ * `message`.
+ */
+declare class SongbrainError extends Error {
+    /** HTTP status, or 0 when the error did not come from an HTTP response. */
+    readonly status: number;
+    /** Machine-readable code, e.g. "invalid_url" or "rate_limited". */
+    readonly code: string;
+    /** The parsed response body, when there was one. */
+    readonly body: unknown;
+    constructor(status: number, code: string, message: string, body?: unknown);
+}
+/** 401: the API key is missing, invalid or revoked. */
+declare class AuthenticationError extends SongbrainError {
+}
+/** 402: the free songs for this month are used up and the balance is below one song. */
+declare class InsufficientCredits extends SongbrainError {
+}
+/** 404: unknown id, or the song belongs to another account. */
+declare class NotFound extends SongbrainError {
+}
+/** 429: too many requests, too many songs in flight, daily cap or busy pipeline. */
+declare class RateLimited extends SongbrainError {
+    /** Seconds to wait, from the Retry-After header (null if absent). */
+    readonly retryAfter: number | null;
+    constructor(status: number, code: string, message: string, body?: unknown, retryAfter?: number | null);
+}
+/** The song was accepted but its analysis failed. Paid credits are refunded automatically. */
+declare class AnalysisFailed extends SongbrainError {
+    readonly songId: string;
+    constructor(songId: string, code: string, message: string, body?: unknown);
+}
+/** `analyze({ wait: true })` gave up before the song was done. It keeps processing on the server. */
+declare class WaitTimeout extends SongbrainError {
+    readonly songId: string;
+    constructor(songId: string, timeoutMs: number);
+}
+
+/** The header Songbrain signs webhooks with. */
+declare const SIGNATURE_HEADER = "Songbrain-Signature";
+type RawBody = string | Uint8Array | ArrayBuffer;
+/**
+ * Check a `Songbrain-Signature: t=<unix>,v1=<hex>` header, where v1 is the
+ * HMAC-SHA256 of `"<t>.<raw body>"` with your key's webhook secret.
+ *
+ * Pass the raw request body exactly as received, before any JSON parsing.
+ * Returns false (never throws) for a missing, malformed, wrong or old signature.
+ *
+ * @param toleranceSec Maximum age in seconds (default 300). 0 disables the check.
+ */
+declare function verifyWebhook(rawBody: RawBody, header: string | null | undefined, secret: string, toleranceSec?: number): boolean;
+/**
+ * Verify the signature and return the parsed event:
+ * `{ type: "song.done" | "song.failed" | "account.low_balance", created, data }`.
+ * Throws if the signature is not valid.
+ */
+declare function constructWebhookEvent<T = Record<string, unknown>>(rawBody: RawBody, header: string | null | undefined, secret: string, toleranceSec?: number): WebhookEvent<T>;
+/** Build a signature header value. Useful to test your webhook handler. */
+declare function signWebhook(rawBody: RawBody, secret: string, timestampSec?: number): string;
+
+declare const VERSION = "0.1.0";
+
+export { type Account, type Act, AnalysisFailed, type AnalyzeOptions, AuthenticationError, type BestMoment, type Billing, type CaptionIdeas, type Clip, DEFAULT_BASE_URL, type DeleteResult, type ErrorInfo, type ExampleList, type ExampleSummary, type FileInput, type FullSong, type FullSongSection, type GetSongOptions, type Instrument, InsufficientCredits, type KeyChange, type LoudnessCheck, type LyricHook, type LyricLine, type Lyrics, NotFound, type Phases, type PlatformFit, type Pricing, RateLimited, SIGNATURE_HEADER, type Scene, type SceneKind, type ScoreBlock, type Scores, type Section, type SectionName, type ShotPlan, type ShotStyle, type Song, type SongCreated, type SongDNA, type SongInfo, type SongList, type SongListItem, type SongShotPlan, type SongStatus, Songbrain, SongbrainError, type SongbrainOptions, type SoundsLike, type Story, type StoryBeats, type StoryElement, type Timeline, VERSION, type VocalChange, type WaitOptions, WaitTimeout, type WebhookEvent, type WhatToFix, type WhatWorks, type Word, constructWebhookEvent, signWebhook, verifyWebhook };