Manage Apple HLS playback over SSL with the Wowza Streaming Cloud REST API

When you broadcast an Apple HLS stream using the Wowza Streaming Cloud™ service, you have complete control over whether or not Secure Socket Layer (SSL) is used to establish a handshake for encrypting the HTTP connections that deliver the stream to viewers. By default, Wowza Streaming Cloud uses relative playlists, which allows streams to be played over HTTP or HTTPS—or both. This provides the greatest flexibility for your viewers. You can, however, require that viewers watch a live stream over HTTP or HTTPS. Requiring viewers to watch a stream over HTTPS ensures an encrypted connection during playback. You can also configure Wowza Streaming Cloud to send the stream from the transcoder to the target using SSL, allowing encryption during this data transfer.

About SSL playback from Wowza Streaming Cloud stream targets


Streams delivered from Wowza Streaming Cloud travel across the internet in two stages to reach their audiences. After Wowza Streaming Cloud transcodes (or passes through) the encoded live source video, it sends the stream to geographically distributed servers. Those servers then deliver the stream to viewers, such as through a hosted webpage or a direct playback URL.

Wowza Streaming Cloud uses the HTTP protocol to make these two outbound network transfers, delivering streams for playback over Apple HLS or over Apple HLS and Adobe HDS. For both types of HTTP delivery, Wowza Streaming Cloud generates a relative playlist, which means that the stream can be viewed over HTTP or HTTPS. The viewer is not restricted to the secure or unsecured protocol.

When you choose to deliver a stream over Apple HLS only, you can enjoy the default flexibility of relative playlists, or you can control whether the viewer has to use HTTP or HTTPS to watch the stream by editing the stream target’s properties. In the Wowza Streaing Cloud REST API, Apple HLS only streams are available using Wowza stream targets and custom stream targets with the provider akamai_cupertino.

Stream target SSL playback cheat sheet


Three stream target properties are used to manage SSL playback for HLS streams. Here's a table that summarizes how to configure those properties for the type of playback you want to support.

Tip: Click the desired result to jump to instructions on how to configure the target with these settings.
Desired result Send stream to target over SSL Play over SSL Relative Playlists
Play HLS over HTTP or HTTPS True* False (default) True (default)
Play HLS over HTTPS True* True False
Play HLS over HTTP False (default)* False (default) False

* Sending the stream from the transcoder to the target over SSL isn't required for secure playback, but it's good practice to use SSL for the connection in and out of the target to keep communications as secure as possible.

Deliver an HLS stream that can be played over HTTP or HTTPS


Live stream workflow — HTTP or HTTPS

