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.
- 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.
- To generate a new access key, click Add Access Key.
- 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 the Wowza GoCoder™ 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
Parameter | Data Type | Description |
aspect_ratio_height | integer | The height, in pixels, of the output rendition. Should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Use the default, 1080. |
aspect_ratio_width | integer | The width, in pixels, of the output rendition. Should correspond to the aspect ratio (widescreen or standard) of the video source and be divisible by 8. Use the default, 1920. The greater the source aspect ratio, the more bitrate renditions Wowza Streaming Cloud creates of the live stream. The highest supported widescreen aspect ratio, 3840x2160, generates 7 bitrate renditions. The highest supported standard aspect ratio, 768x576, generates 4 bitrate renditions. |
billing_mode | string | The billing mode for the stream. Use the default, pay_as_you_go. |
broadcast_location | string |
Specify the region that's closest to where your stream originates. Valid values are asia_pacific_australia, asia_pacific_india, asia_pacific_japan, asia_pacific_s_korea, asia_pacific_singapore, asia_pacific_taiwan, eu_belgium, eu_germany, eu_ireland, south_america_brazil, us_central_iowa, us_east_s_carolina, us_east_virginia, us_west_california, and us_west_oregon. Notes: |
closed_caption_type | string | The type of closed caption data being passed from the source. For this example, use the default, none, indicating that no data is being provided. |
delivery_method | string | The method you're using to deliver the source stream to the transcoder. Use push, the default, to push the stream directly to Wowza Streaming Cloud from the Wowza GoCoder app. |
encoder | string | Specify wowza_gocoder to use the Wowza GoCoder mobile encoding app as the video source for the live stream. |
name | string | The name of the live stream. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyLiveStream. |
password | string | A password for authenticating an RTMP or RTSP push connection. Can contain only uppercase and lowercase letters; numbers; and the period (.), underscore (_), and hyphen (-) characters. No other special characters can be used. If you don't specify a password, Wowza Streaming Cloud will generate one for you. |
transcoder_type | string | Transcoders can be either transcoded, for streams that are transcoded into adaptive bitrate renditions, or passthrough, for streams that aren't processed by the transcoder. Specify the default, transcoded.
Note: Adaptive bitrate transcoding (transcoded) is available at all broadcast locations. Passthrough transcoding is only available at asia_pacific_taiwan, eu_belgium, us_central_iowa, and us_east_s_carolina.
|
username | string | A username for authenticating an RTMP or RTSP push connection. Can contain only uppercase and lowercase letters; numbers; and the period (.), underscore (_), and hyphen (-) characters. No other special characters can be used. If you don't specify a username, Wowza Streaming Cloud will generate one for you. |
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.
Parameter | Data Type | Description |
player_countdown | Boolean | A clock that appears in the player before the event and counts down to the start of the stream. Specify true to display the countdown clock. The default is false. |
player_countdown_at | datetime | The date and time that the event starts, used by the countdown clock. Specify YYYY-MM-DD HH:MM:SS, where HH is a 24-hour clock in UTC. |
player_logo_image | string | A Base64-encoded string representation of a GIF, JPEG, or PNG logo file that appears partially transparent in a corner of the player throughout playback. Must be 2.5 MB or smaller. |
player_logo_position | string | If a player logo is used, the corner of the player in which you want the player logo to appear. The default is top-left. Other accepted values are top-right, bottom-left, and bottom-right. |
player_responsive | Boolean | A player whose size adjusts according to the device on which it's being viewed. The default, true, creates a responsive player. If false, Wowza Streaming Cloud creates a fixed-width player. |
player_type | string | The player you want to use. Select wowza_player to provide HTML5 playback over Apple HLS. wowza_player requires that target_delivery_protocol be hls and closed_caption_type be none. |
player_video_poster_image | string | A Base64-encoded string representation of a GIF, JPEG, or PNG poster image that appears in the player before the stream begins. Must be 2.5 MB or smaller. |
player_width | integer | The width, in pixels, of a fixed-width player. The default is 640. The player height is calculated automatically based on the aspect ratio of the source. If player_responsive is true, player_width is 0. |
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.
Parameter | Data Type | Description |
hosted_page | Boolean | Use the default, true, to generate the hosted page. |
hosted_page_description | string | An optional description that appears on the hosted page below the player. Can't include custom HTML, JavaScript, or other tags. |
hosted_page_logo_image | string | A Base64-encoded string representation of a GIF, JPEG, or PNG logo file that appears in the upper-left corner of the hosted page. Must be 2.5 MB or smaller. |
hosted_page_sharing_icons | Boolean | Icons that let viewers share the stream on Facebook, Google+, Twitter, and by email. Use the default, true, to include sharing icons on the hosted page. |
hosted_page_title | string | A title for the page that appears above the player. Can't include custom HTML, JavaScript, or other tags. If blank, Wowza Streaming Cloud uses the live stream name as the hosted page title. |
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", "playback_stream_name": "f8758cd3", "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" "webrtc" ], "source_connection_information": { "primary_server": "[wowzasubdomain].entrypoint.cloud.wowza.com", "host_port": 1935, "application": "app-B8P6K226", "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].wowza.com/1/abcdTnJwZEpwXYZa/aBcDeGd1/hls/live/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"], "webrtc": ["names, output_ids, and urls returned here"] }, "created_at": "2019-10-16T14:39:50.000Z", "updated_at": "2019-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.
- Start the GoCoder app on your mobile device.
- Tap the Connect icon (the Wowza gear).
- In the Connect To menu, tap Wowza Streaming Cloud.
- For Connection Code, enter the Wowza Streaming Cloud live stream's connection code, for example, 0ab334.
- 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.
- Start the GoCoder app on your mobile device.
- Tap the Connect button (the Wowza gear icon) in the upper-right corner of the app.
- In the Connect To menu, tap Wowza Streaming Engine.
- 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.
- Tap Application, enter the application and stream_name values, and then tap Back.
- Tap Source Authentication and enter the username and password values.
- 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
- 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]"
- 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.