Amazon CloudFront
Developer Guide (API Version 2010-11-01)
Print this pageEmail this pageGo to the ForumsView the PDFShare this page on TwitterShare this page on FacebookBookmark this page on DeliciousSubmit this page to RedditSubmit this page to DiggDid this page help you?  Yes  No   Tell us about it...

Streaming Media on Demand

The basic CloudFront distribution is a download distribution that serves HTTP content. You might want to also serve streamed media using a streaming protocol. This section describes how to use CloudFront to stream on-demand media files.

With CloudFront, streaming means that the end user receives and uses (for example, views) media simultaneously. A streaming server streams the data over a special protocol to a media player that plays the media as it receives it. When the end user is done viewing the video (for example), the video isn't stored locally on the end user's system.

Streaming distributions differ from download distributions in the following ways:

DownloadStreaming
Content distributed over HTTP Content distributed over RTMP
Generally, viewers render content after it downloads completely Content used as it downloads
[Note]Note

CloudFront currently only supports Amazon S3 origin servers for streaming distributions. Custom origins are not supported for streaming distributions. In addition, you must be using API version 2009-12-01 or later.

Streaming Server and Media Player

CloudFront uses Adobe Flash Media Server 3.5 to stream on-demand content with Adobe's Real-Time Messaging Protocol (RTMP). CloudFront accepts RTMP requests over port 1935 and port 80.

CloudFront supports the following variants of the RTMP protocol:

  • RTMP—Adobe's Real-Time Message Protocol

  • RTMPT—Adobe streaming tunneled over HTTP

  • RTMPE—Adobe encrypted

  • RTMPTE—Adobe encrypted tunneled over HTTP

Which protocol you use is up to you and depends on your own needs. For a basic summary of RTMP and the file formats that Adobe Flash Media Server supports, go to Overview of Streaming with Flash Media Server 3 on the Adobe website. This includes information about the supported codecs and containers.

There are resources available on the Internet to help you determine the bit rate to use for your Flash files. For an example, go to Flash video (FLV) bitrate calculator on the Adobe website.

CloudFront supports all the features in Adobe Flash Media Server 3.5 related to dynamic streaming, which is the ability to switch between different quality streams during playback. For more information, go to Dynamic streaming in Flash Media Server 3.5: Part 1 on the Adobe website.

To serve streamed content, you need to provide your end users with a media player. You can write your own player using Adobe Flash. For more information, go to http://www.adobe.com/products/flashplayer/. You can also use an existing player, such as JW Player. For more information, go to http://www.longtailvideo.com/.

Layout of Buckets and Distributions

To stream content, you need to provide two types of files to your end users: your media files and a media player. In this topic, we assume that your media files and your media player are stored in different buckets in Amazon S3, and are served to end users through CloudFront. Making the media player available to end users through Amazon S3 and CloudFront is optional. You can also refer end users to a media player that is stored elsewhere.

If you're using CloudFront to serve both the media player and the media files, you need to use two types of distributions: a download distribution for the media player, and a streaming distribution for the media files. Download distributions serve files over HTTP, whereas streaming distributions stream media files over RTMP (or a variant of RTMP).

The following diagram shows the general layout of your CloudFront streaming setup.

Setup for streaming

Your media player bucket holds the media player and is the origin server for a regular HTTP distribution. In this example, the distribution's domain name is d1234.cloudfront.net.

Your streaming bucket holds your media files and is the origin server for a streaming distribution. In this example, the distribution's domain name is s5678.cloudfront.net.

Your site serves a cached copy of the media player to each end user (through the d1234.cloudfront.net domain). The media player then accesses cached copies of your media files (through the s5678.cloudfront.net domain).

Overall Process to Stream Content

The following table describes the process for configuring on-demand streaming. If you are using JW Player, Flowplayer, or Adobe Flash Builder for your media player, see the applicable tutorial instead:

Process for Streaming Content

1

Choose and configure a media player to play your media files. For help, refer to the documentation for the media player.

2

Upload the files for your media player to the Amazon S3 bucket that you created for the media player, and make the files (not the bucket) publicly readable.

3

Create a distribution for your media player (or you can use an existing distribution). You can use the CloudFront control API or your favorite CloudFront tool. For a list of tools, go to Amazon CloudFront Developer Tools.

For information on creating a download distribution with the control API, go to POST Distribution in the Amazon CloudFront API Reference.

4

Upload your media files to the Amazon S3 bucket that you created for the media files, and make the content (not the bucket) publicly readable.

[Important]Important

Media files in a Flash Video container must include the .flv filename extension, or the media will not stream.

You can put media player files and media files in the same bucket.

5

Use the CloudFront API (or your favorite CloudFront tool) to create a streaming distribution. For more information, see Creating a Streaming Distribution.

6

Configure your media player. For more information, see Configuring the Media Player.


If you have trouble getting your content to play, see Troubleshooting.

Creating a Streaming Distribution

Creating a streaming distribution is almost identical to creating a download distribution. The easiest way is to use the AWS Management Console at http://aws.amazon.com/console.

[Note]Note

CloudFront currently only supports Amazon S3 origin servers for streaming distributions. Custom origins are not supported for streaming distributions.

To create a streaming distribution with the AWS Management Console

  1. Sign in to the AWS Management Console and open the Amazon CloudFront console at https://console.aws.amazon.com/cloudfront/.

  2. Click Create Distribution.

    The Create Distribution dialog box opens.

  3. Select the Streaming button to specify a streaming distribution.

  4. In the Origin list, select the bucket you want as your origin server.

  5. Leave the remaining items as they are and click Create.

    Your new streaming distribution is created and appears in the list of distributions on the page. You can select the check box for the distribution to view its information at the bottom of the page.