The easiest option is to create a live stream that plays Apple HLS over HTTP or HTTPS.

  1. Using the Wowza Streaming Cloud REST API, create a live stream with the target_delivery_protocol set to hls-https (the default value).

    Example request and response

    Notes:
    • For [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
    • For [version], substitute the version number of the API that you're using. For the current version, use v1.2.
    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{ 
       "live_stream": { 
         "aspect_ratio_height": 720, 
         "aspect_ratio_width": 1280, 
         "billing_mode": "pay_as_you_go", 
         "broadcast_location": "us_west_california",    
         "delivery_method": "push", 
         "encoder": "wowza_gocoder", 
         "hosted_page": true, 
         "hosted_page_sharing_icons": true, 
         "name": "MyLiveStream", 
         "player_countdown": false, 
         "player_responsive": true, 
         "player_type": "original_html5", 
         "target_delivery_protocol": "hls-https", 
         "transcoder_type": "transcoded"
       } 
    }' "https://api.cloud.wowza.com/api/[version]/live_streams" 

    The request creates a live stream with an id parameter, an associated player, and a hosted page. The details of live stream's configuration are listed in the response, which should look something like this:

    { 
       "live_stream": { 
         "aspect_ratio_height": 720, 
         "aspect_ratio_width": 1280, 
         "billing_mode": "pay_as_you_go", 
         "broadcast_location": "us_west_california", 
         ... 
         "direct_playback_urls": [ 
           { "rtmp":  ["names, output_ids, and urls returned here"]}, 
           { "rtsp": ["names, output_ids, and urls returned here"]}, 
           { "wowz": ["names, output_ids, and urls returned here"]} 
         ], 
         "encoder": "wowza_gocoder", 
         "hosted_page": true, 
         "hosted_page_sharing_icons": true, 
         "hosted_page_title": "MyLiveStream", 
         "hosted_page_url": "in_progress", 
         "id": "1234abcd", 
         ...
         "player_embed_code": "in_progress", 
         "player_hls_playback_url": "https://[wowzasubdomain]-f.akamaihd.net/i/32a5814b_1@7217/master.m3u8", 
         "player_id": "[UniqueIDReturnedHere]" 
         ...
         "source_connection_information": { 
           "application": "app-464b", 
           "disable_authentication": false, 
           "host_port": 1935, 
           "password": "1234abcd", 
           "primary_server": "[subdomain].entrypoint.cloud.wowza.com", 
           "stream_name": "32a5814b", 
           "username": "client2" 
         }, 
         "stream_targets": [ 
           { 
             "id": "[UniqueIDReturnedHere]" 
           } 
         ], 
         "target_delivery_protocol": "hls-https", 
         "transcoder_type": "transcoded", 
         "updated_at": "2018-11-24T12:06:38.532", 
         "use_stream_source": false 
       } 
    }
    Note:  Initially, the response for the player embed code and hosted page URL indicates that they're "in progress." To get the code and URL, use a GET request to retrieve the live stream's details.
    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]" 
    The POST /live_streams request automatically creates a Wowza stream target with the relativePlaylists property set to the default value of true. This allows the viewer to watch the stream over HTTP and HTTPS, whichever protocol their browser calls. 
  2. Depending on how you want to make the stream available, do one of the following using details from the live stream.
    • Use the Apple HLS playback URL returned as the player_hls_playback_url value to play the stream in a browser or player that supports Apple HLS. Although the playback URL appears as HTTPS, the playback URL can also be accessed using HTTP.
      For example:
      https://[wowzasubdomain]-f.akamaihd.net/i/32a5814b_1@7217/master.m3u8
    • If you created a hosted page, use the hosted_page_url value to share the hosted page URL. Although the hosted page URL appears as HTTPS, the page can also be viewed using HTTP.
      For example:
      https://player.cloud.wowza.com/hosted/[player_id]/player.html
    • If you want to include the stream on an external website (HTTP or HTTPS), use the player_embed_code value, which uses a relative URL in the JavaScript call for the player.
      For example:
      <div id='wowza_player'></div>\n<script id='player_embed' src='//player.cloud.wowza.com/hosted/[player_id]/wowza.js' type='text/javascript'></script>\n

Transcoder workflow — HTTP or HTTPS

