Before you start

This guide assumes that you understand the basics of making a Transcode API request. We recommend completing the Getting Started with Transcoding Media guide first.

Transcode to a specification

Deciding exactly what parameters to set when encoding video can be an art form in its own right. Sometimes, you want to configure the output a certain way to deliver to someone else's specification. In this guide, we will walk through optimizing your output for delivery to Vimeo, though you can do this exercise for other specifications or recommendations as well.

Vimeo has a great guide for explaining the basics of delivering video to their platform. You can read the full walkthrough, but it boils down to a few key takeaways, assuming a 1080p source or input video:

• Video Guidelines:
  • Input codec: h265 (High-Efficiency Video Coding or HEVC).
  • Frame rate: maintain the native video frame rate (this is the frames per second that you recorded or exported from your editing software).
  • Bitrate mode: variable bitrate (known as vbr). This gives the video encoder the flexibility to spend data where the video is complex and save data where the video is easier to compress. This is generally a good choice for video distributed on the web.
  • Bitrate: for 1920x1080p video (known as 1080p), a bitrate of 10-20 mbps (Megabits per second is recommended which translates to 10,000-20,000 kbps (Kilobits per second—this is how we specify a data rate to the Transcode API)
• Audio Guidelines:
  • Codec: Advanced Audio Codec, Low Complexity (aac_lc for short).
  • Bitrate: 320 kbps (Kilobits per second).
  • Sample rate: maintain the input sample rate from the source.
  • Channels: stereo.

Example

Let's configure the Transcode API to output the recommended Vimeo specification.

"outputs": [
    {
        "id": "vimeo-1080p",
        "destination": {
            "ref": "my-s3-output",
            "filename": "vimeo-1080p.mp4"
        },
        "kind": "mp4",
        "video": {
            "height": 1080,
            "codec": "h265",
            "bitrate_mode": "vbr",
            "bitrate_kb": 15000,
            "max_bitrate_kb": 16500
        },
        "audio": [{
            "codec": "aac_lc",
            "bitrate_kb": 320
        }]
    }
]

Now, given the above output, let's walk through each parameter and understand how it is applied in our Transcode request:

• id
  • A unique identifier to associate with this output. You can call it whatever you like.
• destination
  • This is where we want to put the output file. In our example, we are connecting to our own AWS S3 bucket. There are a few other options, see Media Input and Output.
    for getting started quickly. For production work, connect your own storage.)
• kind
  • This is the type of output that you want the API to output. MP4 is a common format for web delivery. If you don't specify any audio or video arguments, the Transcode API decides how to configure the encoder for broad compatibility and high quality outputs for you, selecting which codec to use and which settings to set.
• video
  • height
    • Notice how we specified height but not width. It would be completely valid to specify both, but by only specifying one dimension, the platform scales the other dimension for you. Because our source is actually 1920x1080 already, there is no need to specify even height at all (though it won't hurt!). By default, the Transcode API outputs the dimensions based on the source or input dimensions.
  • codec
    • This tells the encoder to use the h265 codec as recommended by Vimeo. By default, if you specify a "kind" of "mp4", the platform will select the h264 codec for compatibility.
  • bitrate_mode
    • This tells the encoder to make encoding decisions. There are a few options:
      • vbr
        • Variable bitrate is a good file size vs quality trade off. It is generally a good choice to make for files that are for web delivery. The encoder will spend more data compressing complex portions of the video and save data when the scene is less complex.
      • cbr
        • Constant bitrate is similar to variable bitrate, but the encoder attempts to spend the same amount of data over the duration of the output. This is needed for certain playback scenarios.
      • crf
        • This is the default mode for the Transcode API if you don't specify. Constant rate factor (CRF) encoding is a mode that optimizes for quality rather than file size. At points in the video where there is more complexity such as an action sequence, the bitrate will be higher to preserve the quality. The API will choose a default CRF value based on the codec you choose that strikes a balance between file size and quality. You can manually specify a CRF value with the crf parameter when you specify crf as the bitrate_mode.
  • bitrate_kb
    • The bitrate (in kilobits per second) tells the encoder how much data it has to spend over time. This impacts quality. If the encoder has data to spend, it spends it when needed. If the data rate is too low for the complexity of the video, the resulting quality is lower. This is only valid for vbr and cbr encoding modes.
  • max_bitrate_kb
    • This setting is not strictly necessary, but can be provided to tell the encoder to be more constrained to achieve the target bitrate. In our example, we set this value to 10% higher than the target bitrate.
• audio
  • codec
    • We tell the Transcode API which audio codec we want to have in our output. This matches the Vimeo recommendation
  • bitrate_kb
    • Just like the video, this tells the audio encoder what data rate to use for the output.
  • channels
    • We assume a stereo input (2 channels), so we do not need to specify the output channels. The transcode API uses the stereo from the input.

And that's it! You can refer to the Transcode API guide for more detail on the available encoding options or read about transcoding before YouTube's algorithm misconfigures your video.