#Changelog

A record of notable changes to the Transcodely API. We follow Semantic Versioning — breaking changes will always be announced in advance and accompanied by a migration guide.

#Versioning Policy

The Transcodely API uses a single stable version (v1) at the endpoint level. Changes within v1 follow these rules:

Backward-compatible changes are shipped continuously without version bumps. Breaking changes would result in a new API version (e.g., v2).

#2026-03-16

#Added

• Subtitles — Full subtitle processing support via subtitle_tracks on output specifications. Four operations: passthrough, convert, burn_in, and extract. Supports SRT, WebVTT, TTML, and ASS formats with configurable burn-in styling (font, color, outline, positioning). Source from embedded streams or external URLs.
• DRM & Encryption — Content protection for streaming outputs (HLS, DASH, adaptive) via the drm field on output specifications. Supports Widevine, FairPlay, and PlayReady with CENC and CBCS encryption schemes. Two key management modes: Bring Your Own Key (BYOK) and key server integration. Configurable clear lead for ad insertion.
• HDR processing — Per-variant HDR configuration via the hdr field on video variants. Supports HDR10, HDR10+, HLG, and Dolby Vision (profiles 5 and 8). Three processing modes: passthrough (preserve), tonemap (HDR to SDR conversion with Reinhard, Hable, BT.2390, or Mobius algorithms), and force (inject metadata). Compatible with H.265, VP9, and AV1 codecs.
• Content-aware encoding — Intelligent bitrate optimization via the content_aware field on output specifications. Two modes: per_title (optimizes bitrates for your existing ABR ladder to meet a VMAF target) and auto_abr (automatically generates the optimal ABR ladder based on content analysis). Default VMAF targets: economy 88, standard 93, premium 97.
• Thumbnails — Thumbnail generation via the thumbnails array on job creation (max 5 specs per job). Four extraction modes: single (poster frame), interval (periodic), sprite (sprite sheet with WebVTT for seek preview), and timestamps (specific moments). Supports JPEG, PNG, and WebP output.
• Feature-based pricing — Add-on features now carry cost multipliers: DRM (1.25x), HDR (1.40x), content-aware encoding (1.15x), thumbnails (1.10x). The feature_multiplier field in pricing snapshots reflects the combined multiplier. Multiple features stack multiplicatively.
• Codec-specific options — Video variants now accept codec-specific configuration objects (h264, h265, vp9, av1) for fine-grained encoder control: presets, profiles, levels, CRF, bitrate modes, keyframe intervals, B-frames, reference frames, adaptive quantization, psychovisual optimization, tiling, film grain synthesis, and loop filters.

#2026-02-15

#Added

• Real-time job watching — JobService/Watch streams live updates as a job progresses through its lifecycle. Includes snapshot, progress, status_change, completed, and heartbeat event types.
• Execution timing — Jobs now include an execution field with detailed timing telemetry: boot, download, probe, encode, upload, and packaging durations, plus worker instance details and resource usage metrics.
• Chunk encoding telemetry — execution.chunk_count and execution.chunk_strategy fields report parallel encoding details when chunk encoding is used.

#2026-02-01

#Added

• Output path templates — 4-level template hierarchy for controlling where transcoded files are written: per-output, job-level, origin, and system default. Supports variables like {job_id}, {codec}, {resolution}, {date}.
• Collision auto-fix — Implicit path templates (origin or system default) that would produce duplicate paths are automatically fixed by appending /{output_id}.
• Custom manifest names — HLS and DASH outputs now support custom manifest file names via hls.manifest and dash.manifest fields.

#Improved

• Streaming outputs — HLS and DASH outputs now use a structured segments config with duration and gop_alignment fields, replacing the deprecated segment_duration field.

#2026-01-15

#Added

• Per-variant pricing — ABR outputs (HLS/DASH with multiple video variants) now include a variant_pricing array with per-variant cost breakdowns, status, and progress tracking.
• Delayed start — Jobs can be created with delayed_start: true to pause after input probing. The awaiting_confirmation status lets you review estimated costs before calling Confirm to proceed.
• Job confirmation — JobService/Confirm endpoint for starting delayed-start jobs after cost review.

#2026-01-10

#Added

• Adaptive output format — New adaptive output type that produces both HLS (master.m3u8) and DASH (manifest.mpd) manifests from shared CMAF segments.
• Multi-audio tracks — Streaming outputs (HLS, DASH, adaptive) now support multiple audio tracks with language codes and labels via the audio array.
• Video variants — Inline output specification using the video[] array for defining ABR ladders without presets.

#2026-01-05

#Added

• Origins — OriginService for managing storage locations (GCS, S3, HTTP) with credential validation, base paths, and path templates.
• Origin-based job input — Jobs can now reference an origin via input_origin_id and input_path instead of providing a direct input_url.
• Origin-based job output — output_origin_id specifies where transcoded files should be written.

#2025-12-20

#Added

• Preset duplication — PresetService/Duplicate clones any preset (system or custom) as a new custom preset with a new slug.
• Preset by slug — PresetService/GetBySlug looks up a preset using its slug identifier.
• Content types — Presets now support a content_type field for encoder tuning (film, animation, grain, gaming, sports, stillimage).

#2025-12-15

#Added

• Idempotency keys — CreateJobRequest now accepts an idempotency_key for safe retries. Duplicate requests with the same key return the existing job.
• Job metadata — Attach up to 20 custom key-value pairs to jobs via the metadata field.
• Cost estimation — Presets include estimated_cost_per_minute for pre-submission cost estimates.

#2025-12-01

#Added

• Initial API release — Core services: OrganizationService, AppService, APIKeyService, PresetService, JobService, HealthService.
• Multi-tenancy — Organization and App hierarchy with API key authentication.
• System presets — Built-in encoding presets for common configurations.
• Quality tiers — Economy (0.75x), Standard (1.0x), and Premium (2.0x) pricing tiers.
• Four video codecs — H.264, H.265, VP9, and AV1 support.
• Three audio codecs — AAC, Opus, and MP3 support.
• Cursor pagination — All list endpoints support cursor-based and offset-based pagination.
• Structured errors — Connect-RPC error codes with ErrorDetails and FieldViolation payloads.

#Subscribing to Changes

Stay informed about API changes:

• Changelog RSS feed — subscribe to this page for updates
• Status page — monitor API availability and incidents
• Release notes — detailed technical notes for each release

For questions about changes or migration assistance, contact support@transcodely.com.