• 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
    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:

    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

      RTSP stream (rtsp://) settings

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

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

      SHOUTcast/Icecast stream (https://) 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).

    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 
    }
    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).
      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.
      Default: null

    • 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.
      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.
      Default: 0

    • 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.
      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.
      Default: 0

    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,
    }
    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

    Originally Published: 01-31-2013.
    Updated: For Wowza Streaming Engine 4.5.0.01 on 08-18-2016.

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