Versions Compared

Old Version 2

changes.mady.by.user Bill Branan

Saved on

compared with

New Version 3

changes.mady.by.user Bill Branan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

HTTP Live Streaming (HLS) is an HTTP-based streaming protocol which supports delivery of adaptive bitrate video and audio streams. DuraCloud makes use of Amazon CloudFront to deliver its HLS streaming capability, so streaming content must be store stored in the Amazon S3 storage provider to take advantage of this feature. 

...

Further background and information about HLS can be found on: wikipedia, encoding.com, and apple.com (as well as many other sites).

Open and Secure HLS Streaming

DuraCloud supports two different types of HLS streaming, open and secure. Open streaming allows anyone with access to the URL for a content item (in a space where open streaming is enabled) to stream that content. The exception to this is if the allowedOrigins parameter is utilized when enabling HLS streaming for a space, which limits browser-based (JavaScript) streaming requests to only certain hosts.

Secure streaming requires that permission be granted before a user is able to stream a file. Your web application will need to determine if the user has the necessary rights, and if so, allow a set of cookies to be set on that user's browser. Those cookies are used to verify that the user has permission to stream the files in a space. The request to generate those cookies can set further limits, such as the length of time the user will have access and the IP address range where the streaming is allowed to take place. The purpose of secure streaming is to restrict the use of the stream. This is ideal for scenarios where streamed content is not free to use or must only be provided to a limited audience.

Using HLS Streaming

Follow these steps to stream media files with DuraCloud using HLS

  1. Create a space in DuraCloud which you will use to host streamed files
  2. Transfer media files to the space. Be sure that the files have been transcoded to support HLS (.ts and .m3u8 files are expected)
  3. Enable streaming
    1. To enable open streaming: Select the space in the DuraCloud interface and click the "ON" button next to "HLS Streaming:" in the Streaming section of the Space Detail pane. Alternatively, open streaming can be enabled using the same enable-streaming call as secure streaming, but with the "secure" parameter set to 'false".
    2. To enable secure streaming: Perform a POST HTTP call to the URL https://{institution}.duracloud.org/durastore/task/enable-streaming. The body of the POST request should include this JSON document: {"spaceId" : "","secure" : "true"}. Fill in the ID of the space to stream. Note that this call is using the DuraCloud REST API.
    3. For either open or secure streaming, if you would like to limit the hosts able to stream content, include the "allowedOrigins" parameter with a list of allowed origin values. For example, to allow calls from example.com and my.test.com, the value of allowedOrigins would be: ["https://example.com","https://my.test.com"]. Note that it is necessary to include the protocol as part of the origin, and that "http://" is considered different than "http://". The default allowedOrigins value is ["https://*"], which allows calls from all sites using an https protocol.
  4. Wait up to 15 minutes. If this is the first time the space has been streamed, it can take up to 15 minutes for the files to be available on the Amazon edge servers.
  5. Stream a file
    1. When using open streaming: 
      1. Select an HLS index (playlist) file in the space. A video player will appear in the Content Detail pane. Verify that you are able to play the streamed file.
      2. Look in the space properties for the HLS streaming host address. This is the path you will use for streaming files. Alternatively, you can perform a get-url-hls task call through the DuraCloud REST API to retrieve the streaming URL for each content item to be streamed. These URLs are predictable and do not expire.
    2. When using secure streaming:
      1. Spaces using secure streaming do not provide playback via the DuraCloud UI. You will need to perform a "get-signed-cookies-url" call, then redirect the user to the returned URL. More details about the get-signed-cookies-url call can be found in the Amazon S3 Storage Provider tasks section of the DuraCloud REST API.
  6. Set up your website or application to provide access to the streamed files.

RTMP Streaming

The Media Streaming capabilities provided by DuraCloud allow video and audio files to be streamed over RTMP. This feature in DuraCloud takes advantage of Amazon CloudFront streaming, so files to be streamed must be within spaces on an Amazon provider. This type of streaming uses the Flash Media Server to host streaming files over RTMP. File formats supported include MP3, MP4 and FLV among others. For a full listing of supported file types see the Flash Media Server documentation.

