Get started broadcasting a live stream using the Wowza Streaming Cloud REST API

Learn how to use the REST API to send a single encoded stream through the Wowza Streaming Cloud™ service, transcode it to multiple bitrate renditions, and deliver the stream to a player on a Wowza Streaming Cloud-hosted webpage. Then, learn how to programmatically start and stop the live stream and view it on the hosted page.

Note: For information on the Wowza Streaming Cloud free trial and its feature limitations, see Wowza Streaming Cloud free trial.

Prepare authentication for your request

---

Note: The Wowza Streaming Cloud REST API uses hash-based message authentication code (HMAC) for secure authentication in production environments. In this form of authentication, the API key is a private, secret key. It is known to you and the Wowza Streaming Cloud service but never sent directly in an API request. To learn more, see HMAC Authentication.

For initial Wowza Streaming Cloud REST API testing only, you can use API key and access key authentication.

Both the API key and the access key can be found in the Wowza Streaming Cloud user interface.

1. In the menu bar, click your user name and choose API Access.

Your API key appears in the middle of the Wowza Streaming Cloud REST API page.
Access keys are listed in the Access Keys panel on the left side of the page.

2. To generate a new access key, click Add Access Key.
3. Leave Enabled selected so that the key is immediately available, and provide an optional Description. Then, click Add.

Wowza Streaming Cloud generates the key.

You can disable and re-enable the access key at any time, and edit the description.

Create a live stream

---

Create a Wowza Streaming Cloud live stream that receives a stream from Wowza GoCoder™, an RTSP-based encoding app for Apple iOS and Android mobile devices. 

Refer to the parameters and example request below to construct your API request. Example requests are presented in curl using environment variables, but you can also use a GUI REST client for API testing such as Postman or Paw.

For detailed reference information, see the Wowza Streaming Cloud REST API Reference Documentation.

If you have basic questions about using a REST API, start with About the Wowza Streaming Cloud REST API.

Ingest parameters

Player parameters

By default, creating a live stream generates a player that viewers can use to watch the event. The player can be embedded on a webpage hosted by the Wowza Streaming Cloud service, or you can embed it in a third-party site.

For this example, customize the player using the following parameters.

Hosted page parameters

By default, creating a live stream generates a webpage hosted by the Wowza Streaming Cloud service. The webpage includes the hosted player. Customize the hosted webpage for this example using the following parameters.

Example request and response

The following request generates a live stream that uses Wowza GoCoder as the video source and is delivered to viewers using a responsive player and webpage hosted by Wowza Streaming Cloud.

Notes:

• To authenticate API requests, use HMAC authentication for production environments. For testing or proof of concept purposes only, use API key and access key authentication.
• The curl examples below use environment variables, ${WSC_API_KEY}, ${WSC_ACCESS_KEY}, ${WSC_VERSION}, and ${WSC_HOST} for the Wowza Streaming Cloud API key, access key, version number, and your host. See Using cURL for more information on how to set these up.

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "live_stream": {
     "aspect_ratio_height": 1080,
     "aspect_ratio_width": 1920,
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "closed_caption_type": "none",
     "delivery_method": "push",
     "encoder": "wowza_gocoder",
     "hosted_page": true,
     "hosted_page_sharing_icons": true,
     "name": "MyLiveStream",
     "player_responsive": true,
     "player_type": "wowza_player",
     "transcoder_type": "transcoded"
   }
}' "${WSC_HOST}/api/${WSC_VERSION}/live_streams"

The command 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. You'll use the connection code or the source connection information to configure the Wowza GoCoder app as a source for the live stream.

