Set advanced properties with the Wowza Streaming Cloud REST API

Modify default configurations used by the Wowza Streaming Cloud™ service and access additional functionality with advanced transcoder and stream target properties.  

You set a property through the REST API by specifying the property's key/value pair and the section of the transcoder or stream target configuration table the property is stored in. 

"property": {
     "key": "rtpTransportMode",
     "section": "rtsp",
     "value": "udp"

Some functionality available through the advanced properties include:

  • Transcoder — configuring VOD, recording, and file streaming settings; enabling AES 128 encryption; and more.
  • Stream target — Further configuration of an HLS stream and modifying the playlist.

Refer to the transcoder properties and stream target properties sections of this document for detailed information about the properties in each category.

Transcoder properties


When you set a transcoder property, you set a key/value pair and specify the section of the transcoder configuration table where the key and value are stored, as shown in the following example.

"property": {
     "key": "rtpTransportMode",
     "section": "rtsp",
     "value": "udp"

Transcoder properties exist in the following configuration table sections, which also categorize what the properties affect:

  • cupertino — Configures HLS streams.
  • ezdrm — Enables stream protection with a 3rd-party DRM provide, EZDRM. 
  • file — Perform actions on files used as video source.
  • output — Modifies output renditions of a transcoder.
  • recording — Enables recording of source streams.
  • rtmp — Configures RTMP streams.
  • rtsp — Configures RTSP streams. Particularly helpful for troubleshooting playback issues for transcoded streams from a camera connected to Wowza Streaming Cloud over RTSP/RTP.
  • vod_stream — Performs actions on VOD streams.

The following tables list the specific properties available in each transcoder configuration section.

cupertino

Use the cupertino properties to configure HLS streams. 

Section Key Value Description
cupertino aes128Host string The URL that devices will use to fetch the key to decrypt the stream.
cupertino aes128Secret string A 16-byte key that will be used to decrypt the stream. The key must be 32 characters in length and can only contain hex characters (a-z, A-Z, 0-9). The key must match the key returned by the aes128Host.

Learn more


ezdrm

Use the ezdrm properties to integrate with EZDRM, a third-party digital rights management (DRM) service you can use to protect content from unauthorized viewing. 

Section Key Value Description
ezdrm username string

Your EZDRM user name.

ezdrm password string

Your EZDRM password.

ezdrm fairPlayAssetId string

The FairPlay asset ID you generated from EZDRM.

ezdrm wideVineContentId string

The content ID you generated from EZDRM.

Learn more


file

Use the file properties to configure the stream when a file is the video source.

Section Key Value Description
file repeat boolean If True plays the file on a continuous loop. The default is False.
file start_streaming_at string The month, day, year, and time of day that the file should start streaming. Express the value by using the ISO 8601 standard of YYYY-MM-DDTHH:MM:SSZ where HH is a 24-hour clock in UTC.

Learn more


output

Use the output properties to perform actions on output renditions. 

Section Key Value Description
output fitMode string Specifies how to deal with aspect ratio differences between a source stream and transcoder output renditions. The setting affects all output renditions of a transcoder. Valid values are letterbox, fit-width, fit-height, crop, stretch, and match-source. The default is fit-height.
output record string Specifies which output rendition of a transcoder to record. Valid values are an output ID of a transcoder. You can only record one output of a transcoder. If this property isn't set, Wowza Streaming Cloud records the incoming source stream from an encoder instead of a transcoded output rendition. 

Learn more


recording

Use the recording properties to configure recordings on the transcoder. 

Section Key Value Description
recording mp4 boolean If true, creates a recording of the incoming source stream. The recording starts when the transcoder starts and stops automatically when the transcoder stops. The default is false.

Learn more


rtmp

Use the rtmp properties to configure RTMP streams. 

Section Key Value Description
rtmp allowDirectPlayback boolean If false, it prevents direct playback through the RTMP URL. The default is true.

Learn more


rtsp

Use the rtsp properties to configure RTSP streams. 

Important: Change advanced transcoder properties with caution. For most RTSP source connections, none of these settings need 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 rtpDePacketizerPacketSorterBufferTime integer Sets the size, in milliseconds, of the jitter buffer from the default value of 500. This time adds to the overall latency of the live stream. For use if rtpDepacketizerWrapper is set to RTPDePacketizerWrapperPacketSorter.
rtsp rtpDePacketizerPacketSorterFlushTime integer Sets the time, in milliseconds, from the default value of 10. This is the time when the buffer will be flushed. For use when rtpDepacketizerWrapper is set to RTPDePacketizerWrapperPacketSorter.
rtsp rtpDePacketizerWrapper string Enables the ability to set properties for the depacketizer. If set to RTPDePacketizerWrapperPacketSorter, this property enables the use of a jitter buffer. A jitter buffer is an area where packets can be collected and stored before being sent to the depacketizer at regularly spaced intervals to enable more even playback. This property should be enabled when setting values for rtpDepacketizerSorterBufferTime and rtpDepacketizerSorterFlushTime.
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.

vod_stream

Use the vod_stream properties to configure video-on-demand streams.

Section Key Value Description
vod_stream hls string If true, generates a VOD stream and a VOD playback URL after the broadcast is over. Use the URL to configure playback in an HLS compatible player or device.
vod_stream live2vod string If true, replaces the live playlist with the VOD playlist. Viewers can access the VOD stream using the same playback URL they used to view the original stream.
 
Note: vod_stream:hls also must be true.

Learn more


Example transcoder property requests


Notes:

Configure properties when creating a transcoder

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "transcoder": {
     "billing_mode": "pay_as_you_go",
     "broadcast_location": "us_west_california",
     "buffer_size": 4000,
     "delivery_method": "push",
     "low_latency": true,
     "name": "MyABRtranscoder",
     "protocol": "rtsp",
     "transcoder_type": "transcoded",
     "properties": [
      {
        "key": "avSyncMethod",
        "section": "rtsp",
        "value": false
      },
      {
        "key": "debugRtspSession",
        "section": "rtsp",
        "value": true
      }
    ]
   } 
}' "${WSC_HOST}/api/${WSC_VERSION}/transcoders"

This request creates a transcoder and updates the avSyncMethod and debugRtspSession properties. The details of the trancoder's configuration are listed in the response, which does not include transcoder properties. To view the transcoder's properties, send a GET \transcoders\[ID]\properties request. See Related requests for more information.

Configure a property for an existing transcoder

You can configure a single transcoder property or an array of properties. See the API reference linked below for examples of each. This example configures a single property.

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
   "property": {
     "key": "rtpTransportMode",
     "section": "rtsp",
     "value": "udp"
   } 
}' "${WSC_HOST}/api/${WSC_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. See PUT /transcoders/[ID]reset for more information.

