Creating Videos for Multi-Bitrate Streaming with the Media API

Multi-bitrate streaming is a Video Cloud feature that improves a viewer's experience by enabling you to deliver videos with the resolution and bit rate that best matches the viewer's connection speed. The videos in your Media Library can include one or more renditions encoded at different bit rates and sizes. The Video Cloud player automatically displays the highest quality rendition that the viewer's download connection speed can support, taking into account the player's dimensions and the rendition's resolution and bit rate.

When you create a video using the Video Cloud Media API create_video method, you can optionally create multiple renditions of the video to support multi-bitrate streaming. You can also choose whether to encode a video to FLV (VP6) or MP4 (H.264).

The Media Write APIs are available only for Video Cloud Pro and Enterprise customers. If you are interested in upgrading your Video Cloud account, please contact Brightcove for more information.

Using create_video to create multiple renditions

Video Cloud can create multiple renditions of a video to support multi-bitrate streaming when you upload a file that is not already encoded with VP6 (.flv). This is controlled by the optional create_multiple_renditions argument in the create_video method. The create_video method has this signature:

create_video(token:String, video:Video, filename:String, maxsize:Long, file:InputStream,
   file_checksum:String, encode_to:String, create_multiple_renditions:Boolean,
   H264NoProcessing:Boolean, preserve_source_rendition:Boolean):Long

For example, to create a video with multiple renditions, you could post something like this to http://api.brightcove.com/services/post:

{"method": "create_video",
 "params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
             "video" : myVideo,
             "filename":"miamiMoon.mov",
             "create_multiple_renditions" : true}}

If the file passed to the create_video method is a supported, non-VP6 video file type and if create_multiple_renditions=true, then Video Cloud transcodes the file into multiple files, using the transcode settings, including bit rates and dimensions, for your account. Note that Video Cloud does not transcode multiple renditions when you pass in a VP6-encoded file, and in such a case, if you set the create_multiple_renditions=true argument, the create_video method returns an error. Setting create_multiple_renditions=false causes a single VP6-transcoded file to be created at the standard encoding rate and dimensions. For more information, see Using multi-bitrate streaming. As with the Media module, there is a file size limit of 2 GB for uploads.

Selecting the Encoding

Video Cloud can encode non-FLV source videos to either FLV (VP6) or MP4 (H.264). The encode_to argument of the create_video method controls the encoding of the output. You can set encode_to to FLV for VP6 (.flv) output, or to MP4 for H.264 output.

Creating videos with H.264 source files

If your source file uses the H.264 encoding, you can use your source file as an additional multi-bitrate streaming rendition. This behavior is controlled by the optional preserve_source_rendition argument in the create_video method. Set both create_multiple_renditions=true and preserve_source_rendition=true to create multiple renditions, while retaining the source H.264 file as a seventh rendition. If your source file is not H.264 encoded, the preserve_source_rendition argument is ignored.

You can also specify that you want to create a video with only a single rendition from your H.264 source file. Set H264NoProcessing=true, and the H.264 source file you upload with create_video will not be transcoded into multiple renditions.

This flowchart illustrates the interaction of the create_multiple_renditions and preserve_source_rendition parameters in the create_video method:

Getting video renditions

If your video has multiple renditions for multi-bitrate streaming, you can access them through the video's renditions property. This property returns an array of Rendition objects, each of which represents one of the video's multi-bitrate streaming renditions. For more information, see Accessing Video Content with the Media API: Accessing multi-bitrate streaming renditions.

Creating thumbnail and still images with the Media API

Whenever your source video is processed for transcoding by Video Cloud, we create a thumbnail and a video still image for the video. This means that we will create a thumbnail and a video still as a response to a create_video call whenever your source video is a non-VP6 video, unless your source video is H.264 encoded and you set both create_multiple_renditions=false and preserve_source_rendition=true. These images are created by taking a sample frame at the 50% mark in the video. You can replace these images with other images you choose, using the image capture tool or the Edit Video dialog in the Media module, or the add_image method in the Media API.