@transcodely/sdk 0.3.14 → 0.3.16

package/dist/index.d.cts

@@ -1003,9 +1003,9 @@ interface TranscodelyErrorOptions {
 }
 /** Base class for every error the SDK throws. */
 declare class TranscodelyError extends Error {
-    /** Server-side error code (e.g. "JOB_NOT_FOUND"). */
+    /** Server-side error code (e.g. "validation_error"). */
     readonly code: string | undefined;
-    /** Top-level error type (e.g. "validation_error"). */
+    /** Connect error code (e.g. "invalid_argument"). */
     readonly type: string | undefined;
     /** Field-level validation violations. */
     readonly errors: FieldViolation[];
@@ -1835,9 +1835,10 @@ declare class AutoProfileDefaults extends Message<AutoProfileDefaults> {
      */
     qualityTier?: string;
     /**
-     * Encoding mode: "fixed" (default, static CRF) or "auto" (input-aware constrained CRF).
+     * Encoding mode: "auto" (default, input-aware constrained CRF) or "fixed" (static CRF).
      * In "auto" mode, the worker caps each variant's bitrate based on the input's bitrate
-     * and resolution ratio, preventing output from exceeding the input's quality ceiling.
+     * and resolution ratio, preventing output from exceeding the input's quality ceiling,
+     * and skips any ladder rung larger than the source instead of upscaling it.
      *
      * @generated from field: optional string encoding_mode = 5;
      */
@@ -5442,13 +5443,17 @@ declare enum HDRFormat {
      */
     HDR_FORMAT_HLG = 3,
     /**
-     * Dolby Vision Profile 5 (single-layer, cross-compatible).
+     * Dolby Vision Profile 5 (single-layer, no HDR10 or SDR compatibility
+     * layer). Not available: refused at create with `parameter_unsupported` on
+     * `hdr.format` until the worker produces Dolby Vision output.
      *
      * @generated from enum value: HDR_FORMAT_DOLBY_VISION_5 = 4;
      */
     HDR_FORMAT_DOLBY_VISION_5 = 4,
     /**
-     * Dolby Vision Profile 8 (MEL, backward-compatible with HDR10).
+     * Dolby Vision Profile 8.1 (single-layer, HDR10-compatible base layer). Not
+     * available: refused at create with `parameter_unsupported` on `hdr.format`
+     * until the worker produces Dolby Vision output.
      *
      * @generated from enum value: HDR_FORMAT_DOLBY_VISION_8 = 5;
      */
@@ -5471,11 +5476,14 @@ declare enum HDRMode {
      */
     HDR_MODE_PASSTHROUGH = 1,
     /**
-     * Convert HDR to SDR via tone mapping. Requires an HDR input: whether the
-     * input carries HDR color signaling is only knowable once it has been
-     * probed, so a tone-map job on an SDR source is accepted at create and then
-     * fails at probe time with error code `input_not_hdr`, before any encode
-     * starts.
+     * Convert HDR to SDR via tone mapping. The output is BT.709 (primaries,
+     * transfer and matrix), limited range, 8-bit unless the variant is h265
+     * `main10`, and carries no HDR metadata. Works into every video codec,
+     * because the output is SDR: `format` names the source here, not the output.
+     * Requires an HDR input: whether the input carries HDR color signaling is
+     * only knowable once it has been probed, so a tone-map job on an SDR source
+     * is accepted at create and then fails at probe time with error code
+     * `input_not_hdr`, before any encode starts.
      *
      * @generated from enum value: HDR_MODE_TONEMAP = 2;
      */
@@ -5510,7 +5518,10 @@ declare enum ToneMapping {
      */
     HABLE = 2,
     /**
-     * ITU-R BT.2390 reference. Broadcast (default).
+     * ITU-R BT.2390 reference. Broadcast (default). Approximated with `hable`
+     * on CPU: the worker's tone-mapping filter has no BT.2390 curve, so this
+     * value is encoded with the `hable` operator, the closest available
+     * highlight roll-off.
      *
      * @generated from enum value: TONE_MAPPING_BT2390 = 3;
      */
@@ -5529,7 +5540,11 @@ declare enum ToneMapping {
  */
 declare class HDRConfig extends Message<HDRConfig> {
     /**
-     * Target HDR format (required for passthrough and force modes).
+     * Target HDR format (required for passthrough and force modes). In tonemap
+     * mode it names the HDR format of the source.
+     * `dolby_vision_5` and `dolby_vision_8` are refused at create until the
+     * worker produces Dolby Vision output; a refused request creates no job and
+     * is neither quoted nor billed.
      *
      * @generated from field: transcodely.v1.HDRFormat format = 1;
      */
@@ -5541,14 +5556,17 @@ declare class HDRConfig extends Message<HDRConfig> {
      */
     mode: HDRMode;
     /**
-     * Tone mapping algorithm (for tonemap mode).
+     * Tone mapping algorithm (tonemap mode only). Unset means `bt2390`, which,
+     * like an explicit `bt2390`, is approximated with `hable` on CPU.
      *
      * @generated from field: transcodely.v1.ToneMapping tone_mapping = 3;
      */
     toneMapping: ToneMapping;
     /**
-     * Target peak brightness in nits (for tonemap and force modes).
-     * Range: 100-10000.
+     * Target peak brightness in nits. Range: 100-10000. Applies to HDR output
+     * only: refused with `parameter_forbidden` in tonemap mode, whose SDR target
+     * has a fixed peak. Accepted in passthrough and force modes, where the
+     * encoder does not currently read it, so it has no effect on the output.
      *
      * @generated from field: optional int32 target_peak_nits = 4;
      */
@@ -5568,7 +5586,9 @@ declare class HDRConfig extends Message<HDRConfig> {
      */
     contentLightLevel?: string;
     /**
-     * Dolby Vision RPU file URL (for DV metadata injection).
+     * Dolby Vision RPU file URL. Only accepted with a `dolby_vision_*` format,
+     * which is refused at create until the worker produces Dolby Vision output,
+     * so this field is currently unreachable.
      *
      * @generated from field: optional string rpu_url = 7;
      */
@@ -7003,11 +7023,8 @@ declare class DRMConfig extends Message<DRMConfig> {
 /**
  * Content-aware encoding mode.
  *
- * One of the two modes ships: `per_title` is accepted and acted on. `auto_abr`
- * is still rejected at CreateJob with error code `parameter_unsupported` and
- * the message "auto_abr is not available yet; per_title is" (issue #167),
- * because it would change the NUMBER of renditions after the job was already
- * quoted per rendition at create time.
+ * Both modes are accepted and acted on. `per_title` tunes the ladder you
+ * declare; `auto_abr` builds the ladder from one seed rendition.
  *
  * @generated from enum transcodely.v1.ContentAwareMode
  */
@@ -7027,45 +7044,87 @@ declare enum ContentAwareMode {
      */
     PER_TITLE = 1,
     /**
-     * Generate the bitrate ladder automatically. NOT YET ACCEPTED — rejected at
-     * create.
+     * Choose which rungs of a standard ladder to render, and tune each rung's
+     * CRF to the content.
+     *
+     * You declare a seed (one video rendition giving the codec, quality tier and
+     * optional framerate) and optional bounds (AutoABRConfig). The API expands
+     * the seed into a CEILING: the standard rungs (2160p, 1440p, 1080p, 720p,
+     * 480p) inside the bounds. Tiers are names; nothing is ever upscaled: each
+     * rung renders at the source scaled into its tier's frame (turned on its
+     * side for a portrait source), never larger than the source, and at most
+     * one tier at or above the source's short side is kept, rendered at the
+     * source's own size (a 1920x800 source: 1080p at 1920x800, 720p at
+     * 1280x534, 480p at 854x356; a 1080x1920 phone video: 1080x1920, 720x1280,
+     * 480x854). Each rung is billed at the smaller of its tier and the tier its
+     * rendered pixels need, never above the picture it carries.
+     * Capped at max_variants by keeping the top and bottom rung. The worker runs
+     * the per-title search once on the top rung, sets every rung's CRF from
+     * it, and drops a rung whose
+     * delivered bitrate would not be meaningfully below the rung above it. It
+     * never adds a rung that is not in the ceiling.
+     *
+     * Billing: the output is quoted at the ceiling and billed for the rungs
+     * actually rendered, at the 1.5x content-aware multiplier, so the bill is
+     * never above the estimate shown once the source has been probed. When the
+     * analysis cannot run (for example a source shorter than 120 seconds), the
+     * whole ceiling is rendered at the quality tier's static CRFs and billed at
+     * 1.0x. Streaming outputs (hls, dash, adaptive) only.
+     *
+     * This is not a convex-hull per-title ladder: rungs are not compared against
+     * each other on quality, and no resolution outside the standard set is ever
+     * produced.
      *
      * @generated from enum value: CONTENT_AWARE_MODE_AUTO_ABR = 2;
      */
     AUTO_ABR = 2
 }
 /**
- * Auto ABR ladder generation constraints.
- *
- * NOT YET ACCEPTED — see ContentAwareConfig. These constraints are validated
- * for shape but never applied, because a request in auto_abr mode is rejected
- * at create.
+ * Bounds for an auto_abr ladder. Only meaningful with mode `auto_abr`; sent
+ * with `per_title` it is refused with `parameter_forbidden`. See
+ * CONTENT_AWARE_MODE_AUTO_ABR for how the bounds shape the ladder.
  *
  * @generated from message transcodely.v1.AutoABRConfig
  */
 declare class AutoABRConfig extends Message<AutoABRConfig> {
     /**
-     * Minimum number of variants in the ladder.
-     * Default: 2.
+     * Fewest rungs the ladder may be pruned to. Default: 2.
+     *
+     * A ladder can never hold more rungs than the source allows: only one tier
+     * at or above the source's short side is kept, so a 480-line source yields
+     * one rung whatever this says. When pruning would leave fewer rungs than
+     * this, rungs are put back from the bottom of the ladder up. Set it to 1 to
+     * say a single rung is an acceptable result for any source. Must not exceed
+     * max_variants, nor the number of standard rungs between min_resolution and
+     * max_resolution.
      *
      * @generated from field: optional int32 min_variants = 1;
      */
     minVariants?: number;
     /**
-     * Maximum number of variants in the ladder.
-     * Default: 8.
+     * Most rungs the ladder may hold. A ceiling longer than this keeps its TOP
+     * rung (quality) and its BOTTOM rung (reach) and drops interior rungs from
+     * the highest down: 2160p..480p capped at 3 is 2160p, 720p, 480p. Default:
+     * no cap beyond the standard rungs in range (at most five).
      *
      * @generated from field: optional int32 max_variants = 2;
      */
     maxVariants?: number;
     /**
-     * Lowest resolution in the generated ladder.
+     * Lowest rung the ladder may contain. Default: 480p. When the source's short
+     * side is below this, the ladder is one rung: the smallest tier at or above
+     * the source's short side, rendered at the source's own size.
      *
      * @generated from field: transcodely.v1.Resolution min_resolution = 3;
      */
     minResolution: Resolution;
     /**
-     * Highest resolution in the generated ladder.
+     * Highest rung the ladder may contain. Default: 1080p, NOT the highest the
+     * source allows — 1440p and 2160p rungs must be asked for here. The worker
+     * that renders the job is sized from this ceiling before the source is
+     * known, and a default that sized every job for 4K would bill nobody more
+     * but waste a large machine on most sources. 4320p is accepted and behaves
+     * as 2160p, the largest standard rung.
      *
      * @generated from field: transcodely.v1.Resolution max_resolution = 4;
      */
@@ -7088,14 +7147,28 @@ declare class AutoABRConfig extends Message<AutoABRConfig> {
  * unchanged — same renditions, same resolutions — so the price quoted at create
  * still holds, with the 1.5x per-title multiplier applied.
  *
- * Three requests are refused at create:
- *   - `auto_abr` mode (`parameter_unsupported`) — not available yet;
+ * In `auto_abr` mode the output declares one seed rendition and the API
+ * expands it into a ceiling of standard rungs; see CONTENT_AWARE_MODE_AUTO_ABR.
+ *
+ * Requests refused at create, for `per_title`:
  *   - an output with no video renditions, or one whose every video rendition is
  *     pinned to an explicit bitrate (`parameter_incompatible`) — a pinned
  *     rendition ignores CRF, so the search would change nothing while still
  *     being billed;
- *   - a source shorter than 120 seconds, refused at probe with
- *     `per_title_source_too_short` once the input has been measured.
+ *   - an `auto_abr` block (`parameter_forbidden`).
+ *
+ * For `auto_abr`: a non-streaming output (`parameter_unsupported`); more or
+ * fewer than one video rendition (`parameter_incompatible`); a seed that
+ * names a resolution, width or height (`parameter_forbidden`) or a bitrate
+ * (`parameter_incompatible`); inverted bounds (`parameter_invalid`); and a
+ * min_variants above the standard rungs in range (`parameter_out_of_range`).
+ *
+ * Either mode, on an output with any `hdr.mode: tonemap` variant
+ * (`parameter_forbidden` on `outputs[i].content_aware`): the search would score
+ * the HDR source, not the tone-mapped picture that is delivered.
+ *
+ * A source shorter than 120 seconds is refused at probe with
+ * `per_title_source_too_short` once the input has been measured.
  *
  * What the search decided is reported back on OutputReport.content_aware.
  *
@@ -7103,8 +7176,7 @@ declare class AutoABRConfig extends Message<AutoABRConfig> {
  */
 declare class ContentAwareConfig extends Message<ContentAwareConfig> {
     /**
-     * Encoding mode (required). `per_title` is accepted; `auto_abr` is rejected
-     * at create.
+     * Encoding mode (required): `per_title` or `auto_abr`.
      *
      * @generated from field: transcodely.v1.ContentAwareMode mode = 1;
      */
@@ -7125,8 +7197,8 @@ declare class ContentAwareConfig extends Message<ContentAwareConfig> {
      */
     vmafTarget?: number;
     /**
-     * Auto ABR constraints (only for auto_abr mode). NOT YET ACCEPTED — an
-     * auto_abr request is rejected at create whatever these say.
+     * Ladder bounds, only for `auto_abr` mode. Refused with
+     * `parameter_forbidden` on `per_title`.
      *
      * @generated from field: optional transcodely.v1.AutoABRConfig auto_abr = 3;
      */
@@ -9522,7 +9594,9 @@ declare class OutputSpec extends Message<OutputSpec> {
      * Enables per-title encoding, which tunes this output's CRF to the source
      * rather than to its quality tier. Requires at least one video rendition that
      * is not pinned to an explicit bitrate, and a source of at least 120 seconds.
-     * `auto_abr` mode is not accepted yet.
+     * `auto_abr` mode (choose which rungs of a standard ladder to render, for
+     * streaming outputs) is defined but not accepted yet: it is rejected with
+     * `parameter_unsupported`.
      *
      * @generated from field: optional transcodely.v1.ContentAwareConfig content_aware = 13;
      */
@@ -9531,6 +9605,10 @@ declare class OutputSpec extends Message<OutputSpec> {
      * Encoding mode: "fixed" (default, static CRF) or "auto" (input-aware constrained CRF).
      * In "auto" mode, the worker caps each variant's bitrate based on the input's bitrate
      * and resolution ratio, preventing output from exceeding the input's quality ceiling.
+     * "auto" also skips any ABR rung larger than the source instead of upscaling it.
+     * A skipped rung is reported with status "skipped" and is not billed.
+     * Outputs created since 2026-10-27 echo the resolved mode on responses (unset
+     * resolves to "fixed"). Outputs created before then omit it: their mode was not stored.
      *
      * @generated from field: optional string encoding_mode = 14;
      */
@@ -9761,7 +9839,10 @@ declare class VariantPricingSnapshot extends Message<VariantPricingSnapshot> {
      */
     actualCost?: number;
     /**
-     * Variant encoding status: "pending", "processing", "completed", "failed".
+     * Variant encoding status: "pending", "processing", "completed", "failed",
+     * "canceled", or "skipped". A rung is "skipped" when `encoding_mode: auto`
+     * left it unencoded because it would have upscaled the source. A skipped
+     * rung has actual_cost 0 and is not billed.
      *
      * @generated from field: string status = 20;
      */
@@ -13439,6 +13520,13 @@ declare class UsageSummary extends Message<UsageSummary> {
      */
     storageGbAvg: number;
     /**
+     * Storage cost of the period so far, as your invoice will carry it. Each
+     * day is one GB-day: the day's stored bytes at the day's monthly price
+     * divided by the days in that month. Days already billed are reported at
+     * the rate they were billed at, so a later price or rate-card change never
+     * re-prices them; the remaining days (see hosting_estimated_from) are
+     * estimated the same way at your current rate.
+     *
      * @generated from field: double storage_cost = 11;
      */
     storageCost: number;
@@ -13453,6 +13541,10 @@ declare class UsageSummary extends Message<UsageSummary> {
      */
     egressGb: number;
     /**
+     * Delivery cost of the period so far, as your invoice will carry it:
+     * billed delivery at the rate it was billed at, delivery not billed yet
+     * estimated at your current rate.
+     *
      * @generated from field: double egress_cost = 21;
      */
     egressCost: number;
@@ -13472,6 +13564,18 @@ declare class UsageSummary extends Message<UsageSummary> {
      * @generated from field: string currency = 31;
      */
     currency: string;
+    /**
+     * First day (YYYY-MM-DD, UTC) whose storage or delivery cost is an
+     * estimate rather than billed usage. Hosting is billed daily, through the
+     * previous day, so while you store or deliver video the current period has
+     * an estimated tail, and the estimate turns into the billed amount as each
+     * day is billed. Empty when no day with hosting usage in the period is
+     * still unbilled, which is when storage_cost and egress_cost match your
+     * invoice (to within the sub-cent remainder carried to the next charge).
+     *
+     * @generated from field: string hosting_estimated_from = 32;
+     */
+    hostingEstimatedFrom: string;
     /**
      * Per-day usage breakdown for the billing period identified by
      * billing_month, oldest day first. With a billing anchor day other than 1,
@@ -18005,7 +18109,7 @@ interface SerializeOptions {
 declare function toWireJson<T extends Message<T>>(msg: T, opts?: SerializeOptions): JsonValue;
 
 /** SDK version. Bumped by release-please from package.json on each tag. */
-declare const SDK_VERSION = "0.3.14";
+declare const SDK_VERSION = "0.3.16";
 /**
  * API version this SDK release is pinned to. Sent on every request as
  * `Transcodely-Version`. Customers can override per-client via the