API Reference 2.0

Simple Format Specification

A Simple format describes the format specs you want to use in outputs section.

The Simple Format Specification defines the output format for media content in the Coconut Transcoding Service. This guide provides details on the structure, including video and audio specifications, and format options.

Format Naming Convention

Video formats are represented as:

$video_container:$video_specs:$audio_specs:$format_options

Of these, only $video_container is required. Appropriate defaults (codecs, bitrates, sample rates) are set based on the chosen container.

Specs must be separated by semi-colon ":" and options must be separated by underscore "_". Refer to the examples provided for a clearer understanding of how to use the different format options.

For Audio-only formats:

$audio_container:$audio_specs

For image formats, you can only set the resolution:

$image_container:$resolution

Containers

List of supported containers (video, audio and image)
mp4 webm mpegts mov ogg aac mp3 wav jpg png webp gif webp_anim

Video Specifications

$resolution_$bitrate_$codec_$fps
Video specsValuesDefault
Resolution240p 360p 480p 540p 576p 720p 1080p 2160p
Any resolution WxH
Original
Codeccopy dnxhd h264 hevc novideo prores prores-ks theora vp8 vp9Container standard
Bitrate (kbps)Any value < 200000k
1500k 2000k 4000k ...
FPS0fps 15fps 23.98fps 25fps 29.97fps 30fps 60fpsOriginal

Audio Specifications

$codec_$bitrate_$sample_rate_$channels
Audio specsValuesDefault
Codecaac ac3 amr-nb copy flac mp2 mp3 noaudio pcm pcm-alaw pcm-s16le pcm-u8 vorbis wmav2Container standard
Bitrate (kbps)Any value < 512k
64k 128k 256k ...
Sample rate8000hz 11025hz 22050hz 44100hz 48000hzOriginal
Channelsmono stereo multiOriginal

Format options

$options
OptionsValuesDefault
pix_fmtyuv420p yuv422p yuva444p10leyuv420p
2passIf present, will transcode in 2passNo
metadataStrip original metadata if metadata=01

MP4 options

OptionsValuesDefault
fragGenerate a fragmented MP4 file if this option is used.No

H264 and HEVC options

OptionsValuesDefault
vprofilebaseline main high high10 high422 high444baseline
level10 11 12 13 20 21 22 30 31 32 40 41 42 50 5131
qualitySet a visual quality instead of bitrate From 1 (worst) to 5 (visually lossless)
quality=4 is a pretty good quality / file size ratio.
maxrate (kbps)When using quality, you can cap the bitrate to not go higher your requirements.
mp4:1080p::quality=4,maxrate=2500k

VP8 and VP9 options

OptionsValuesDefault
qualitySet a visual quality instead of bitrate From 1 (worst) to 5 (visually lossless)
quality=4 is a pretty good quality / file size ratio.
maxrate (kbps)When using quality, you can cap the bitrate to not go higher your requirements.
webm:vp9_1080p::quality=4,maxrate=2500k

Prores options

OptionsValuesDefault
vprofileProxy: 0 LT: 1 SQ: 2 HQ: 3

Full examples

FormatDescription
mp4:1080pMP4 with H264 / AAC codecs. 1080p resolution and 4000k bitrate
mp4:1080p::quality=4Use quality option instead of video bitrate
mp4:1080p::quality=4,maxrate=3000kUse quality option and cap the bitrate to 3000k
mp4:hevc_2160pMP4 with HEVC / AAC codecs. 4k resolution and 8000k bitrate
mp4:1080p::2passEnable 2pass encoding
mp4:320x240_1000kSpecify the full resolution and the video bitrate
mp4:1080p:noaudioRemove the audio track
mp4:1080p:copyCopy the audio track without transcoding
mp4:::quality=3Keep the original resolution and use the quality option
mp4:360p_25fpsChanges the original frame rate to 25fps
mp4:copy:copyCopy the video and audio track without transcoding
mp4:1080p::frag,quality=4Create a fragmented MP4 file with 1080p resolution and quality option
mp4:::quality=3,vprofile=high,level=50Specify the video profile high and level 50 for H264 encoding
webm:720pWebM with VP8 / vorbis codecs. 720p resolution and 2000k bitrate
webm:vp9_1080pWebM with VP9 / vorbis codecs. 1080p resolution and 4000k bitrate
webm:720p:48000hzSpecify the sample rate 48000hz
mp4:720p:multiKeep the audio channels 5.1 instead of changing it to stereo
mp3MP3 audio-only format with 128k bitrate
aac:64kAAC audio-only format with 64k bitrate
webp:400xWebP image-only format with 400x resolution. Height is calculated automatically
jpg:640x360JPG image-only format with full resolution given 640x360