MediaRuntime Presets: Every Output Recipe Explained
Learn what a MediaRuntime preset controls, how type and preset work together in a job invocation, and when to use every current video, social, GIF, frame, HLS, audio, and image recipe.
A media API should let an application describe the result it needs without forcing every developer to design an FFmpeg command, choose a codec profile, or assemble a streaming package from scratch. MediaRuntime presets provide that contract. A preset is a named, versioned output recipe implemented by the execution engine. It converts product intent—such as ‘make this video playable on the web,’ ‘prepare this audio for speech recognition,’ or ‘create a vertical social clip’—into a repeatable media operation.
A preset is an executable recipe, not just a label
Every object in outputs[] contains a type and a preset. The type selects the execution family—mp4, hls, social, gif, frames, audio, or image—while the preset selects the recipe inside that family. Send both exactly as documented. The preset establishes dependable defaults for codecs, containers, dimensions, bitrates, filters, segmenting, or derivative behavior. Job options then add request-specific intent such as a poster timestamp, subtitle format, image dimensions, output suffix, moderation report, or watermark.
{
"file_url": "gs://value-returned-by-upload-url",
"metadata": {
"asset_id": "video_0426",
"media_type": "video"
},
"outputs": [
{
"type": "mp4",
"preset": "mp4_720p_h264_aac",
"path_suffix": "web-playback"
}
]
}Use the exact file_uri returned by POST /v1/upload-url. The input address does not choose the output format—the type and preset do.
Why presets make job invocations useful
Presets make payloads small enough to understand in a code review and stable enough to persist as product configuration. They also make retries reproducible: the same input and output recipe express the same processing intent. They are composable. One uploaded video can request an MP4, an HLS package, an audio-only file, subtitles, a poster, and a GIF preview in one asynchronous job. Each entry in outputs[] is independently named with path_suffix, and MediaRuntime returns the generated artifacts in the completed job instead of requiring the client to predict filenames or storage paths.
Video files and poster presets
mp4_720p_h264_aac — Send type: mp4. Produces a 720p H.264 video with AAC audio in a faststart MP4. This is the general-purpose Standard preset for web playback and broad device compatibility. mp4_ladder_v1 — Send type: mp4. Produces separate 1080p, 720p, and 480p H.264/AAC MP4 renditions, plus a poster for each rendition. Use it when your application chooses a downloadable rendition rather than adaptive streaming. Its base tier is Standard. transmux_mp4_fast — Send type: mp4. Copies compatible source streams into a faststart MP4 without re-encoding, preserving quality and finishing quickly. It is Standard. Because stream copy depends on codec and container compatibility, use mp4_720p_h264_aac when the target characteristics must be predictable. If stream copy fails and fallback is enabled, the engine can re-encode with the 720p H.264 recipe. poster_frame_v1 — Send type: mp4, even though the result is an image. Captures one 720p JPG at poster_time_sec. It is a Standard recipe for standalone cover art or a single thumbnail. mp4_hevc_1080p — Send type: mp4. Produces a 1080p HEVC/H.265 video with AAC audio and the hvc1 tag used for Apple playback compatibility. It is Premium and is useful when smaller delivery files matter more than encode speed or universal legacy support. mp4_av1_smart — Send type: mp4. Produces a 1080p AV1 + Opus MP4. It is Premium, CPU-intensive, and aimed at compression-efficient modern delivery. Confirm playback support in your target clients before choosing AV1 as the only output. mov_prores_422 — Send type: mp4. Produces a ProRes 422 HQ + PCM MOV at the source dimensions. It is a Premium editing master or mezzanine output: large to store and deliver, but well suited to editing and archival workflows.
Social video, GIF, frame extraction, and HLS
social_vertical_blur — Send type: social. Produces a 1080×1920 H.264/AAC MP4 for Reels, TikTok, and Shorts. The source is fitted without cropping while a blurred copy fills the 9:16 background. It is Premium because the vertical output reaches 1920 pixels in height. gif_hq — Send type: gif. Produces a palette-optimized animated GIF at 480 pixels wide and 15 frames per second. It is a Standard primary GIF output. Use gif_preview instead when you want a short, explicitly timed GIF attached to another video output. extract_frames_1 — Send type: frames. Produces a numbered JPG sequence sampled at one frame per second. It is Standard and useful for indexing, lightweight analysis, datasets, contact sheets, and custom preview selection. extract_frames_5 — Send type: frames. Produces the same numbered JPG sequence at five frames per second. It is Standard and provides denser temporal coverage at the cost of more artifacts and storage. hls_ladder_v1 — Send type: hls. Produces an HLS VOD package containing 1080p and 720p H.264/AAC variants, a master playlist, and independent six-second segments. Its base tier is Standard. Use it when the playback client should adapt quality to changing network conditions.
{
"file_url": "gs://value-returned-by-upload-url",
"outputs": [
{
"type": "hls",
"preset": "hls_ladder_v1",
"path_suffix": "adaptive-stream"
}
]
}Audio presets
Audio presets accept an audio source or extract the audio stream from a video source. That means the same uploaded video can produce playback video, a podcast-ready audio file, and transcripts without a separate extraction service.
audio_copy_fast — Send type: audio. Copies a compatible source audio stream without re-encoding, avoiding generation loss. It is Standard. If copying is incompatible and fallback is enabled, the engine can produce 128 kbps AAC instead. audio_aac_128k — Send type: audio. Produces 128 kbps AAC in a faststart M4A file. It is a Standard choice for efficient, widely supported audio delivery. audio_mp3_128k — Send type: audio. Produces a 128 kbps MP3. It is Standard and useful when compatibility with older clients or existing MP3 workflows matters. audio_opus_96k — Send type: audio. Produces a 96 kbps Opus file. It is Standard and particularly efficient for speech-oriented delivery. audio_loudnorm_aac_128k — Send type: audio. Normalizes the program toward -16 LUFS and produces 128 kbps AAC. Its base tier is Standard. Use it to make interviews, podcasts, lessons, and user-generated recordings play at a more consistent perceived loudness. audio_trim_silence_aac_128k — Send type: audio. Removes leading and trailing silence before producing 128 kbps AAC. It is Premium and useful for voice notes, recordings, and clips that should begin promptly. audio_loudnorm_trim_aac_128k — Send type: audio. Trims boundary silence, normalizes toward -16 LUFS, and produces 128 kbps AAC. It is Premium and combines cleanup with delivery preparation. audio_whisper_prep — Send type: audio. Produces 16 kHz mono PCM WAV for Whisper, ASR, and other speech pipelines. It is Premium. This is a preprocessing artifact; request a delivery format such as AAC, MP3, or Opus separately when users also need to listen to the audio.
{
"file_url": "gs://value-returned-by-upload-url",
"metadata": {
"asset_id": "interview_0426",
"media_type": "video"
},
"outputs": [
{
"type": "audio",
"preset": "audio_aac_128k",
"path_suffix": "listen",
"subtitles": {
"enabled": true,
"languages": ["auto"],
"format": "both",
"model": "ggml-base.bin",
"translate_to_english": false
}
},
{
"type": "audio",
"preset": "audio_whisper_prep",
"path_suffix": "speech-model-input"
}
]
}Image derivative preset
image_multi_v1 — Send type: image. Produces every rendition described in images[]. Each entry selects width, height, mode, format, and quality. Supported resize modes are fit, fill, cover, and contain; output formats are JPG, PNG, WebP, and AVIF. Generated derivatives strip source metadata such as EXIF and IPTC. The base tier varies with the request. Standard supports JPG or PNG, up to three derivatives, and widths through 1920 pixels. WebP or AVIF, larger derivative sets, wider images, smart crop, and background removal require Premium.
{
"file_url": "gs://value-returned-by-upload-url",
"metadata": {
"asset_id": "product-photo-0426",
"media_type": "image"
},
"outputs": [
{
"type": "image",
"preset": "image_multi_v1",
"path_suffix": "catalog",
"images": [
{ "width": 1200, "height": 1200, "mode": "cover", "format": "jpg", "quality": 88 },
{ "width": 1600, "height": 900, "mode": "fit", "format": "webp", "quality": 82 },
{ "width": 600, "height": 800, "mode": "contain", "format": "png", "quality": 90 }
]
}
]
}Options that extend a preset
Not every capability needs another preset name. poster_time_sec chooses a frame time. gif_preview adds a short GIF preview to a video output. thumbnails configures sampled thumbnail sheets. subtitles requests SRT, WebVTT, or both from an audio-bearing output. images[] defines image renditions. path_suffix gives an output a stable application-facing label. Moderation and watermark are job-level controls. Moderation samples visual frames and attaches report evidence; it is currently report-only and does not block the transcode. Watermark uses the account’s configured PNG logo on supported visual outputs. Both require Premium.
One video, several product-ready artifacts
The following invocation turns one source video into an adaptive HLS stream, a downloadable MP4 with a poster and GIF preview, and an audio-only M4A with SRT and WebVTT transcripts. The GIF preview makes this a Premium request even though the three base presets can otherwise run at Standard tier.
{
"file_url": "gs://value-returned-by-upload-url",
"metadata": {
"asset_id": "episode_0426",
"media_type": "video"
},
"outputs": [
{
"type": "hls",
"preset": "hls_ladder_v1",
"path_suffix": "stream"
},
{
"type": "mp4",
"preset": "mp4_720p_h264_aac",
"path_suffix": "download",
"poster_time_sec": 5,
"poster_format": "jpg",
"gif_preview": {
"enabled": true,
"width": 480,
"fps": 10,
"start_time": 5,
"duration": 3
}
},
{
"type": "audio",
"preset": "audio_aac_128k",
"path_suffix": "listen",
"subtitles": {
"enabled": true,
"languages": ["auto"],
"format": "both",
"model": "ggml-base.bin",
"translate_to_english": false
}
}
]
}How to choose the right preset
Choose mp4_720p_h264_aac for dependable browser playback. Choose hls_ladder_v1 when adaptive streaming matters. Choose transmux_mp4_fast only when compatible stream copy is acceptable. Choose HEVC or AV1 when compression goals and client support justify Premium encoding. Choose ProRes for an editing master, not ordinary playback. Use social_vertical_blur for a ready-made vertical canvas, gif_hq for a primary animated GIF, a frame preset for numbered stills, and poster_frame_v1 for exactly one cover image. For audio, decide whether you need lossless copying, a delivery codec, loudness consistency, silence cleanup, or speech-model preparation. For images, describe the actual derivative matrix your interface consumes.
The complete job determines tier and cost
A preset’s base tier is only the starting point. More than three outputs, moderation, watermarking, advanced subtitle models, translation, multiple subtitle languages, GIF previews, WebP or AVIF images, large image batches, smart crop, and background removal can raise the required tier. MediaRuntime evaluates the complete request before execution, estimates projected usage, and reserves the projected wallet amount. After the engine completes, billing settles against actual usage and releases any unused reservation. Use the returned estimate for the exact job rather than treating a preset name as a fixed-price quote.
Start with the deliverable
Start by naming what your product needs to deliver: a browser MP4, adaptive HLS, vertical social media, a poster, GIF, frame sequence, normalized audio, transcript, speech WAV, or a set of image derivatives. Select the matching type and preset, add only the options specific to your product, and let the asynchronous job produce the artifacts. Explore executable examples and the live endpoint reference at https://mediaruntime.com/docs.