@omelhorsite/sdk 0.1.0

package/dist/types/resources/tools/jumpstyle.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Jumpstyle edits: a track plus a pile of clips, cut to the beat.
+ *
+ * The odd one out of the tool family in three ways. Its quota is metered in
+ * finished EDITS, not seconds, so it uses {@link EditsQuota}. Its create call
+ * is a multi-file form: one `track` plus a `clips[]` array. And its row has no
+ * `"pending"` state at all - the controller forwards the files to the sidecar
+ * inside the request and saves the row already `"processing"`, so a create that
+ * returns at all has work under way.
+ *
+ * Limits, all enforced by the backend:
+ *
+ * | | |
+ * |---|---|
+ * | track | 30 MiB, and the MIME type must be `audio/*` |
+ * | each clip | 120 MiB, and the MIME type must be `video/*` or `image/*` |
+ * | whole upload | 400 MiB |
+ * | clips | 20 |
+ * | output length | clamped to `[10, 60]` seconds |
+ * | daily quota, anonymous | 3 edits |
+ * | daily quota, signed in | 15 edits |
+ * | `POST /jumpstyle_jobs` | 20 a minute, shared with every other expensive tool |
+ *
+ * The MIME checks read the `contentType` on each {@link FileInput}, which the
+ * SDK sends as the part's `Content-Type`. A file handed over with the wrong one
+ * - or with none, which some hosts do for an unknown extension - is a 400 that
+ * has nothing to do with the bytes.
+ *
+ * Read {@link JumpstyleNamespace.quota} before uploading. It is the cheapest
+ * preflight in the family, because one invocation is exactly one edit: if
+ * `remaining_edits` is `0`, the upload cannot succeed.
+ */
+import { Resource } from "../../http";
+import type { FileInput, Id, RequestOptions } from "../../types";
+import { type EditsQuota, type ToolCaptcha, type ToolRecord, type ToolRunOptions } from "./index";
+/**
+ * How busy the cut is, in the sidecar's own words.
+ *
+ * `chill` cuts once a phrase, `normal` is the default, `hyper` cuts on
+ * subdivisions and is what the tool did before the setting existed.
+ *
+ * Get this wrong and nothing tells you: the controller replaces an
+ * unrecognised value with `"normal"` rather than refusing it, so a plausible
+ * synonym is a silent no-op that costs a whole edit to discover.
+ */
+export type JumpstyleDensity = "chill" | "normal" | "hyper";
+/** The three the backend accepts. Anything else is silently read as `"normal"`. */
+export declare const JUMPSTYLE_DENSITIES: readonly JumpstyleDensity[];
+/** A jumpstyle edit. */
+export interface JumpstyleJob extends ToolRecord {
+    readonly track_filename?: string | null;
+    readonly n_clips?: number | null;
+    /** Seconds of output. */
+    readonly duration?: number | null;
+    /** The seed that produced this cut. Reuse it to reproduce the edit. */
+    readonly seed?: number | null;
+    readonly density?: string | null;
+    readonly rapid_fire?: boolean | null;
+    /** BPM that was forced, when one was. */
+    readonly bpm?: number | null;
+    /** BPM the sidecar detected, or the forced one once the run settles. */
+    readonly detected_bpm?: number | null;
+    /** What the sidecar is doing right now. `null` unless processing. */
+    readonly stage?: string | null;
+    /** The finished video, once the status is `"complete"`. */
+    readonly output_url?: string | null;
+}
+/** Arguments for starting an edit. */
+export interface CreateJumpstyleInput extends ToolCaptcha {
+    /** The music. Must be `audio/*`. Backend cap: 30 MiB. */
+    readonly track: FileInput;
+    /** Footage to cut. Must be `video/*` or `image/*`. At most 20, 120 MiB each. */
+    readonly clips: FileInput[];
+    /**
+     * Seconds of output. Clamped by the server to `[10, 60]`.
+     *
+     * Omitting it is NOT the same as leaving it to a server default: the
+     * controller reads a missing value as `0` and then clamps, so an omitted
+     * duration produces a 10-second edit. Pass one.
+     */
+    readonly duration?: number;
+    /**
+     * Reproducibility seed. Omit and the server rolls one; read it back off the
+     * finished row to make the same cut again. Taken modulo 100000.
+     */
+    readonly seed?: number;
+    /** Defaults to `"normal"`. An unknown value is silently replaced by it. */
+    readonly density?: JumpstyleDensity;
+    /** Cuts on every beat rather than every phrase. */
+    readonly rapidFire?: boolean;
+    /**
+     * Forces the tempo. Pass it ONLY when detection has already failed; the
+     * server clamps it to `[100, 220]`.
+     */
+    readonly bpm?: number;
+}
+/** The `jumpstyle` tool, reachable as `oms.tools.jumpstyle`. */
+export declare class JumpstyleNamespace extends Resource {
+    /**
+     * `GET /jumpstyle_jobs/quota` - edits spent and left today.
+     *
+     * Cheap and anonymous-safe. The only quota in the family counted in whole
+     * units, which makes the preflight exact: one call to {@link create} spends
+     * exactly one edit, so `remaining_edits === 0` means the next upload fails.
+     *
+     * `limit_edits` and `remaining_edits` are `null` exactly when `unlimited` is
+     * `true`. A failed edit does not count against the day.
+     */
+    quota(options?: RequestOptions): Promise<EditsQuota>;
+    /**
+     * `POST /jumpstyle_jobs` - uploads the track and the clips, enqueues the cut.
+     *
+     * The clips go up as a `clips[]` array, which is how Rails reads a list; the
+     * transport appends the suffix itself, so pass a plain array.
+     *
+     * The files are forwarded to the sidecar INSIDE this request, which is why it
+     * is the slowest create in the family - up to 400 MiB moves twice before it
+     * answers - and why the row comes back already `"processing"` rather than
+     * `"pending"`. If the sidecar refuses, the row is destroyed rather than left
+     * dangling, so a failure here leaves nothing to clean up.
+     *
+     * NOT retried by default: replaying this `POST` after a 502 re-uploads the
+     * whole pile and spends a second edit. Pass `retry: {}` to opt back in.
+     *
+     * @throws {OmsQuotaError} 429 when the daily edits are spent. The message is
+     *   a bare string with no `Retry-After`, so `retryAfterMs` is `undefined` -
+     *   the wait is until midnight. The expensive-tools throttle, also a 429,
+     *   DOES set it.
+     * @throws {OmsApiError} 413 when a file or the total is over a cap, 400 for a
+     *   wrong MIME type, no clips, or more than 20 of them, 503 when the edit
+     *   sidecar is down.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
+     */
+    create(input: CreateJumpstyleInput, options?: RequestOptions): Promise<JumpstyleJob>;
+    /**
+     * `GET /jumpstyle_jobs/:id` - one poll, carrying `stage` and
+     * `progress_percent` while the sidecar works.
+     *
+     * Both are read live off the sidecar and are `null` the moment the row
+     * settles - at which point `detected_bpm` stops being the sidecar's guess
+     * and becomes whatever was saved on the row.
+     *
+     * @throws {OmsApiError} 404 once the 24-hour retention sweep has taken it.
+     * @throws {OmsAuthError} 401 when the job belongs to someone else, which
+     *   includes an anonymous job being read from a different address.
+     */
+    get(id: Id, options?: RequestOptions): Promise<JumpstyleJob>;
+    /**
+     * Uploads, waits, and returns the finished row.
+     *
+     * The wait is {@link get} on a loop, driven by `pollUntilTerminal` from the
+     * jobs module - the same loop every other tool uses.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the work failed.
+     * Pass `waitTimeoutMs` (or a `signal`) to bound the wait; there is no default
+     * deadline.
+     *
+     * Read {@link JumpstyleJob.seed} off the row that comes back: it is the only
+     * way to reproduce a cut you liked, and the server rolls a fresh one every
+     * time it is not given one.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the run: pick it
+     *   up later with {@link get}.
+     */
+    run(input: CreateJumpstyleInput, options?: ToolRunOptions): Promise<JumpstyleJob>;
+    /**
+     * `DELETE /jumpstyle_jobs/:id`.
+     *
+     * @throws {OmsApiError} 404 when it is already gone.
+     * @throws {OmsAuthError} 401 when the job belongs to someone else.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * Downloads the finished video.
+     *
+     * Two calls: one to read the row for its `output_url`, one to fetch the
+     * signed URL itself with NO credential attached. Hand a row you already hold
+     * to {@link outputUrl} plus `fetchToolArtifact` if you would rather not pay
+     * for the first.
+     *
+     * @throws {OmsError} `conflict` when the edit has not finished,
+     *   `invalid_request` when it failed, `not_found` when the artefact is gone.
+     */
+    download(id: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The signed URL of the finished video, from a row you already hold.
+     *
+     * It is a credential: anyone holding it can watch the video.
+     *
+     * @throws {OmsError} explaining which of the three reasons there is no URL.
+     */
+    outputUrl(record: JumpstyleJob): string;
+}

package/dist/types/resources/tools/transcription.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Transcription: speech to text, with SRT and VTT subtitle output.
+ *
+ * Runs on the `transcriber` service, which is the ONLY place whisper lives in
+ * this project. No other sidecar embeds it, and no client should call whisper
+ * directly; that rule is deliberate and predates this SDK.
+ *
+ * The quota is metered in seconds of audio, so it is charged on the file's
+ * duration at create time, not on how long the run takes. A file whose
+ * duration alone exceeds the daily ceiling is a 400, not a 429: it can never
+ * fit, no matter how long you wait.
+ *
+ * Limits, all enforced by the backend:
+ *
+ * | | |
+ * |---|---|
+ * | file size | 250 MiB (`413`) |
+ * | daily quota, anonymous | 15 minutes of audio |
+ * | daily quota, signed in | 60 minutes of audio |
+ * | `POST /transcriptions` | 20 a minute, shared with every other expensive tool |
+ *
+ * The daily quota is per user when signed in and per IP when not, and an
+ * account can be given a bigger one - or none at all, in which case
+ * {@link SecondsQuota.unlimited} is `true` and the numbers mean nothing. Read
+ * {@link TranscriptionNamespace.quota} before uploading; it is cheap, it works
+ * anonymously, and it is the difference between a refusal and 250 MiB spent on
+ * a 429.
+ *
+ * The 20-a-minute throttle is shared across background removal, upscale,
+ * transcription, vocal separation, captions, jumpstyle and the downloader, and
+ * it is keyed on the credential when there is one and on the IP when there is
+ * not. It answers 429 with a `Retry-After`, which the transport honours, so a
+ * caller that hits it waits rather than failing - unless it passed
+ * `retry: false`, which {@link TranscriptionNamespace.create} does by default.
+ */
+import { Resource } from "../../http";
+import type { FileInput, Id, RequestOptions } from "../../types";
+import { type SecondsQuota, type ToolCaptcha, type ToolModel, type ToolRecord, type ToolRunOptions } from "./index";
+/** A transcription run. */
+export interface Transcription extends ToolRecord {
+    readonly model_id: string;
+    /** Audio duration charged against the quota. */
+    readonly duration_seconds: number;
+    /** Language that was requested, or `null` when it was auto-detected. */
+    readonly language?: string | null;
+    /** Language the model actually detected. */
+    readonly detected_language?: string | null;
+    readonly has_original?: boolean;
+    /** The transcript. Only shipped once the status is `"complete"`. */
+    readonly text?: string | null;
+    /** SubRip subtitles, once complete. */
+    readonly srt_url?: string | null;
+    /** WebVTT subtitles, once complete. */
+    readonly vtt_url?: string | null;
+}
+/** Arguments for starting a transcription. */
+export interface CreateTranscriptionInput extends ToolCaptcha {
+    /** The audio. Sent as the `audio` form field. Backend cap: 250 MiB. */
+    readonly audio: FileInput;
+    /** Model to use. Omit for the one flagged `default` in {@link TranscriptionNamespace.models}. */
+    readonly modelId?: string;
+    /** ISO language hint. Omit to let the model detect it. */
+    readonly language?: string;
+}
+/** Which subtitle format {@link TranscriptionNamespace.subtitles} should fetch. */
+export type SubtitleFormat = "srt" | "vtt";
+/** The `transcription` tool, reachable as `oms.tools.transcription`. */
+export declare class TranscriptionNamespace extends Resource {
+    /**
+     * `GET /transcriptions/models` - the selectable models.
+     *
+     * The controller answers `{ models: [...] }`; this unwraps it, because a
+     * one-key envelope is not information a caller should have to know about.
+     * Exactly one entry carries `default: true`, and that is the model the
+     * server picks when {@link CreateTranscriptionInput.modelId} is omitted.
+     *
+     * `translation_key` is an i18n key, not a display name. The SDK does not
+     * translate; render the id if you have no catalogue.
+     */
+    models(options?: RequestOptions): Promise<ToolModel[]>;
+    /**
+     * `GET /transcriptions/quota` - seconds spent and left today.
+     *
+     * Cheap and anonymous-safe. Call it before a long file rather than
+     * discovering the ceiling through a 429 after the upload.
+     *
+     * `limit_seconds` and `remaining_seconds` are `null` exactly when
+     * `unlimited` is `true`; `used_seconds` is always a real number. The window
+     * is a calendar day, so "remaining" is not a rate - it does not tick back up
+     * until midnight.
+     */
+    quota(options?: RequestOptions): Promise<SecondsQuota>;
+    /**
+     * `POST /transcriptions` - uploads the audio and enqueues the run.
+     *
+     * Answers with the row in `"pending"`. There is no `job_id` here: this tool
+     * is polled by re-reading its own row with {@link get}, which is what
+     * {@link run} does.
+     *
+     * NOT retried by default, unlike most of the SDK. The transport's policy
+     * replays a `POST` that died with a 502, and here that would re-upload up to
+     * 250 MiB and start a second run - charged twice against the daily quota.
+     * Pass `retry: {}` to opt back in.
+     *
+     * `modelId` and `language` are omitted from the form when absent rather than
+     * sent empty, so the server applies its own defaults.
+     *
+     * @throws {OmsQuotaError} 429 when the daily seconds are spent, or when the
+     *   20-a-minute expensive-tools throttle fires. Only the throttle sets
+     *   `Retry-After`, so `retryAfterMs` being `undefined` means the wait is
+     *   until midnight, not seconds.
+     * @throws {OmsApiError} 413 when the file is over 250 MiB. 400 when the file
+     *   is missing, undecodable, names an unknown model, or is longer on its own
+     *   than the whole daily quota.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
+     */
+    create(input: CreateTranscriptionInput, options?: RequestOptions): Promise<Transcription>;
+    /**
+     * `GET /transcriptions/:id` - one poll. Carries `progress_percent` while
+     * processing and the text once complete.
+     *
+     * `text`, `srt_url` and `vtt_url` are `null` until the status is
+     * `"complete"` - deliberately, so that polling a long run does not drag the
+     * whole transcript across the wire every few seconds.
+     *
+     * Ownership is the caller's session, or - for an anonymous run - the IP the
+     * run was started from.
+     *
+     * @throws {OmsApiError} 404 once the 24-hour retention sweep has taken it.
+     * @throws {OmsAuthError} 401 when the run belongs to someone else, which
+     *   includes an anonymous run being read from a different address.
+     */
+    get(id: Id, options?: RequestOptions): Promise<Transcription>;
+    /**
+     * Uploads, waits, and returns the finished row with its text.
+     *
+     * There is no `job_id` for this tool, so the wait is {@link get} on a loop -
+     * but the loop itself is `pollUntilTerminal` from the jobs module, the same
+     * one every other tool uses. Nothing here opens a second one.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the work failed:
+     * the request cycle worked, the work did not, and only the caller knows
+     * whether that is an exception. Check `status` before reading `text`.
+     *
+     * Pass `waitTimeoutMs` (or a `signal`) to bound the wait; there is no default
+     * deadline, because a two-hour file is a legitimate run.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the run: pick it
+     *   up later with {@link get}.
+     */
+    run(input: CreateTranscriptionInput, options?: ToolRunOptions): Promise<Transcription>;
+    /**
+     * Downloads the subtitles of a finished run.
+     *
+     * Two calls: one to read the row for the format's URL, one to fetch the
+     * signed URL itself with NO credential attached. Hand a row you already hold
+     * to {@link subtitleUrl} plus `fetchToolArtifact` if you would rather not pay
+     * for the first.
+     *
+     * For the plain transcript there is nothing to download: it rides on the row
+     * as {@link Transcription.text} once the run completes.
+     *
+     * @throws {OmsError} `conflict` when the run has not finished,
+     *   `invalid_request` when it failed, `not_found` when the artefact is gone -
+     *   which after 24 hours means the retention sweep took it.
+     */
+    subtitles(id: Id, format: SubtitleFormat, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The signed URL of one subtitle format, from a row you already hold.
+     *
+     * Good for handing to a player or a browser instead of moving the bytes. It
+     * is a credential: anyone holding it can read the subtitles.
+     *
+     * @throws {OmsError} explaining which of the three reasons there is no URL.
+     */
+    subtitleUrl(record: Transcription, format: SubtitleFormat): string;
+}

package/dist/types/resources/tools/upscale.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Upscaling: enlarges an image without turning it to mush.
+ *
+ * Same shape as background removal: `POST /upscales` enqueues a proxy job and
+ * answers with a row plus a `job_id` and, when anonymous, a `watch_token`.
+ *
+ * Backend limits: 20 MiB, and the scale must be one the upscaler advertises.
+ *
+ * Like background removal, this tool is not metered by the `Quotas` catalogue,
+ * so there is no `quota()` to call first.
+ */
+import { Resource } from "../../http";
+import type { FileInput, Id, RequestOptions } from "../../types";
+import { type ToolCaptcha, type ToolJobHandle, type ToolRecord, type ToolRunOptions } from "./index";
+/**
+ * Enlargement factor, as the string the API expects.
+ *
+ * A string and not a number because the backend compares it against an
+ * allow-list of strings; `4` and `"4"` are not the same request.
+ */
+export type UpscaleScale = "2" | "3" | "4";
+/** An upscale run. */
+export interface Upscale extends ToolRecord {
+    readonly scale: string;
+    /** URL of the enlarged image, once the status is `"complete"`. */
+    readonly result_url?: string | null;
+}
+/** What `POST /upscales` answers with. */
+export type UpscaleCreated = Upscale & ToolJobHandle;
+/** Arguments for starting a run. */
+export interface CreateUpscaleInput extends ToolCaptcha {
+    /** The image. Backend cap: 20 MiB. */
+    readonly file: FileInput;
+    /** Defaults to `"4"`, which is what the backend picks when none is sent. */
+    readonly scale?: UpscaleScale;
+}
+/** The `upscale` tool, reachable as `oms.tools.upscale`. */
+export declare class UpscaleNamespace extends Resource {
+    /**
+     * The one polling loop, reached through the jobs namespace. Built here for
+     * the same reason as in every other tool: the constructor stays
+     * one-argument, and the wrapper is stateless.
+     */
+    private readonly jobs;
+    /**
+     * `POST /upscales` - enqueues a run and returns straight away.
+     *
+     * `scale` is omitted from the form when the caller did not pick one, so the
+     * server applies its own default rather than the SDK guessing at it.
+     *
+     * NOT retried by default: replaying this `POST` after a 502 re-uploads the
+     * image and starts a second run. Pass `retry: {}` to opt back in.
+     *
+     * @throws {OmsApiError} 400 for an oversized image, an image bomb, or a
+     *   scale outside the allow-list.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
+     */
+    create(input: CreateUpscaleInput, options?: RequestOptions): Promise<UpscaleCreated>;
+    /**
+     * `GET /upscales/:id` - one poll.
+     *
+     * @throws {OmsApiError} 404 once the 24-hour retention sweep has taken it.
+     * @throws {OmsAuthError} 401 when the run belongs to someone else, which
+     *   includes an anonymous run being read from a different address.
+     */
+    get(id: Id, options?: RequestOptions): Promise<Upscale>;
+    /**
+     * Creates a run and waits for it, through `oms.jobs.wait`.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the work failed.
+     * Pass `waitTimeoutMs` (or a `signal`) to bound the wait; there is no default
+     * deadline.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the run: pick it
+     *   up later with {@link get}.
+     */
+    run(input: CreateUpscaleInput, options?: ToolRunOptions): Promise<Upscale>;
+    /**
+     * Downloads the enlarged image of a finished run.
+     *
+     * @throws {OmsError} `conflict` when the run has not finished,
+     *   `invalid_request` when it failed, `not_found` when the artefact is gone.
+     */
+    download(id: Id, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The signed URL of a finished run's image, from a row you already hold.
+     *
+     * It is a credential: anyone holding it can read the image.
+     *
+     * @throws {OmsError} explaining which of the three reasons there is no URL.
+     */
+    resultUrl(record: Upscale): string;
+}

package/dist/types/resources/tools/vocalSeparation.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Vocal separation: splits a track into a vocals stem and an instrumental.
+ *
+ * Runs are serialised against a single sidecar, so a pending row reports
+ * {@link VocalSeparation.queue_position} - how many live runs entered the queue
+ * ahead of it, `0` meaning next up. Surface it: on a busy day the wait is the
+ * queue, not the model. {@link vocalSeparationProgress} folds it into the
+ * progress line for exactly that reason.
+ *
+ * There is a second door onto the same machinery, `POST /songs/:id/separate`,
+ * which separates a track already in the music library and leaves the stems on
+ * the song rather than as attachments. Both doors share one daily ceiling, and
+ * both are behind the same expensive-tools throttle - the twin was added to
+ * that throttle only after a load generator drove it on its own and pushed the
+ * box into swap.
+ *
+ * Limits, all enforced by the backend:
+ *
+ * | | |
+ * |---|---|
+ * | file size | 100 MiB (`413`) |
+ * | daily quota, anonymous | 12 minutes of audio |
+ * | daily quota, signed in | 30 minutes of audio |
+ * | `POST /vocal_separations` | 20 a minute, shared with every other expensive tool |
+ *
+ * The quota is metered in seconds of audio and charged on the file's duration
+ * at create time, not on how long the run takes - which matters here more than
+ * anywhere else, because this is the slowest tool in the family. Read
+ * {@link VocalSeparationNamespace.quota} before uploading; it is cheap, it
+ * works anonymously, and a track longer than the whole daily ceiling is a 400
+ * that no amount of waiting fixes.
+ */
+import { Resource } from "../../http";
+import type { FileInput, Id, Progress, RequestOptions } from "../../types";
+import { type SecondsQuota, type ToolCaptcha, type ToolModel, type ToolRecord, type ToolRunOptions } from "./index";
+/** Which stem to fetch. */
+export type VocalStem = "vocals" | "instrumental";
+/** A vocal separation run. */
+export interface VocalSeparation extends ToolRecord {
+    readonly model_id: string;
+    /** Audio duration charged against the quota. */
+    readonly duration_seconds: number;
+    /** Set when the run came from the music library rather than an upload. */
+    readonly song_id?: Id | null;
+    readonly song_title?: string | null;
+    readonly has_original?: boolean;
+    readonly has_vocals?: boolean;
+    readonly has_instrumental?: boolean;
+    /**
+     * Live runs queued ahead of this one; `0` means next up. `null` once the run
+     * is processing or terminal.
+     */
+    readonly queue_position?: number | null;
+    /**
+     * Stem URLs, once complete. Both stay `null` for a song-owned separation,
+     * whose stems live on the song as filesystem nodes instead.
+     */
+    readonly vocals_url?: string | null;
+    readonly instrumental_url?: string | null;
+}
+/** Arguments for starting a separation. */
+export interface CreateVocalSeparationInput extends ToolCaptcha {
+    /** The audio. Sent as the `audio` form field. Backend cap: 100 MiB. */
+    readonly audio: FileInput;
+    /** Model to use. Omit for the one flagged `default` in {@link VocalSeparationNamespace.models}. */
+    readonly modelId?: string;
+}
+/**
+ * Renders a separation as a {@link Progress}, queue position included.
+ *
+ * Identical to the shared `toolProgress` except while the run is queued, where
+ * the position is folded into `status` - `"pending (2 ahead in the queue)"`.
+ * That is a deliberate liberty with a field documented as the server's own
+ * status string: `status` is the only part of a {@link Progress} a host
+ * renders as text, and "pending" for forty minutes with no explanation is the
+ * single worst thing this tool does to a person watching it.
+ */
+export declare function vocalSeparationProgress(record: VocalSeparation): Progress;
+/** The `vocalSeparation` tool, reachable as `oms.tools.vocalSeparation`. */
+export declare class VocalSeparationNamespace extends Resource {
+    /**
+     * `GET /vocal_separations/models` - the selectable models.
+     *
+     * The controller answers `{ models: [...] }`; this unwraps it. Exactly one
+     * entry carries `default: true`, and that is what the server picks when
+     * {@link CreateVocalSeparationInput.modelId} is omitted.
+     *
+     * The models differ in cost as well as quality - the default is the heaviest
+     * of them - but the API exposes no such ranking, so there is nothing here to
+     * choose on but the id.
+     */
+    models(options?: RequestOptions): Promise<ToolModel[]>;
+    /**
+     * `GET /vocal_separations/quota` - seconds spent and left today.
+     *
+     * Cheap and anonymous-safe. `limit_seconds` and `remaining_seconds` are
+     * `null` exactly when `unlimited` is `true`. The window is a calendar day, so
+     * "remaining" is not a rate: it does not tick back up until midnight.
+     *
+     * This ceiling is shared with `POST /songs/:id/separate`, so a separation
+     * started from the music library spends the same budget.
+     */
+    quota(options?: RequestOptions): Promise<SecondsQuota>;
+    /**
+     * `POST /vocal_separations` - uploads the audio and enqueues the run.
+     *
+     * Answers with the row in `"pending"`, already carrying its
+     * {@link VocalSeparation.queue_position}. There is no `job_id` here: this
+     * tool is polled by re-reading its own row with {@link get}.
+     *
+     * NOT retried by default: replaying this `POST` after a 502 re-uploads up to
+     * 100 MiB, charges the quota twice, and puts a second run behind the first in
+     * a queue that is already the slowest thing in the API. Pass `retry: {}` to
+     * opt back in.
+     *
+     * @throws {OmsQuotaError} 429 for the daily ceiling or the expensive-tools
+     *   throttle. Read `retryAfterMs`; the throttle sets it, the daily ceiling
+     *   does not, so `undefined` means the wait is until midnight.
+     * @throws {OmsApiError} 413 when the file is over 100 MiB. 400 when it is
+     *   missing, undecodable, names an unknown model, or is longer on its own
+     *   than the whole daily quota.
+     * @throws {OmsAuthError} 401 when anonymous and the captcha is missing or bad.
+     */
+    create(input: CreateVocalSeparationInput, options?: RequestOptions): Promise<VocalSeparation>;
+    /**
+     * `GET /vocal_separations/:id` - one poll, carrying `queue_position` while
+     * pending and `progress_percent` while processing.
+     *
+     * Never both: the position is `null` from the moment the sidecar picks the
+     * run up, and the percentage is `null` before that and after it finishes.
+     *
+     * @throws {OmsApiError} 404 once the 24-hour retention sweep has taken it.
+     * @throws {OmsAuthError} 401 when the run belongs to someone else, which
+     *   includes an anonymous run being read from a different address.
+     */
+    get(id: Id, options?: RequestOptions): Promise<VocalSeparation>;
+    /**
+     * Uploads, waits, and returns the finished row.
+     *
+     * The wait is {@link get} on a loop, driven by `pollUntilTerminal` from the
+     * jobs module - the same loop every other tool uses. Progress reports carry
+     * the queue position while the run is still waiting its turn; see
+     * {@link vocalSeparationProgress}.
+     *
+     * Resolves with a `"failed"` row rather than throwing when the work failed.
+     * Pass `waitTimeoutMs` (or a `signal`) to bound the wait; there is no default
+     * deadline, and this is the tool where that matters most - a busy queue plus
+     * a long track is comfortably an hour.
+     *
+     * @throws {OmsTimeoutError} `code: "timeout"` when `waitTimeoutMs` elapses,
+     *   `code: "aborted"` when the signal fires. Neither cancels the run: pick it
+     *   up later with {@link get}.
+     */
+    run(input: CreateVocalSeparationInput, options?: ToolRunOptions): Promise<VocalSeparation>;
+    /**
+     * Downloads one stem of a finished run.
+     *
+     * Two calls: one to read the row for the stem's URL, one to fetch the signed
+     * URL itself with NO credential attached. Hand a row you already hold to
+     * {@link stemUrl} plus `fetchToolArtifact` if you would rather not pay for
+     * the first.
+     *
+     * @throws {OmsError} `not_found` for a song-owned separation, whose stems are
+     *   not attachments at all; read them through the music library instead.
+     *   `conflict` when the run has not finished, `invalid_request` when it
+     *   failed, `not_found` again once the 24-hour sweep has taken the stems.
+     */
+    download(id: Id, stem: VocalStem, options?: RequestOptions): Promise<Blob>;
+    /**
+     * The signed URL of one stem, from a row you already hold.
+     *
+     * Good for handing to a player instead of moving the bytes. It is a
+     * credential: anyone holding it can read the stem.
+     *
+     * A song-owned separation is answered separately and first, because
+     * otherwise it looks exactly like a swept artefact - complete, no URL - and
+     * the caller would be told to blame a retention sweep for a run whose stems
+     * were never attachments in the first place.
+     *
+     * @throws {OmsError} explaining which of the four reasons there is no URL.
+     */
+    stemUrl(record: VocalSeparation, stem: VocalStem): string;
+}