API documentation

Coconut's API is a config-based API built with simplicity and flexibility in mind.
Encode your first video in less than 5 minutes.

API Reference

Simple Format Specification

A Simple format describes the format specs you want to use in output definitions ->.

The format name follows this simple naming convention:

$container:$video_specs:$audio_specs:$format_options

Only the container is required, which is really nice because the correct format specs are set for you like bitrates, codecs, sample rate, etc.

So let's say you want to use a fairly standard format like MP4 (H264 / AAC), the format name would be mp4. For a WebM format: webm and so on.

Here are some simple format examples to show you how it works:

mp4 mp4:240p_400k mp4:720p hls:360p webm:600x0_800k mp4:hevc_720p_1500k webm:vp9 mp4::256k

If you want an audio only output format, use one of the audio container mp3, ogg, aac or wav. In that case, the $video_specs must be removed from the format name.

Example: mp3 ogg:64k mp3:64k_22050hz_mono

Simple Format Base

For each container, video and audio specs are set automatically for you following the video format standards. Most of the time, you just need to customize the output resolution and you get a format that just works.

ContainerVideo specsAudio specs
mp4h264 0x0 1000k 0fpsaac 44100hz 128k stereo
mp4:hevchevc 0x0 1000k 0fpsaac 44100hz 128k stereo
webmvp8 0x0 1000k 0fpsvorbis 44100hz 128k stereo
webm:vp9vp9 0x0 1000k 0fpsvorbis 44100hz 128k stereo
avi
Aliases: divx xvid
mpeg4 0x0 1000k 0fpsmp3 44100hz 128k stereo
asf
Alias: wmv
wmv2 0x0 1000k 0fpswmav2 44100hz 128k stereo
mpegts
Alias: hls
h264 0x0 1000k 0fpsaac 44100hz 128k stereo
movh264 0x0 1000k 0fpsaac 44100hz 128k stereo
flv
Alias: flash
flv 0x0 1000k 0fpsmp3 44100hz 128k stereo
mkvh264 0x0 1000k 0fpsaac 44100hz 128k stereo
3gph263 0x0 1000k 0fpsaac 44100hz 32k stereo
ogv
Alias: theora
theora 0x0 1000k 0fpsvorbis 44100hz 128k stereo
oggvorbis 44100hz 128k stereo
mp3mp3 44100hz 128k stereo
jpgjpg 0x0
pngpng 0x0
gifgif 0x0
storyboardpng 0x0


Video specs

Video specs must be separated by the underscore character _ and are all optional.

To disable video, set the video specs to x. For instance: mp4:x mp4:x:256k_48000hz.

• Resolution

Default resolution if not specified: 0x0 (=Original resolution)

There are two ways to specify the resolution: either with the classic widthxheight or with the *p notation like 720p or 1080p. Note that for thumbnails, GIF and storyboard, only the notation widthxheight is working.

If you use the latter, the video bitrate is automatically set for you:

DefinitionResolutionAspectBitrate in Kbit/s
240p0x240*500k
360p0x360*800k
480p0x480*1000k
720p1280x72016:92000k
1080p1980x108016:94000k


If you set the width or height to 0, we will automatically calculate the value for you according to the aspect ratio of the source video. 0x0 means that the original resolution will be kept.

Note that the video bitrate can still be overriden when using *p notation: mp4:720p_1800k.

• Video codec

Here is the list of video codecs we support:

mpeg4 xvid flv h263 mjpeg mpeg1video mpeg2video qtrle svq3 wmv1 wmv2 huffyuv rv20 h264 hevc vp8 vp9 theora dnxhd

Example: mp4:hevc_1080p_2000k avi:mpeg4_640x320

Note that we always set the right video codec associated to the right container for you. So unless you want HEVC or VP9, you can leave the video codec setting to us.

• Video bitrate

Default video bitrate if not specified: 1000k

The video bitrate must be given in kbps and always ends with k. Value must be < 200000k

Example: mp4:1080p_6000k webm:1200k

• FPS

Default FPS if not specified: 0fps (=original FPS)

The FPS value must ends with fps, here are the possible FPS you can provide: 0fps 15fps 23.98fps 25fps 29.97fps 30fps

Note that 0fps means keep original FPS.

Example: mp4:240p_15fps mp4:720p_30fps

Audio specs

Audio specs must be separated by the underscore character _ and are all optional.

To disable audio, set the audio specs to x. Example: mp4:720p:x mp4:hevc_1080p:x

• Audio codec

Here is the list of audio codecs we support:

mp3 mp2 aac amr_nb ac3 vorbis flac pcm_u8 pcm_s16le pcm_alaw wmav2

Example: mkv:mpeg4:mp3 mpegts::mp3

Note that we always set the right audio codec associated to the right container for you. However you can customize it if you need to.

• Audio bitrate

Default audio bitrate if not specified: 128k

The audio bitrate must be given in kbps and always ends with k. Value must be <= 512k.

Example: mp4:1080p:512k webm:1200k:256k

• Sample rate

Default sample rate if not specified: 44100hz

The sample rate value must ends with hz, here are the possible sample rate you can provide:

8000hz 11025hz 16000hz 22000hz 22050hz 24000hz 32000hz 44000hz 44100hz 48000hz

Example: mp4:240p:64k_22050hz mp4:720p:48000hz

• Audio Channel

Default channel if not specified: stereo

Possible channel values are mono stereo

Example: mp4:240p:64k_mono

Format options

• 2pass encoding

To enable 2pass encoding, you can set 2pass. For instance: mp4:720p::2pass