Presets

A preset is a named set of output options. Name one in an output with preset; the output may leave out type, and if it sets one it must be the preset's. GET /v1/presets lists them with their options.

curl "$VIDEXO_API_URL/v1/transcode" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "https://example.com/talk.mp4",
  "preset": "web-1080p"
}'

const response = await fetch(`${process.env.VIDEXO_API_URL}/v1/transcode`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDEXO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "input": "https://example.com/talk.mp4",
    "preset": "web-1080p"
  }),
});
const job = await response.json();

ffmpeg \
  -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf "scale='min(iw,1920)':'min(ih,1080)':force_original_aspect_ratio=decrease:force_divisible_by=2" \
  -c:v libx264 -preset veryfast -crf 22 -pix_fmt yuv420p \
  -map "0:a:0?" \
  -c:a aac -b:a 160k -movflags +faststart \
  video.mp4

Your fields win#

The output's own fields replace the preset's key by key, and a field you set clears the inherited fields it is an alternative to. So { "preset": "web-720p", "video": { "quality": "high" } } keeps the preset's size and codec and is CRF 18, and { "preset": "web-720p", "resize": { "height": 540 } } is 540 pixels high.

Lists (overlays, mix, times, concat) replace the preset's, and "audio": false replaces an inherited audio object. The job's spec shows the result.

Preset stability#

During the preview, a preset's options may still change. Every change is listed in the changelog, and a job keeps the command it was created with. To pin the exact settings, copy them from GET /v1/presets into the output instead of naming the preset.

After launch, a preset keeps its options for as long as /v1 exists: new behaviour gets a new name or a dated revision of the same name (web-720p@2027-03-01), and the name without a date stays the first version. A deprecated preset is marked here and in GET /v1/presets, and keeps working.

The presets#

web-720p#

A video output. MP4 for the web: H.264 at CRF 23 within 1280 by 720 (never enlarged), AAC 128k, fast start.

Its options, as the fields of an output:

{
  "format": "mp4",
  "resize": {
    "width": 1280,
    "height": 720,
    "fit": "contain",
    "enlarge": false
  },
  "video": {
    "codec": "h264",
    "crf": 23,
    "encoder_preset": "veryfast",
    "pixel_format": "yuv420p",
    "faststart": true
  },
  "audio": {
    "codec": "aac",
    "bitrate": "128k"
  }
}

On one input it runs:

ffmpeg \
  -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf "scale='min(iw,1280)':'min(ih,720)':force_original_aspect_ratio=decrease:force_divisible_by=2" \
  -c:v libx264 -preset veryfast -crf 23 -pix_fmt yuv420p \
  -map "0:a:0?" \
  -c:a aac -b:a 128k -movflags +faststart \
  main.mp4

web-1080p#

A video output. MP4 for the web: H.264 at CRF 22 within 1920 by 1080 (never enlarged), AAC 160k, fast start.

Its options, as the fields of an output:

{
  "format": "mp4",
  "resize": {
    "width": 1920,
    "height": 1080,
    "fit": "contain",
    "enlarge": false
  },
  "video": {
    "codec": "h264",
    "crf": 22,
    "encoder_preset": "veryfast",
    "pixel_format": "yuv420p",
    "faststart": true
  },
  "audio": {
    "codec": "aac",
    "bitrate": "160k"
  }
}

On one input it runs:

ffmpeg \
  -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf "scale='min(iw,1920)':'min(ih,1080)':force_original_aspect_ratio=decrease:force_divisible_by=2" \
  -c:v libx264 -preset veryfast -crf 22 -pix_fmt yuv420p \
  -map "0:a:0?" \
  -c:a aac -b:a 160k -movflags +faststart \
  main.mp4

social-vertical#

A video output. Vertical 1080 by 1920 MP4, cropped at the centre, 30 fps, keeping the sound when there is one.

Its options, as the fields of an output:

{
  "format": "mp4",
  "resize": {
    "width": 1080,
    "height": 1920,
    "fit": "cover",
    "anchor": "center"
  },
  "fps": 30,
  "video": {
    "codec": "h264",
    "crf": 23,
    "encoder_preset": "veryfast",
    "pixel_format": "yuv420p",
    "faststart": true
  },
  "audio": {
    "codec": "aac",
    "bitrate": "128k"
  }
}

On one input it runs:

ffmpeg \
  -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,fps=30 \
  -c:v libx264 -preset veryfast -crf 23 -pix_fmt yuv420p \
  -map "0:a:0?" \
  -c:a aac -b:a 128k -movflags +faststart \
  main.mp4

square#

A video output. Square 1080 by 1080 MP4, cropped at the centre, 30 fps, keeping the sound when there is one.

Its options, as the fields of an output:

{
  "format": "mp4",
  "resize": {
    "width": 1080,
    "height": 1080,
    "fit": "cover",
    "anchor": "center"
  },
  "fps": 30,
  "video": {
    "codec": "h264",
    "crf": 23,
    "encoder_preset": "veryfast",
    "pixel_format": "yuv420p",
    "faststart": true
  },
  "audio": {
    "codec": "aac",
    "bitrate": "128k"
  }
}

On one input it runs:

ffmpeg \
  -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf scale=1080:1080:force_original_aspect_ratio=increase,crop=1080:1080,fps=30 \
  -c:v libx264 -preset veryfast -crf 23 -pix_fmt yuv420p \
  -map "0:a:0?" \
  -c:a aac -b:a 128k -movflags +faststart \
  main.mp4

podcast-audio#

A audio output. MP3 128k stereo at 44.1 kHz, normalised to -16 LUFS with peaks under -1.5 dBTP.

Its options, as the fields of an output:

{
  "format": "mp3",
  "audio": {
    "codec": "mp3",
    "bitrate": "128k",
    "sample_rate": 44100,
    "channels": 2,
    "normalize": {
      "loudness": -16,
      "true_peak": -1.5,
      "range": 11
    }
  }
}

On one input it runs:

ffmpeg \
  -i https://example.com/talk.mp4 \
  -vn \
  -map 0:a:0 \
  -af loudnorm=I=-16:LRA=11:TP=-1.5 \
  -c:a libmp3lame -b:a 128k -ar 44100 -ac 2 \
  main.mp3

gif-preview#

A gif output. An animated GIF at most 480 pixels wide at 12 fps with 256 colours: the first 5 seconds unless trim says otherwise.

Its options, as the fields of an output:

{
  "format": "gif",
  "resize": {
    "width": 480,
    "enlarge": false
  },
  "fps": 12,
  "colors": 256,
  "trim": {
    "start": 0,
    "duration": 5
  }
}

On one input it runs:

ffmpeg \
  -t 5 -i https://example.com/talk.mp4 \
  -filter_complex "[0:v:0]scale='min(iw,480)':'min(ih,7680)':force_original_aspect_ratio=decrease:force_divisible_by=2:flags=lanczos,fps=12[o0s0];[o0s0]split[o0g0][o0g1];[o0g0]palettegen=max_colors=256[o0p];[o0g1][o0p]paletteuse[o0v]" \
  -map "[o0v]" \
  main.gif

poster#

A image output. A JPEG within 1280 by 720 (never enlarged) of the most representative of the first frames, or of the frame at at.

Its options, as the fields of an output:

{
  "format": "jpg",
  "at": "auto",
  "quality": "high",
  "resize": {
    "width": 1280,
    "height": 720,
    "fit": "contain",
    "enlarge": false
  }
}

On one input it runs:

ffmpeg \
  -i https://example.com/talk.mp4 \
  -map 0:v:0 \
  -vf "thumbnail=300,scale='min(iw,1280)':'min(ih,720)':force_original_aspect_ratio=decrease:force_divisible_by=2" \
  -frames:v 1 -q:v 2 \
  main.jpg