The CloudFront control API also provides a set of actions for creating and managing your streaming distributions. The actions are parallel to those for creating and managing download distributions. The main difference is that the resource is a streaming-distribution instead of a distribution. For information about the API actions for streaming distributions, go to the Amazon CloudFront API Reference.

To create a streaming distribution with the control API

  1. Send a CloudFront control API request that looks similar to the following example.

    POST /2010-11-01/streaming-distribution HTTP/1.1
    [Required headers]
    
    <?xml version="1.0" encoding="UTF-8"?>
    <StreamingDistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2010-11-01/">
      <S3Origin>
          <DNSName>mystreamingbucket.s3.amazonaws.com</DNSName>
      </S3Origin>   
      <CallerReference>20120229090000</CallerReference>
      <Comment>My comments</Comment>
      <Enabled>true</Enabled>
    </StreamingDistributionConfig>
  2. You will receive a response that looks similar to the following example.

    201 Created
    Location: https://cloudfront.amazonaws.com/2010-11-01/streaming-distribution/EGTXBD79EXAMPLE
    x-amz-request-id: request_id
    
    <?xml version="1.0" encoding="UTF-8"?>
    <StreamingDistribution xmlns="http://cloudfront.amazonaws.com/doc/2010-11-01/">
       <Id>EGTXBD79EXAMPLE</Id>
       <Status>InProgress</Status>
       <LastModifiedTime>2009-11-19T19:37:58Z</LastModifiedTime>
       <DomainName>s5c39gqb8ow64r.cloudfront.net</DomainName>
       <StreamingDistributionConfig>
          <S3Origin>
             <DNSName>mystreamingbucket.s3.amazonaws.com</DNSName>
          </S3Origin>
          <CallerReference>20120229090000</CallerReference>
          <Comment>My comments</Comment>
          <Enabled>true</Enabled>
       </StreamingDistributionConfig>
    </StreamingDistribution>
  3. Store the Location header from the response, which contains the URI for your newly created streaming distribution, the ID for the distribution, and the domain name.

Configuring the Media Player

To play a media file, you need to configure the media player with the correct path to the file. How you configure the media depends on which media player you're using and how you're using it.

When you configure the media player, the path you specify to the media file must contain the characters cfx/st immediately after the domain name. For example, rtmp://s5c39gqb8ow64r.cloudfront.net/cfx/st/mediafile.flv.

[Note]Note

CloudFront follows Adobe's FMS naming requirements. Different players have their own rules about how to specify streams. The above example is for JW Player. Check your player's documentation. For example, Adobe's Flash Media Server does not allow the .flv extension to be present on the play path. Many players try and hide this fact and actually remove the .flv extension for you.

Your media player might ask for the path separate from the file name. For example, with JW Player's wizard, you specify a streamer and file variable:

  • streamer—rtmp://s5c39gqb8ow64r.cloudfront.net/cfx/st (with no trailing slash)

  • file— mediafile.flv

If you've stored the media files in a directory in your bucket (for example, videos/mediafile.flv), then the variables for JW Player would be:

  • streamer—rtmp://s5c39gqb8ow64r.cloudfront.net/cfx/st (with no trailing slash)

  • file— videos/mediafile.flv

To use the JW Player wizard, go to http://www.longtailvideo.com/support/jw-player-setup-wizard?example=204.

MPEG Files

To serve MP3 audio files or H.264/MPEG-4 video files, you might need to prefix the file name with mp3: or mp4:. Some media players can be configured to add the prefix automatically. The media player might also require you to specify the file name without the file extension (for example, magicvideo instead of magicvideo.mp4).

Restricting Access Using Crossdomain.xml

The Adobe Flash Media Server crossdomain.xml file specifies which domains can access media files in a particular domain. CloudFront supplies a default file that allows all domains to access the media files in your streaming distribution, and you cannot change this behavior. If you include a more restrictive crossdomain.xml file in your S3 bucket, CloudFront ignores it.

Error Codes

The following table lists the error codes that CloudFront can send to your playback media player. The errors are part of the string returned with Event.info.application.message or Event.info.description.

ErrorDescription

DistributionNotFound

The distribution is not found

DistributionTypeMismatch

The distribution is not a streaming distribution

InvalidInstance

The instance is invalid

InvalidURI

The URI is invalid

Troubleshooting

If you're having trouble getting your media files to play, check the items in the following table.

Item to CheckDescription

Separate distributions for the media player files and media files

The media player must be served by a regular HTTP distribution (for example, domain name d604721fxaaqy9.cloudfront.net), whereas the media files must be served by a streaming distribution (for example, domain name s5c39gqb8ow64r.cloudfront.net). Make sure you're not using the same distribution for both.

/cfx/st in the file path

Make sure to include /cfx/st in the file's path (for more information, see Configuring the Media Player). You don't need to include /cfx/st in the path to the object in the Amazon S3 bucket.

Problems playing MPEG-4 files

Some media players require mp4: before the file name. Some might also require you to exclude the .mp4 extension. For more information, see MPEG Files.

Port 1935 on your firewall

Adobe Flash Media Server uses port 1935 for RTMP. Make sure your firewall has this port open. If it doesn't, the typical message returned is "Unable to play video." You can also switch to RTMPT to tunnel over HTTP using port 80.

Adobe Flash Player messaging

By default, the Adobe Flash Player won't display a message if the video file it's trying to play is missing. Instead, it waits for the file to show up. You might want to change this behavior to give your end users a better experience.

To instead have the player send a message if the video is missing, use play("vid",0,-1) instead of play("vid").