Related requests

Stream target properties


When you set a stream target property, you set a key/value pair and specify the section of the stream target configuration table where the key and value are stored, as shown in the following example.

  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": 2
  }

Stream target properties exist in the following configuration table sections, which also categorize what the properties affect:

  • hls — Configures an HLS stream.
  • playlist — Modifies the playlist.

The following tables list the specific properties available in each stream target configuration section.

Note: All stream target properties are available for Wowza CDN on Akamai - HLS stream targets and custom stream targets whose provider is akamai_cupertino. Only a subset of stream target properties are available for Wowza CDN on Fastly stream targets. The target type that supports the property is also listed in the tables.

hls

Use the hls properties to configure an HLS output stream.

Section Key Value Target Type Description
hls acao string
  • Fastly
Explicitly specifies the origin that can access the stream. While most streams won't need the origin expliclity set, you might use this property for older players that don't send the Referer header in their stream request. Format: http://<origin>
hls chunkSize integer
  • Fastly
  • Akamai: akamai_cupertino
  • Custom: akamai_cupertino
Specifies the duration of the time-based audio and video media segments 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
  • Fastly
  • Akamai: akamai_cupertino
  • Custom: akamai_cupertino
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: For ultra low latency stream targets that have HLS fallback enabled, the convertAMFData property is enabled by default on backup HLS streams.
hls sendSSL Boolean
  • Akamai: akamai_cupertino
  • Custom: akamai_cupertino
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.

Learn more


playlist

Use the playlist properties to configure a stream's media playlist.

Section Key Value Target Type Description
playlist playlistSeconds integer
  • Fastly
  • Akamai: akamai_cupertino
  • Custom: akamai_cupertino
The number of seconds in the media playlist (chunklist). The default, 100, results in a media playlist of 10, based on the default chunkSize of 10. Valid values are any integer between 6 and 28800 (8 hours).

playlist playSSL Boolean
  • Akamai: akamai_cupertino
  • Custom: akamai_cupertino
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 redundantChunklists Boolean
  • Akamai: akamai_cupertino
  • Custom: akamai_cupertino
When true, creates and sends a redundant set of media playlists (chunklists) within the master playlist. If playback falters, a player that supports redundancy can switch to the redundant variant playlist. Check your player's documentation to see if it supports redundant media playlists. The default is false.

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

playlist relativePlaylists Boolean
  • Fastly
  • Akamai: akamai_cupertino
  • Custom: akamai_cupertino
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.

Learn more


Example stream target property requests


Notes:

Configure a property for a stream target

You can configure a single property or, if the stream target is a Wowza CDN on Fastly stream target or an Akamai target with a provider of akamai_cupertino, an array of properties. See the API reference linked below for examples of each. This example configures a single property.

Endpoint Reference

curl -X POST \
-H "Content-Type: application/json" \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
-d '{
  "property": {
    "key": "chunkSize",
    "section": "hls",
    "value": 2
  }
}' "${WSC_HOST}/api/${WSC_VERSION}/stream_targets/[stream_target_id]/properties"

The command assigns a media segment 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. See PUT /live_streams/[ID]/reset and PUT /transcoders/[ID]reset for more information. 

Related requests

More resources