{
    "live_stream": {
        "id": "abcntjvl",
        "name": "MyLiveStream",
        "transcoder_type": "transcoded",
        "billing_mode": "pay_as_you_go",
        "broadcast_location": "us_west_california",
        "recording": false,
        "closed_caption_type": "none",
        "low_latency": false,
        "encoder": "wowza_gocoder",
        "delivery_method": "push",
        "target_delivery_protocol": "hls-https",
        "use_stream_source": false,
        "aspect_ratio_width": 1920,
        "aspect_ratio_height": 1080,
        "connection_code": "07yqLI",
        "connection_code_expires_at": "2018-10-17T14:39:50.000Z",
        "delivery_protocols": [
            "rtmp",
            "rtsp",
            "wowz",
            "hls"
        ],
        "source_connection_information": {
            "primary_server": "[wowzasubdomain].entrypoint.cloud.wowza.com",
            "host_port": 1935,
            "application": "app-8f5c",
            "stream_name": "4d3db5e1",
            "disable_authentication": false,
            "username": "client2",
            "password": "cde44772"
        },
        "player_id": "ly4rnpyt",
        "player_type": "wowza_player",
        "player_responsive": true,
        "player_countdown": false,
        "player_embed_code": "in_progress",
        "player_hls_playback_url": "https://[wowzasubdomain].akamaihd.net/hls/live/620367/be4fb5a4/playlist.m3u8",
        "hosted_page": true,
        "hosted_page_title": "MyLiveStream",
        "hosted_page_url": "in_progress",
        "hosted_page_sharing_icons": true,
        "stream_targets": [
            {
                "id": "jjwwxxpk"
            }
        ],
        "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"]
        },
        "created_at": "2018-10-16T14:39:50.000Z",
        "updated_at": "2018-10-16T14:39:50.000Z"
    }
}

Configure the source

---

Use the connection code or the source connection information from the live stream you created to configure the Wowza GoCoder mobile app.

First, download the free Wowza GoCoder app for iOS from the Apple Store or for Android from Google Play.

Connect the GoCoder app using a connection code

The easiest connection method is using the connection code value returned when you created the live stream with the REST API.

1. Start the GoCoder app on your mobile device.
    
2. Tap the Connect icon (the Wowza gear).
3. In the Connect To menu, tap Wowza Streaming Cloud.

3. For Connection Code, enter the Wowza Streaming Cloud live stream's connection code, for example, 0ab334.

1. Tap Done.

Connect the GoCoder app manually

To manually configure the app, use the live stream's source connection information from the REST API response to connect the app to Wowza Streaming Cloud. This connection method is useful for troubleshooting a connection with a connection code that isn't working as expected.

1. Start the GoCoder app on your mobile device.
    
2. Tap the Connect button (the Wowza gear icon) in the upper-right corner of the app.
    
3. In the Connect To menu, tap Wowza Streaming Engine.

4. Tap Host. For Server enter the primary_server value from your Wowza Streaming Cloud live stream (without rtsp:// at the start of the URL). For Port enter the live stream's host_port value. Then, tap Back.

5. Tap Application, enter the application and stream_name values, and then tap Back.

6. Tap Source Authentication and enter the username and password values.

7. Tap Done.

Note: You can connect to Wowza Streaming Cloud using a number of different sources. See these articles for more information:

• Connect an RTMP encoder to Wowza Streaming Cloud using the Wowza Streaming Cloud REST API
• Send a stream from Wowza Streaming Engine to a Wowza CDN HLS target using Wowza APIs
• Send a stream from Wowza Streaming Engine to Wowza Streaming Cloud for transcoding using Wowza APIs or Wowza Streaming Engine Manager
• How to connect to Wowza Streaming Cloud with GoCoder SDK for iOS
• How to connect to Wowza Streaming Cloud with GoCoder SDK for Android

Start the live stream

---

When the live stream is created and the source is configured, use the PUT method to start it. Wowza Streaming Cloud will transcode the stream coming from the source and send it to the player for viewing on the hosted page.

Start the live stream:

curl -X PUT \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
"${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/start"

View the stream on the hosted page

---

1. Initially, after creating the live stream using the REST API, the information in the response for the hosted page URL shows that it's "in progress." To find the URL, use the GET method to retrieve the live stream's details.
   
   Get details about the live stream:
    

   curl -X GET \
   -H "wsc-api-key: ${WSC_API_KEY}" \
   -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
   "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]"

2. Enter the hosted_page_url value into a browser to open the hosted page and view the live stream.

Stop the live stream

---

After viewing the live stream on the hosted page, use the PUT method to stop it.

Stop the live stream:

curl -X PUT \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
"${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/stop"

 

Note: Transcoding charges accrue for started live streams even if they aren't actively streaming content. Wowza Streaming Cloud automatically stops idle live streams after 20 minutes, but you should stop your stream as soon as your event ends to avoid accruing unnecessary charges.

More resources

---

• About the Wowza Streaming Cloud REST API
• General Examples for the Wowza Streaming Cloud REST API
• Wowza Streaming Cloud REST API reference documentation
• Use Wowza Player with Wowza Streaming Cloud