Creating Videos for Dynamic Delivery with the Media API

Multi-bitrate streaming is a Brightcove 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 Brightcove 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 Brightcove 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 Brightcove Pro and Enterprise customers. If you are interested in upgrading your Brightcove account, please contact Brightcove for more information.

Using create_video to create multiple renditions

Brightcove 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,
   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 Brightcove transcodes the file into four VP6 (.flv) files, using the standard bit rates and dimensions for multi-bitrate streaming renditions:

Note that Brightcove 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

Brightcove 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 four VP6 (.flv) renditions, while retaining the source H.264 file as a fifth 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 Brightcove, 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.