...

DuraCloud supports two different types of RTMP streaming, open and secure. Open streaming allows anyone with access to the URL for a streamed content item to stream the content. This works well for open access content which is intended to be shared and accessed widely. Secure streaming requires that a request be made to DuraCloud to retrieve a signed URL. That signed URL can then be used to stream the file. The request to retrieve a signed URL can specify how long the content will be available to stream (the default is 8 hours) as well as the IP address or IP address range where the streaming is allowed to take place. The purpose of secure streaming is to restrict the use of the stream. This is ideal for scenarios where streamed content is not free to use or must only be provided to a limited audience. Note that both types of streaming, open and secure, use the RTMP protocol, which protects the source file from being downloaded. The RTMP protocol requires that a flash-based streaming media player be used to play the streamed content.

...

Follow these steps to stream media files with DuraCloud using RTMP

  1. Create a space in DuraCloud which you will use to host streamed files
  2. Transfer media files to the space. Be sure that the file files are using supported formats (see the link above).
  3. Enable streaming
    1. To enable open streaming: Select the space in the DuraCloud interface and click the "ON" button next to "RTMP Streaming:" in  in the top row of buttonsStreaming section of the Space Detail pane. Alternatively, open streaming can be enabled using the same enable-streaming call as secure streaming, but with the "secure" parameter set to 'false".
    2. To enable secure streaming: Perform a POST HTTP call to the URL https://{institution}.duracloud.org/durastore/task/enable-streaming. The body of the POST request should include this JSON document: {"spaceId" : "","secure" : "true"}. Fill in the ID of the space to stream. Note that this call is using the DuraCloud REST API.
  4. Wait up to 15 minutes. If this is the first time the space has been streamed, it can take up to 15 minutes for the files to be available on the Amazon edge servers.
  5. Stream a file
    1. When using open streaming: 
      1. Select a media file in the space. A video player will appear in the Content Detail pane. Verify that you are able to play the streamed file.
      2. Look in the space properties for the RTMP streaming address. This is the path you will use for streaming files. Alternatively, you can perform a get-url task call through the DuraCloud REST API to retrieve the streaming URL for each content item to be streamed. These URLs are predictable and do not expire.
    2. When using secure streaming:
      1. Spaces using secure streaming do not provide playback via the DuraCloud UI. You will need to perform a "get-signed-url" call to retrieve a signed URL for each content item to be streamed, and stream the file through an RTMP compatible player. More details about the get-signed-url call can be found in the Amazon S3 Storage Provider tasks section of the DuraCloud REST API.
  6. Set up your website or application to provide access to the streamed files. Some example files to get you started are listed below.

Warning

The Flash Media Server used by Amazon CloudFront and media players like JWPlayer and Flowplayer require certain specific conventions for requesting streamed files. There are two primary variables, one being a prefix which may need to precede the file name (example prefix values are "mp3:" and "mp4:"). The other variable is whether a file extension is allowed on the file name. Getting these combinations right is particularly important when using secure streaming, as the player cannot request the file with alternative file names to match its preferences. Not all file types use the same combination of prefix and file extension settings. For example, it is common for MP4 files to require a prefix and extension (example file name: "mp4:videofile.mp4") while MP3 files require a prefix but no extension (example file name: "mp3:audiofile").

The prefix value, when needed, should be added to the stream path by using the "resourcePrefix" parameter on the get-url or get-signed-url call made through the DuraCloud REST API.

In most cases, the file extension will need to be part of the stored file name. Even if files are named with a file extension (which is typically the case), calls to retrieve a streaming URL can specify the file name with no extension.

RTMP Integration Demo Files

The following files are available as a bundle here.
They are intended as a starting point for integrating streaming media into your own website.

...

All of the above files are intended as examples only. Their purpose is to give developers a starting point for embedding video streamed by DuraCloud on their own web pages.

...