• How to broadcast a live stream by 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.

    Contents


    Create a live stream
    Start and stop the live stream

    Create a live stream


    Start by creating a Wowza Streaming Cloud live stream that receives a stream from a source encoder.

    Ingest parameters

    Parameter Data Type Description
    name string The name of the live stream. Enter an alphanumeric string that is short (maximum 200 characters) and descriptive, for example, MyLiveStream.
    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.
    billing_mode string The billing mode for the stream. The default is pay_as_you_go. If you have a 24x7 subscription, choose pay_as_you_go or twentyfour_seven.
    broadcast_location string Specify the region that's closest to where your stream originates.

    For pay-as-you-go subscriptions, specify 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, or us_west_oregon.

    For 24x7 subscriptions, specify asia_pacific_taiwan, eu_belgium, us_central_iowa, or us_east_s_carolina.

    4K streaming (3840x2160 aspect ratio) is not supported at asia_pacific_taiwan, eu_belgium, us_central_iowa, or us_east_s_carolina.
    recording Boolean If true, creates a recording of the live stream. The default is false.
    closed_caption_type string The type of closed caption data being passed from the source. The default, none, indicates that no data is being provided. cea indicates that a CEA closed captioning data stream is being provided. on_text indicates that an onTextData closed captioning data stream is being provided. both indicates that both CEA and onTextData closed captioning data streams are being provided.
    encoder string Specify one of the following values as the video source for the live stream:

    wowza_streaming_engine – Wowza Streaming Engine™. Requires a separate license.

    wowza_gocoder – The RTSP-based Wowza GoCoder™ mobile encoding app for iOS and Android devices.

    axis – A professional network IP camera from Axis Communications.

    epiphan – The Epiphan Pearl encoder.

    hauppauge – The Hauppauge StreamEez-Pro encoder.

    jvc – A JVC ProHD digital camcorder.

    live_u – An LU Series video encoder from LiveU.

    matrox – The Matrox Monarch HD encoder.

    newtek_tricaster – The NewTek TriCaster video production and streaming system.

    osprey – The Osprey Talon encoder.

    sony – The Sony SRG-300SE IP camera.

    telestream_wirecast – The Telestream Wirecast encoder.

    teradek_cube – The Teradek Cube encoder.

    vmix – vMix or vMix Go live production software.

    x_split – XSplit Broadcaster video production software.

    ipcamera – Any IP camera that supports the RTSP protocol.

    other_rtmp – Any encoder that supports RTMP and H.264.

    other_rtsp – Any encoder that supports RTSP and H.264.
    delivery_method string The method you're using to deliver the source stream to the transcoder. Use one of the following valid values to send the source stream to the Wowza Streaming Cloud transcoder:

    pull – (Default) Instructs Wowza Streaming Cloud to pull the stream from the RTMP or RTSP source.

    push – Instructs the RTMP or RTSP source to push the stream directly to Wowza Streaming Cloud.
    delivery_type string If encoder is wowza_streaming_engine, specify the type of stream that Wowza Streaming Engine is delivering to Wowza Streaming Cloud: single-bitrate or multi-bitrate.
    delivery_protocol string The protocol used to deliver the stream for playback. Specify hls, hls-https, or hls-hds.
    low_latency Boolean If delivery_protocol is hls, the stream can be configured as low latency. Specifying true delivers smaller packets to the player to reduce latency. The default is false.
    use_stream_source Boolean Specify false, the default, to send your stream from the encoder directly to Wowza Streaming Cloud.
    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. The default is 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.
    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. The default is 1080.
    source_url string For RTMP and RTSP pull connections. Specify the source encoder or IP camera's web address, without the preceding protocol or trailing slash (/).
    disable_authentication Boolean Authentication is required by default for RTMP and RTSP push connections from a video source to Wowza Streaming Cloud. Specify true to disable authentication with the video source.
    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.
    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.
    video_fallback Boolean Controls what viewers see if the video source disconnects from the transcoder. If true, black video plays. If false (the default), a stream-not-available message appears. Video fallback works only with Apple HLS stream targets.

    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.

    If you don't plan to use the player, disregard the player parameters. Otherwise, customize the player using the following parameters.

    Parameter Data Type Description
    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_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.
    player_video_poster_image string The path to a GIF, JPEG, or PNG poster image that appears in the player before the stream begins. Poster image files must be 2.5 MB or smaller.
    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 The path to a GIF, JPEG, or PNG logo file that appears partially transparent in a corner of the player throughout playback. Logo file 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.

    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 using the following parameters.

    Parameter Data Type Description
    hosted_page Boolean The default, true, generates the hosted page. Specify false to not create a hosted webpage.
    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.
    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_sharing_icons Boolean Icons that let viewers share the stream on Facebook, Google+, Twitter, and by email. The default, true, includes sharing icons on the hosted page. Specify false to omit sharing icons.
    hosted_page_logo_image string The path to a GIF, JPEG, or PNG logo file that appears in the upper-left corner of the hosted page. Logo file must be 2.5 MB or smaller.

    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.

    Note: In all code examples, for [key], substitute your API key or your access key as appropriate. For more information, see Locating and using API and access keys.
    curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "live_stream": {
         "name": "MyLiveStream",
         "transcoder_type": "transcoded",
         "billing_mode": "pay_as_you_go",
         "broadcast_location": "us_west_california",
         "recording": false,
         "closed_caption_type": "none",
         "encoder": "wowza_gocoder",
         "delivery_method": "push",
         "delivery_protocol": "hls",
         "use_stream_source": false,
         "aspect_ratio_width": 1280,
         "aspect_ratio_height": 720,
         "player_responsive": true,
         "player_width": 0,
         "player_countdown": false,
         "hosted_page": true,
         "hosted_page_sharing_icons": true
       }
    }' "https://api.cloud.wowza.com/api/v1/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, which should look something like this:

    {
       "live_stream": {
         "id": "1234abcd",
         "name": "MyLiveStream",
         "transcoder_type": "transcoded",
         "billing_mode": "pay_as_you_go",
         "broadcast_location": "us_west_california",
         "recording": false,
         "encoder": "wowza_gocoder",
         "delivery_method": "push",
         "low_latency": false,
         "delivery_protocol": "hls",
         "use_stream_source": false,
         "aspect_ratio_width": 1280,
         "aspect_ratio_height": 720,
         "connection_code": "033334",
         "connection_code_expires_at": "2015-11-25T12:06:38.453-08:00",
         "source_connection_information": {
           "primary_server": "6022e9.entrypoint.cloud.wowza.com",
           "host_port": 1935,
           "application": "app-464b",
           "stream_name": "32a5814b",
           "disable_authentication": false,
           "username": "client2",
           "password": "1234abcd"
         },
         "video_fallback": "false",
         "player_responsive": true,
         "player_countdown": false,
         "player_embed_code": "in_progress",
         "player_hds_playback_url": "http://wowzadev-f.akamaihd.net/z/32a5814b_1@7217/manifest.f4m",
         "player_hls_playback_url": "http://wowzadev-f.akamaihd.net/i/32a5814b_1@7217/master.m3u8",
         "hosted_page": true,
         "hosted_page_title": "MyLiveStream",
         "hosted_page_url": "in_progress",
         "hosted_page_sharing_icons": true,
         "stream_targets": [
          {
            "id": "zk2n75bj"
          }
        ],
         "created_at": "2015-11-24T12:06:38.451",
         "updated_at": "2015-11-24T12:06:38.532"
       } 
    }
    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 the GET method to retrieve the live stream's details.

    Related requests

    View all live streams for the account:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams"
    View the details of a live stream, including the player embed code and hosted page URL:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]"
    Update a live stream's configuration:

    curl -X PATCH --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "live_stream": {
         "name": "MyDifferentLiveStreamName"
       }
    }' "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]"
    View all players for the account, including the ID for each player:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/players"
    Get the details of a player:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/players/[player_id]"
    Update a player:

    curl -X PATCH --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
       "player": {
         "width": "800"
       }
    }' "https://api.cloud.wowza.com/api/v1/players/[player_id]"

    Start and stop the live stream


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

    Example requests

    Start the live stream:

    curl -X PUT --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]/start"
    Stop the live stream:

    curl -X PUT --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]/stop"

    Related requests

    View a live stream's state:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]/state"
    Possible live stream states are starting, stopping, started, stopped, and resetting.

    View the details of a running live stream:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]/stats"
    Regenerate a live stream's connection code:

    curl -X PUT --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]/regenerate_connection_code"
    Delete a live stream:

    curl -X DELETE --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]"
    View a player's state:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/players/[player_id]/state"
    Possible player states are requested and activated.

    View a live stream's preview image:

    curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/v1/live_streams/[live_stream_id]/thumbnail_url"

    Originally Published: 01-21-2016.
    Updated: 09-22-2016.

    If you're having problems or want to discuss this article, post in our forum.