For a more modular API workflow with detailed control over configuration, you can create a transcoder with outputs and stream targets that play Apple HLS over HTTP or HTTPS.

  1. Using the Wowza Streaming Cloud REST API, create a transcoder. Depending on your streaming setup needs, you can specify a delivery_method of push or pull and a transcoder_type of passthrough or transcoded (ABR).

    Example request and response

    Create a transcoder

    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{ 
       "transcoder": { 
         "billing_mode": "pay_as_you_go", 
         "broadcast_location": "us_west_california", 
         "buffer_size": 4000, 
         "delivery_method": "push", 
         "name": "MyABRtranscoder", 
         "protocol": "rtmp", 
         "transcoder_type": "transcoded" 
     } 
    }' "https://api.cloud.wowza.com/api/[version]/transcoders" 

    The request creates a transcoder and returns a response that includes details of the transcoder, including its unique transcoder ID. There are no outputs associated with the transcoder yet. Make note of the ID, which is the transcoder ID that Wowza Streaming Cloud creates for your stream. You'll need it to associate your transcoder with output renditions and stream targets. The response should look something like this:

    { 
        "transcoder": { 
            "id": "432vwp8k", 
            "name": "MyABRtranscoder", 
            "transcoder_type": "transcoded", 
            "billing_mode": "pay_as_you_go", 
            "broadcast_location": "us_west_california", 
            ...
            "protocol": "rtmp", 
            "delivery_method": "push", 
            "source_port": 1935, 
            "domain_name": "[wowza-subdomain].entrypoint.cloud.wowza.com", 
            "application_name": "app-5b86", 
            "stream_name": "805e7031", 
            ...
            "username": "client2", 
            "password": "456d2f30", 
            "watermark": false, 
            "created_at": "2018-08-01T16:38:03.000Z", 
            "updated_at": "2018-08-01T16:38:03.000Z", 
            "direct_playback_urls": { 
                "rtmp": ["names and urls returned here"], 
                "rtsp": ["names and urls returned here"], 
                "wowz": ["names and urls returned here"] 
            }, 
            "outputs": [], 
        } 
    }

  2. Complete the transcoder by adding outputs and stream targets, but keep the following in mind:
    • Create either a custom stream target or a Wowza stream target. Ultra low latency stream targets do not work with this workflow.
    • Ensure that your stream target has a provider of akamai_cupertino. This will enable the relativePlaylists stream target property by default, allowing viewers to play your stream over HTTP or HTTPS.
    For instructions on adding output renditions and stream targets, see one of the following articles, depending on whether you're creating an adaptive-bitrate or passthrough transcoder:
  3. Refer to the hls_playback_url value returned in the stream target details. Use this URL to play the stream in a browser or player that supports Apple HLS. Although the playback URL appears as HTTPS, the playback URL can also be accessed using HTTP.
    For example:
    https://[wowzasubdomain]-f.akamaihd.net/i/32a5814b_1@7217/master.m3u8

Deliver an HLS stream that can only be played over HTTPS


You can require SSL for HLS playback, if desired. This ensures that viewer clients connect securely to view the stream. You can also optionally send the stream from the transcoder to the target using SSL. 

Live stream workflow —HTTPS only

The simpler option for HTTPS-only playback is to create a live stream that plays Apple HLS over HTTPS only.

  1. Using the Wowza Streaming Cloud REST API, create a live stream with target_delivery_protocol set to hls-https (the default value). For instructions, see step 1 of Live stream workflow — HTTP or HTTPS.
  2. In the response to the POST /live_streams request, note the stream target id for the next step.
  3. Configure properties for the stream target associated with your live stream. See Configure stream target properties to delivery an HLS stream for playback over HTTPS only.

Transcoder workflow — HTTPS only

For a more modular API workflow with detailed control over configuration, you can create a transcoder with outputs and stream targets that play Apple HLS over HTTPS only.

  1. Using the Wowza Streaming Cloud REST API, create a transcoder. Depending on your streaming setup needs, you can specify a delivery_method of push or pull and a transcoder_type of passthrough or transcoded (ABR).
    For instructions, see steps 1 and 2 of Transcoder workflow — HTTP and HTTPS.
  2. Configure properties for the stream target or stream targets that you associated with your transcoder. See Configure stream target properties to delivery an HLS stream for playback over HTTPS only.

Configure stream target properties to delivery an HLS stream for playback over HTTPS only

Configure the following properties for the stream target one at a time. The sendSSL property is optional but recommended.

Key (property name) Section Value Description
sendSSL hls true When true, Wowza Streaming Cloud sends the stream from the transcoder to the target using SSL (HTTPS).
playSSL playlist true When true, the target sends the stream to the player using SSL (HTTPS).
relativePlaylists playlist false When false, the viewer's playback protocol (HTTP or HTTPS) must correspond to the target's specified playback protocol.

Example request and response

Configure a property for a stream target

curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{   
  "property": {     
  "key": "playSSL",     
  "section": "playlist",     
  "value": true  
  } 
}'   "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/" 

This request assigns the value true to the playSSL stream target property. The details of the target's property are listed in the response, which should look something like this:

