How to specify per-stream settings in .stream files

Stream (.stream) files enable you to replace complex stream names that are published to a Wowza™ media server from sources such as MPEG-TS encoders and IP cameras (RTSP/RTP streams), SHOUTcast/Icecast streams, and native RTP encoders. For example, if your complex stream name on the server is udp://0.0.0.0:10000, you can create a stream file named mycoolevent.stream and assign the contents to the complex stream name. Players can then use mycoolevent.stream in playback URLs in place of the more complex stream name.

The properties that you specify for live video streaming applications that host a .stream file apply to all streams delivered by the application. This article describes how to specify per-stream settings in .stream files to override those in the application configuration for the stream. These settings apply only to the types of streams identified by the application configuration.

Note: This article is for use with Wowza Streaming Engine™ media server software.

Contents


Overview
Per-stream settings reference
Common settings
MPEG-TS stream (udp://) settings
MPEG-TS (TCP/IP) stream (http://) settings
RTSP stream (rtsp://) settings
Live Stream Repeater stream (rtmp://, rtmps://, wowz://, or wowzs://) settings
SHOUTcast/Icecast stream (https://) settings
Apple HLS M3U8 manifest stream (http://) settings
PTZ settings

Overview


Follow the instructions in How to create and use .stream files in Wowza Streaming Engine Manager to create a stream file that you can use to re-stream from MPEG-TS encoders and IP cameras (RTSP/RTP streams), SHOUTcast/Icecast streams, and native RTP encoders. After you create the stream file, do the following to configure per-stream settings for the stream in Wowza Streaming Engine Manager:
  SRT stream (srt://) settings
  1. Click the name of the stream file you want to configure in the Stream Files list.


     
  2. Click the Properties tab. (Note that access to the Properties tab is limited to administrators with advanced permissions. For more information about how to configure access, see Manage credentials.) On the Properties tab, there are two sets of properties: Common properties (can be configured for any stream type) and stream URI-specific properties, which are unique for the source stream URI that's specified in the stream file. The following figure shows the properties that are available for a stream file that references a SHOUTcast-Icecast stream (https:// URI type):


     
  3. To enable a property, click Edit and then select the Enabled check box for the property. The property will be enabled with a default value that you can change in the Value box. After you're done, click Save.


     
  4. Refer to the following sections in this article for details about the common and URI-specific properties that you can configure:

    Common settings
    MPEG-TS stream (udp://) settings
    MPEG-TS (TCP/IP) stream (http://) settings
    RTSP stream (rtsp://) settings
    Live Stream Repeater stream (rtmp://, rtmps://, wowz://, or wowzs://) settings
    SHOUTcast/Icecast stream (https://) settings
    Apple HLS M3U8 manifest stream (http://) settings

Per-stream settings reference


The settings described in this section are optional and can be omitted to allow for broader definitions set in other configuration files to remain in effect. All settings are case-sensitive.

When you configure per-stream settings in Wowza Streaming Engine Manager, they are entered into the stream (.stream) file using Java Script Object Notation (JSON) to enable configuration of stream-specific settings.

If you're running Wowza Media Server™ software (version 3.5.1 or later), you must open the .stream files in a text editor and add the per-stream settings in JSON notation. The following examples show the syntax for JSON settings.
 
  • Strings use quoted values:
    stringSetting: "aValue"
  • Integers are unquoted values that can be represented as decimal or hexadecimal. Hexadecimal settings must start with 0x or x (enclosed in quotation marks):
    decimalSetting: 3
    hexSetting1: "0x3"
    hexSetting2: "x3"
  • Boolean values are the unquoted strings true or false:
    booleanSetting: true
    booleanSetting: false
 
Note: If you're running Wowza Media Server software version 3.5.0 or earlier, per-stream settings are done by adding query parameters to URLs in .stream files.

Common settings


The following common parameters can be set in .stream files for all stream types.





JSON notation
{
    uri:"udp://192.168.1.100:10000",
    streamTimeout:5000,
    reconnectWaitTime:3000
}
Setting descriptions
 
  • uri: String
    Specified in .stream files without JSON.
  • streamTimeout: Integer
    If non-zero, Wowza Streaming Engine monitors the stream. If a break occurs in the stream that's longer than the streamTimeout value, in milliseconds, it resets the connection to the camera.
  • reconnectWaitTime: Integer
    The minimum time between reconnection attempts, in milliseconds.

MPEG-TS stream (udp://) settings


The following settings are supported for MPEG Transport Streams (MPEG-TS).





JSON notation
{
    uri:"udp://192.168.1.100:10000",
    streamTimeout:5000,
    reconnectWaitTime:3000,
    mpegtsAudioPID:15,
    mpegtsVideoPID:16,
    mpegtsProgramID:2,
    mpegtsAudioLanguage:"spa",
    mpegtsAudioBitrate:50000,
    mpegtsVideoBitrate:750000,
    mpegtsAudioIsAligned:true,
    mpegtsVideoIsAligned:false,
    mpegtsAdjustBFrameTimecodes:false,
    mpegtsDropIncompleteVideoFrames:true,
    mpegtsLogIncompleteVideoFrames:true,
    mpegtsMapTimeToSystemTime:false,
    mpegtsMapTimeToSystemTimeWindow:2000,
    mpegtsImportAC3:false
}
Setting descriptions
 
  • mpegtsAudioPID: Integer
    Packet ID (PID) of the audio elementary stream that you want to use.
    Default: The first audio stream found in the Program Map Table (PMT) for the program is used.
  • mpegtsVideoPID: Integer
    PID of the video elementary stream that you want to use.
    Default: The first video stream found in the PMT for the program is used.
  • mpegtsProgramID: Integer
    Program ID of the service that you want to use.
    Default: The first program in the list of programs in the PMT is used.
  • mpegtsAudioLanguage: Three letter string.
    String that represents the ISO 639-2 language code used to select the desired audio elementary stream.
    Default: The first audio stream in the PMT for the program is used.
  • mpegtsAudioBitrate: Integer
    Used to specify the audio bitrate, in bits per second, for use with Wowza Transcoder.
    Default: -1
  • mpegtsVideoBitrate: Integer
    Used to specify the video bitrate, in bits per second, for use with Wowza Transcoder.
    Default: -1
  • mpegtsAudioIsAligned: Boolean
    Some MPEG-TS based encoders and cameras send unaligned audio packets. This setting enables Wowza Streaming Engine to manage them correctly. For more details, see the references to the audioIsAligned property in Properties to fix audio and video alignment.
    Default: true
  • mpegtsVideoIsAligned: Boolean
    Some MPEG-TS based encoders and cameras send unaligned video packets. This setting enables Wowza Streaming Engine to manage them correctly. For more details, see the references to the videoIsAligned property in Properties to fix audio and video alignment.
    Default: true
  • mpegtsAdjustBFrameTimecodes: Boolean
    Enables the feature to manufacture decode/presentation time stamps (DTS/PTS) for B-frames when an encoder can't generate them or generates them incorrectly.
    Default: false
  • mpegtsDropIncompleteVideoFrames: Boolean
    Enables frames to be dropped when packet loss occurs.
    Default: false
  • mpegtsLogIncompleteVideoFrames: Boolean
    Enables information about dropped frames to be logged when packet loss occurs (see mpegtsDropIncompleteVideoFrames:).
    Default: false
  • mpegtsMapTimeToSystemTime: Boolean
    Enables mapping of DTS/PTS values to the system clock. This is generally used in a parallel origin configuration and ensures that a smoother transition occurs during failover because all of the origin servers generate similar PTS/DTS values based on matched system clocks.
    Default: false
  • mpegtsMapTimeToSystemTimeWindow: Integer
    Controls the rollover window duration, in milliseconds, around system/PTS/DTS clocks. This is generally used in a parallel origin configuration and ensures that clock rollover is handled identically on all origin servers.
    Default: 2000
  • mpegtsImportAC3: Boolean
    Enables AC-3 elementary streams to be imported. It allows Dolby Digital (AC-3) and Dolby Digital Plus (Enhanced AC-3) audio from MPEG-TS encoders to pass through unaltered for delivery using Apple HTTP Live Streaming (Apple HLS/Cupertino) and MPEG-DASH streaming. This allows your customers to experience immersive surround-sound audio when streaming on media devices such as Apple TV, Sony PlayStation 3 (PS3), hybrid set-top boxes, and smart TVs.
    Default: false
Note: For basic configuration information, see How to publish and play a live stream (MPEG-TS based encoder).

MPEG-TS (TCP/IP) stream (http://) settings


In Wowza Streaming Engine 4.5.0.02 and later, the following setting is supported for MPEG Transport Streams (MPEG-TS) over TCP.





JSON notation
{
    uri:"http://192.168.1.100:10000",
    streamTimeout:5000,
    reconnectWaitTime:3000,
    mpegtstcpSourceHostName:true
}
Setting descriptions
 
  • mpegtstcpSourceHostName: Boolean
    When set to true, Wowza Streaming Engine sets the Host: header in the initial request to that of the hostname used in the connection URI. This is required to connect to some MPEG-TS over TCP/IP streams correctly.
    Default: false 
Notes:

RTSP stream (rtsp://) settings


The following settings are supported for Real Time Streaming Protocol (RTSP) streams.





JSON notation
{
    uri:"rtsp://192.168.1.100:10000",
    streamTimeout:5000,
    reconnectWaitTime:3000,
    rtpTransportMode:"udp",
    rtspValidationFrequency:15000,
    rtspFilterUnknownTracks:true,
    rtspStreamAudioTrack:false,
    rtspStreamVideoTrack:true,
    rtpDebugSession:true,    
    rtpIgnoreProfileLevelId:true,
    rtpIgnoreSPropParameterSets:true,
    rtspBindIpAddress:"192.168.1.1",
    rtspRemoveUserInfo:true,
    rtspSessionTimeout:8000,
    rtspConnectionTimeout:8000,
    rtspUserHeaders:null,
    rtspMulticastServerPortAudio:0,
    rtspMulticastServerPortVideo:0,
    rtspMulticastServerDestinationInSetup:true
}
Setting descriptions
 
  • rtpTransportMode: String "udp", "interleave" or "tcp", "tunnel" or "https"
    This setting controls how the RTSP protocol is used when pulling an RTSP/RTP stream from an IP camera. For more details, see the references to the rtpTransportMode property in How to re-stream video from an IP camera (RTSP-RTP re-streaming).
    Default: "udp"
  • rtspValidationFrequency: Integer
    Specifies, in milliseconds, how often Wowza Streaming Engine validates an RTSP/RTP connection. For more details, see Additional property configuration needed for some cameras.
    Default: 15000
  • rtspFilterUnknownTracks: Boolean
    Filters out tracks sent from IP cameras that Wowza Streaming Engine doesn't understand. For more details, see Additional property configuration needed for some cameras.
    Default: false
  • rtspStreamAudioTrack: Boolean
    Enables audio tracks from IP cameras to be turned on (true) or off (false). For more details, see the section "How to turn on/off audio and video tracks" in How to re-stream video from an IP camera RTSP-RTP re-streaming.
    Default: true
  • rtspStreamVideoTrack: Boolean
    Enables video tracks from IP cameras to be turned on (true) or off (false). For more details, see the section "How to turn on/off audio and video tracks" in How to re-stream video from an IP camera RTSP-RTP re-streaming.
    Default: true.
  • rtpDebugSession: Boolean
    Enables extra debug information to be added to log files for RTP sessions. Due to the large volume of data that's logged, this setting shouldn't be enabled in production environments unless there is a problem that must be investigated. For more details, see the section "How to add additional logging for RTSP debugging in How to re-stream video from an IP camera (RTSP-RTP re-streaming)[/URL].
    Default: false
  • rtpIgnoreProfileLevelId: Boolean
    Disables profile-level-id parsing (profile level ID extracted from SPS/PPS NAL units). For more details, see the section "Problematic SDP files" in How to re-stream video from an IP camera (RTSP-RTP re-streaming).
    Default: false
  • rtpIgnoreSPropParameterSets: Boolean
    If true, Wowza Streaming Engine ignores the sprop-parameter-sets data in an Session Description Protocol (SDP) file and relies on the data reported in the SPS and PPS packets of the stream (if they exist). This setting is generally used when a camera/encoder sends or encodes the parameter sets incorrectly.
    Default: false
  • rtspBindIpAddress: String
    Specifies the IP address that Wowza Streaming Engine binds to when streaming RTP packets over UDP. For details, see How to set up an application for RTSP/RTP streaming.
    Default: Binds to the default interface(s)
  • rtspRemoveUserInfo: Boolean
    If true, the username and password information are removed from RTSP/RTP URLs before streams are requested from an IP camera.
    Default: true
  • rtspSessionTimeout: Integer
    Specifies, in milliseconds, how often Wowza Streaming Engine validates the connection to the camera by sending GET_PARAMETER messages. For more details, see RTP Session Properties Description.
    Default: 8000
  • rtspConnectionTimeout: Integer
    Specifies, in milliseconds, the TCP connection timeout for making the initial TCP connection to an IP camera. For more details, see RTP Session Properties Description.
    Default: 8000
  • rtspUserHeaders: String
    Enables custom RTSP headers for MediaCaster RTSP connections. This setting can contain multiple values separated by the pipe ("|") character (for example, key1:value1|key2:value2).
    Default: null
    Note: This setting is introduced in Wowza Streaming Engine 4.0.6 and must be added to the JSON notation for your .stream file by using a text editor. The ability to add this setting by using the Streaming Engine Manager user interface will be included in a later release of the server software.
  • rtspMulticastServerPortAudio: Integer
    Some RTSP sources (IP cameras and encoders) support dynamic client side port allocation for multicast streaming and require you to set a port number. This value specifies the audio UDP port the RTSP source should use when the source doesn't specify the port.
    Default: 0
    Note: This setting is introduced in Wowza Streaming Engine 4.5.0 and must be added to the JSON notation for your .stream file by using a text editor. The ability to add this setting by using the Streaming Engine Manager user interface will be included in a later release of the server software.
  • rtspMulticastServerPortVideo: Integer
    Some RTSP sources (IP cameras and encoders) support dynamic client side port allocation for multicast streaming and require you to set a port number. This value specifies the video UDP port the RTSP source should use when the source doesn't specify the port.
    Default: 0
    Note: This setting is introduced in Wowza Streaming Engine 4.5.0 and must be added to the JSON notation for your .stream file by using a text editor.
  • rtspMulticastServerDestinationInSetup: Boolean
    Some multicast-enabled IP cameras don't work if the SETUP command includes the destination=[multicast-ip-address] parameter. This value can be set to false to suppress this parameter from RTSP SETUP commands for multicast connections.
    Default: true
    Note: This setting is introduced in Wowza Streaming Engine 4.6.0.01 and must be added to the JSON notation for your .stream file by using a text editor.
 
Note: For basic configuration information, see How to set up live streaming using an RTSP/RTP based encoder.

Live Stream Repeater stream (rtmp://, rtmps://, wowz://, or wowzs://) settings


The following settings are supported for Live Stream Repeater streams.





JSON notation
{
    lsrSecureTokenOriginSharedSecret:"monkeySeeMonkeyDo",
    lsrCallFCSubscribe: true,
    lsrRemoveDefaultAppInstance: true,
    lsrResetOnStreamNotFound: false
}
Setting descriptions
 
  • lsrSecureTokenOriginSharedSecret: String
    Specifies the security token to be exchanged between either edge/origin servers or server/client players in a secured environment. If null, it's not used. For more details, see How to protect RTMP streaming using SecureToken (ModuleSecureToken).
    Default: null
  • lsrCallFCSubscribe: Boolean
    If true, Wowza Streaming Engine will "subscribe" to the stream. This setting is needed for RTMP live streams from Content Delivery Networks (CDNs) that require the Real Time Messaging Protocol (RTMP) FCSubscribe command. For more details, see How to re-stream an unprotected stream from Adobe Media Server or a CDN.
    Default: false
  • lsrRemoveDefaultAppInstance: Boolean
    If true, Wowza Streaming Engine won't send the default application instance name to the origin server when making a live repeater connection.
    Default: false
  • lsrResetOnStreamNotFound: Boolean
    If true, an edge server that receives a NetStream.Play.StreamNotFound error from an origin server will reset the stream.
    Default: false 
Note: For basic configuration information, see How to configure a live stream repeater.

SHOUTcast/Icecast stream (https://) settings


The following settings are supported for SHOUTcast/Icecast streams.





JSON notation
{
    uri:"https://192.168.1.100:80",
    streamTimeout:5000,
    reconnectWaitTime:3000,
    shoutcastCharacterEncoding:"8859_1",
    shoutcastMP3GroupCount: 4,
    shoutcastSetTimecodesBasedOnSystemClock: true,
    shoutcastSourceHostName: false
}
Setting descriptions
 
  • shoutcastCharacterEncoding: String
    The metadata character encoding.
    Default: "8859_1"
  • shoutcastMP3GroupCount: Integer
    Specifies the number of frames-per-packet.
    Default: 4
  • shoutcastSetTimecodesBasedOnSystemClock: Boolean
    When set to true, Wowza Streaming Engine sets the SHOUTcast timebase to be based on the system clock.
    Default: false
  • shoutcastSourceHostName: Boolean
    When set to true, Wowza Streaming Engine sets the Host: header in the initial request to that of the hostname used in the connection URI. This is required to connect to some SHOUTcast server farms correctly.
    Default: false 
Note: For basic configuration information, see How to re-stream audio from SHOUTcast/Icecast.

Apple HLS M3U8 manifest stream (http://) settings


In Wowza Streaming Engine 4.5.0.01 and later, the following settings are supported for Apple HLS streams.





JSON notation
{
    uri:"http://192.168.1.100:1935/live/myStream/playlist.m3u8",
    streamTimeout:5000,
    reconnectWaitTime:3000,
    cupertinoManifestLimit:-1,
    cupertinoManifestIndex: "",
    cupertinoRestGroupOnSingleFailure: true,
    cupertinoAutoSegmentBuffer: false,
    cupertinoManifestBufferBlockCount: 5,
    cupertinoManifestMaxBufferBlockCount: 15,
    cupertinoAutoSegmentBufferTime: 30000,
    cupertinoChunkMaxDurationAllowed: 30000,
    cupertinoPacketDeliveryTime: 200
}
Setting descriptions
 
  • cupertinoManifestLimit: Integer
    Specifies the maximum number of streams to pull in from an adaptive bitrate manifest. The default value (-1) pulls in all streams found.
    Default: -1
  • cupertinoManifestIndex: String
    Specifies, as a comma-separated list with numbering starting at 0, an index to pull in from an adaptive bitrate manifest. If no value is specified, all indexes are pulled in.
    Default: <no value set>
  • cupertinoRestGroupOnSingleFailure: Boolean
    If true, all streams found in a manifest are reset if an error is detected on any of them.
    Default: true
  • cupertinoAutoSegmentBuffer: Boolean
    If true, the cupertinoManifestBufferBlockCount is calculated based on the cupertinoAutoSegmentBufferTime.
    Default: true
  • cupertinoManifestBufferBlockCount: Integer
    Specifies the number of blocks pulled in prior to publishing the stream. By default, this is calculated based on the duration of the first block in the manifest and the cupertinoAutoSegmentBufferTime. To use the cupertinoAutoSegmentBuffer property, the cupertinoAutoSegmentBuffer property must be set to false.
    Default: 2
  • cupertinoManifestMaxBufferBlockCount: Integer
    Specifies the maximum number of blocks allowed in the buffer. By default, the value is three times the cupertinoManifestBufferBlockCount. This is used to ensure that the input is being processed effectively. To use the cupertinoManifestMaxBufferBlockCount property, the cupertinoAutoSegmentBuffer property must be set to false.
    Default: 15
  • cupertinoAutoSegmentBufferTime: Integer
    Specifies, in milliseconds, the buffer time required when pulling in Apple HLS (cupertino) blocks.
    Default: 30000
  • cupertinoChunkMaxDurationAllowed: Integer
    Specifies, in milliseconds, the maximum block duration. Any block exceeding the maximum duration is dropped.
    Default: 30000
  • cupertinoPacketDeliveryTime: Long
    Specifies the time interval, in milliseconds, when processing MPEG-TS packets from the Apple HLS (cupertino) block buffer. Some variable bitrate streams may require this value to be increased, but the value should not exceed 2000.
    Default: 200
Note: For basic configuration information, see How to publish and play a live stream (Apple HLS).

PTZ settings


The following common parameters can be set in .stream files for all stream types to cameras with Pan/Tilt/Zoom controls.
 
Note: Wowza Streaming Engine 4.2.0 and later can control Pan/Tilt/Zoom (PTZ) functionality in integrated Sony and Axis IP cameras using the Pan/Tilt/Zoom Controller in Wowza Streaming Engine Manager.




JSON notation
{
    uri:"udp://192.168.1.100:10000",
    sourceControlConnectionTimeout:1000,
    sourceControlReadWriteTimeout:3000,
    sourceControlSessionTimeout:10000,
    sourceControlImageRefreshRate:2000,
    sourceControlImageMinimumRate:1000,
}
Setting descriptions
 
  • sourceControlConnectionTimeout: Integer
    Specifies, in milliseconds, how long to wait for a connection with the camera to be established.
    Default: 1000
  • sourceControlReadWriteTimeout: Integer
    Specifies, in milliseconds, how long to wait for a response from the camera.
    Default: 3000
  • sourceControlSessionTimeout: Integer
    Specifies, in milliseconds, how long to keep a session with an inactive camera open. A camera is considered inactive if it's not sending a stream and not being viewed by clients. (The Pan/Tilt/Zoom Controller dialog box is a client.)
    Default: 10000
  • sourceControlImageRefreshRate: Integer
    Specifies, in milliseconds, how often to refresh the video preview window in the Pan/Tilt/Zoom Controller dialog box.
    Default: 2000
  • sourceControlImageMinimumRate: Integer
    Specifies, in milliseconds, a lower limit to the sourceControlImageRefreshRate property value. Use this property to prevent refreshes of the video preview window in the Pan/Tilt/Zoom Controller dialog box from occurring too frequently, which can affect web browser performance.
    Default: 1000
    Note: This property is supported in Wowza Streaming Engine 4.6.0.04 and later.

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