Set advanced properties with the Wowza Streaming Cloud REST API

Learn how to use the REST API to configure advanced transcoder and stream target properties for the Wowza Streaming Cloud™ service.

Contents


About advanced properties
Transcoder properties
Example transcoder property requests
Stream target properties
Example stream target property requests
More resources

About advanced properties


The Wowza Streaming Cloud REST API provides access to several advanced properties for transcoders and stream targets. These advanced properties can be configured to troubleshoot playback failures of transcoded streams from a camera connected to Wowza Streaming Cloud over RTSP/RTP and to improve playback over Wowza CDN - HLS stream targets.

By default, these properties are enabled and configured to use their default values. You can, however, change them. To do so, for each advanced property, you must specify the section the transcoder or stream target configuration table that contains the property. Then, you specify the property's key-value pair.

Transcoder properties


Important: Change advanced transcoder properties with caution. For most RTSP source connections, none of these settings needs to be changed from the default. Edit them only if your viewers experience failed playback of streams that are produced by cameras connected to Wowza Streaming Cloud via RTSP, transcoded, and sent to Akamai for CDN delivery.
Section Key Value Description
rtsp avSyncMethod Boolean Specifies how Wowza Streaming Cloud synchronizes the audio and video in the RTSP/RTP source stream. Set to true to use timecodes in the RTP stream packets to synchronize the audio and video. Set to false (the default) to use SR packets for synchronization information.
rtsp debugRtspSession Boolean If true, logs extra debug information about the handshake between Wowza Streaming Cloud and the RTSP/RTP source stream. The default, false, generates less-detailed logs.
rtsp maxRtcpWaitTime integer For use if avSyncMethod is false, which means Wowza Streaming Cloud is using Sender Report (SR) packets for A/V synchronization information. Specifies how long, in milliseconds, Wowza Streaming Cloud will wait for SR packets in the RTSP/RTP source stream to arrive. The default is 2000.
rtsp rtpIgnoreProfileLevelId Boolean Attempts to derive the H.264 profile level ID from the sprop parameter data sets in the stream's Session Description Protocol (SDP) message. The ID allows a decoder to recognize the requirements to decode the stream, but many RTSP sources, especially IP cameras, publish an incorrect ID in the SDP message. Set to true to tell Wowza Streaming Cloud to ignore the profile level ID in the sprop parameter data sets of the stream's SDP message when decoding the stream. The default, false, uses the ID in the decoding process.
rtsp rtpIgnoreSpropParameterSets Boolean Attempts to derive the H.264 profile level ID from SPS/PPS NAL units in the stream, if they exist. If the stream's SDP message contains incorrect sprop parameter data sets, try setting this value to true to derive the H.264 profile level ID from the SPS/PPS NAL units in the stream, instead. The default, false, instructs Wowza Streaming Cloud to attempt to derive the H.264 profile ID from sprop parameter sets.
rtsp rtpTransportMode string Specifies the transport mode used to pull an RTSP/RTP stream from an IP camera. The default is interleave, which is RTP over TCP; the alternative is udp, which is TCP over UDP.
rtsp rtspFilterUnknownTracks Boolean If true, removes unidentifiable tracks from the RSTP/RTP source stream. The default, false, leaves unidentifiable tracks in the stream.
rtsp rtspValidationFrequency integer Specifies, in milliseconds, how frequently Wowza Streaming Cloud validates the RTSP/RTP connection. The default is 15000.

Example transcoder property requests


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.

Configure a transcoder property:

curl -X POST --header "Content-Type: application/json" --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" -d '{
   "property": {
     "key": "rtpTransportMode",
     "section": "rtsp",
     "value": "udp"
   } 
}' "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/properties"

The command updates the rtpTransportMode property for the transcoder. The details of the transcoder property are listed in the response, which should look something like this:

{
  "property": {
    "key": "rtpTransportMode",
    "section": "rtsp",
    "value": "udp"
  }
}
Note: If you have started a transcoder at any point before updating its transcoder property, you must reset the transcoder for the property to take effect. This step isn’t necessary if you haven’t started the transcoder at all.

Reset a transcoder

curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/reset"

View all of the properties applied to a transcoder:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/properties"

The property_id, which is required to view or delete a specific property, is a string that contains the property's section and key, connected by a dash. For example, rtsp-rtpTransportMode.

View the details of a specific property applied to a transcoder:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/properties/[property_id]"

Delete a specific property applied to a transcoder:

curl -X DELETE --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/properties/[property_id]"

Stream target properties


Stream target properties are available for Wowza stream targets and custom stream targets whose provider is akamai_cupertino.

Stream target properties

Section Key Value Description
hls chunkSize integer Specifies the duration of the time-based audio and video chunks that Wowza Streaming Cloud delivers to the target. A lower (shorter) duration can reduce latency but may affect playback on some older devices. Valid values are 2, 4, 6, 8, and 10 (the default).
 
Caution: For most HLS stream targets, the segment duration doesn't need to be changed. Edit it only if viewers experience unacceptably long latency.
hls convertAMFData Boolean Determines whether Wowza Streaming Cloud converts AMF data into ID3 tags. ID3 tags allow you to include metadata in your HLS stream. If set to True, Wowza Streaming Cloud listens for AMF data events coming from the source encoder or camera, parses the data events, maps the events to ID3 tags, and sends the ID3 tags in the HLS stream. The default is False.

Note: Although configurable stream target properties are available for Wowza stream targets and custom stream targets whose provider is akamai_cupertino, for ultra low latency stream targets that have HLS enabled, the convertAMFData property is enabled by default on backup HLS streams.
hls sendSSL Boolean Determines whether Wowza Streaming Cloud sends the stream from the transcoder to the target by using SSL (HTTPS). The default, false, sends the stream over HTTP.
playlist playSSL Boolean Determines whether Wowza Streaming Cloud sends the stream from the target to the player by using SSL (HTTPS). playSSL is false by default. If you want to require playback over HTTPS, specify playSSL as true to and set relativePlaylists to false.
playlist playlistSeconds integer (Available from API version 1.1.) The number of seconds in the playlist. The default, 100, results in a chunklist of 10, based on the default chunkSize of 10. Valid values are any integer between 6 and 200.

Tip: For information on how to customize a stream's chunklists by using the playlistSeconds and chunkSize properties, see Create custom chunklists with the Wowza Streaming Cloud REST API.

playlist redundantChunklists Boolean When true, creates and sends a redundant set of chunklists within the playlist. If playback falters, a player that supports redundancy can switch to the redundant chunklists. Check your player's documentation to see if it supports redundant chunklists. The default is false.

Note: Enabling the redundantChunklists property increases playback reliability but doubles egress data usage and associated charges.

playlist relativePlaylists Boolean When true (the default), allows the viewer to watch the stream over HTTP and HTTPS, whichever protocol their browser calls. If false, the viewer's playback protocol (HTTP or HTTPS) must correspond to the target's specified playback protocol.

Example stream target property requests


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": "chunkSize",
    "section": "hls",
    "value": 2
  }
}' "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/"

The command assigns a chunk size of 2 to the target. The details of the target's property are listed in the response, which should look something like this:

{
   "property": {
     "key": "chunkSize",
     "section": "hls",
     "value": 2
   }
}
Note: If you have started a live stream or transcoder at any point before updating a property associated with its stream target, you must reset the live stream or transcoder for the property to take effect. This step isn’t necessary if you haven’t started the live stream or transcoder at all.

Reset a live stream

curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/live_streams/[live_stream_id]/reset"

Reset a transcoder

curl -X PUT --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/transcoders/[transcoder_id]/reset"

View all of the properties applied to a stream target:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties"

The property_id, which is required to view or delete a specific property, is a string that contains the property's section and key, connected by a dash. For example, hls-chunkSize.

View the details of a specific property applied to a stream target:

curl -X GET --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/[property_id]"

Delete a specific property applied to a stream target:

curl -X DELETE --header "wsc-api-key: [key]" --header "wsc-access-key: [key]" "https://api.cloud.wowza.com/api/[version]/stream_targets/[stream_target_id]/properties/[property_id]"

More resources