{    
  "property": {      
    "key": "playSSL",      
    "section": "playlist",      
    "value": true 
  } 
} 

For more information about configuring stream target properties and related requests, see How to set advanced properties using the Wowza Streaming Cloud REST API.

Playback over HTTPS only

Live stream workflow

Do one of the following for playback over HTTPS only, depending on how you want to make your live stream available:

  • Use the Apple HLS playback URL returned as the player_hls_playback_url value to play the stream in a browser or player that supports Apple HLS. The playback URL can only be accessed using HTTPS.
    For example:
    https://[wowzasubdomain]-f.akamaihd.net/i/32a5814b_1@7217/master.m3u8
  • If you created a hosted page, use the hosted_page_url value to share the hosted page URL. The hosted page can only be viewed using HTTPS.
    For example:
    https://player.cloud.wowza.com/hosted/[player_id]/player.html
  • If you want to include the stream on an external website (HTTPS), use the player_embed_code value, which uses a relative URL in the JavaScript call for the player.
    For example:
    <div id='wowza_player'></div>\n<script id='player_embed' src='//player.cloud.wowza.com/hosted/[player_id]/wowza.js' type='text/javascript'></script>\n

Transcoder workflow

For playback over HTTPS only, refer to the hls_playback_url value returned in the stream target details. Use this URL to play the stream in a browser or player that supports Apple HLS. The playback URL can only be accessed using HTTPS.
For example:
https://[wowzasubdomain]-f.akamaihd.net/i/32a5814b_1@7217/master.m3u8

Deliver an HLS stream that can only be played over HTTP


Live stream workflow —HTTP only

The simpler option for HTTP-only playback is to create a live stream that plays Apple HLS over HTTP only.

  1. Using the Wowza Streaming Cloud REST API, create a live stream with target_delivery_protocol set to hls-https (the default value). For instructions, see step 1 of Live stream workflow — HTTP or HTTPS.
  2. In the response to the POST /live_streams request, note the stream target id for the next step.
  3. Configure properties for the stream target associated with your live stream. See Configure stream target properties to delivery an HLS stream for playback over HTTP only.

Transcoder workflow — HTTP only

For a more modular API workflow with detailed control over configuration, you can create a transcoder with outputs and stream targets that play Apple HLS over HTTP only.

  1. Using the Wowza Streaming Cloud REST API, create a transcoder. Depending on your streaming setup needs, you can specify a delivery_method of push or pull and a transcoder_type of passthrough or transcoded (ABR).
    For instructions, see steps 1 and 2 of Transcoder workflow — HTTP and HTTPS.
  2. Configure properties for the stream target or stream targets that you associated with your transcoder. See Configure stream target properties to delivery an HLS stream for playback over HTTP only.

Configure stream target properties to delivery an HLS stream for playback over HTTP only

Configure the following properties for the stream target one at a time. The sendSSL property is optional, and the sendSSL and playSSL properties are false by default. If you have already set them to true, you can configure them to false using the example request below to reset the value.

Key (property name) Section Value Description
sendSSL hls false When false, Wowza Streaming Cloud sends the stream from the transcoder to the target using HTTP.
playSSL playlist false When false, the target sends the stream to the player using HTTP.
relativePlaylists playlist false When false, the viewer's playback protocol (HTTP or HTTPS) must correspond to the target's specified playback protocol.
 

Example request and response

Configure a property for a stream target

curl --header 'wsc-api-key: [key]' --header 'wsc-access-key: [key]' --header 'Content-Type: application/json' -X POST -d '{   
  "property": {     
  "key": "relativePlaylists",     
  "section": "playlist",     
  "value": false  
  } 
}'   "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/" 

This request assigns the value false to the relativePlaylists stream target property. The details of the target's property are listed in the response, which should look something like this:

{    
  "property": {      
    "key": "relativePlaylists",      
    "section": "playlist",      
    "value": false 
  } 
} 

For more information about configuring stream target properties and related requests, see How to set advanced properties using the Wowza Streaming Cloud REST API.

More resources