A Wowza Streaming Engine™ (WSE) application is a contextual media streaming environment. Each app specifies a set of operating properties and provides a namespace and context for streaming. Users may create as many applications as needed, for example a live streaming app, a video on demand (VOD) app, or apps for transcoding, nDVR, and re-streaming.
When a new app is created, a configuration file is created to store its settings. The app's configuration file is called Application.xml and is located in the [install-dir]/conf/[app-name] directory. We recommend using WSE Manager to change an app's settings, but you may also update an app's Application.xml file directly.
The Application.xml file located in [install-dir]/conf is the server's application configuration template. It is used as the template for new apps' configuration settings.
An application instance is started dynamically; a single application can have multiple named application instances running simultaneously. If no name is specified for an application instance, then the default name _definst_ is used. In many scenarios, a single application instance is used per-application and the name is never referenced and defaults to _definst_.
Note: The properties described below apply to the latest WSE version. Some properties may not apply to earlier versions.
Contents
Application element
The <Application> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<Name> |
String | The name of the application. Required. |
<AppType> |
String | The type of the application, such as live, vod, livehttporigin, vodhttporigin, liveedge, vodedge. Required. |
<Description> |
String | A text description of the application. Optional. |
<ApplicationTimeout> |
Integer | Milliseconds the server waits before shutting down an app with no client connections. Set to 0 to run until the virtual host shuts down. If unset, the VHost.xml value applies. |
<PingTimeout> |
Integer | Milliseconds the server waits for a ping response from the client. This is an RTMP internal ping, not ICMP. Set to 0 to wait indefinitely. If unset, the VHost.xml value applies. |
<ValidationFrequency> |
Integer | Milliseconds the server waits during server-to-client validation, which sends a ping request to the client. Validation runs only if the client stops sending data. Set to 0 to disable validation. If unset, the VHost.xml value applies. |
<MaximumPendingWriteBytes> |
Integer | Maximum bytes allowed to queue while waiting to be sent. A client connection that exceeds this is terminated. Set to 0 for no maximum. If unset, the VHost.xml value applies. |
<MaximumSetBufferTime> |
Integer | Maximum milliseconds honored for client-side NetStream.setBufferTime(seconds) calls. The check guards against spoofing tools that request a very large client-side buffer to make the server send all media data at once, consuming Java heap memory. Set to 0 to turn off the check. (Default: 60000) |
<MaximumStorageDirDepth> |
Integer | Maximum number of subfolders allowed in any storage path. Helps protect against symbolic link loops. |
<Connections> |
Container | Connection restrictions. See the Connections elements table for available child elements. |
<Streams> |
Container | Stream configuration for the application. See the Streams elements table for available child elements. |
<Transcoder> |
Container | Transcoder configuration. See the Transcoder elements table for available child elements. |
<DVR> |
Container | DVR recording configuration. See the DVR elements table for available child elements. |
<TimedText> |
Container | Timed text captioning configuration. See the TimedText elements table for available child elements. |
<HTTPStreamers> |
String | Comma-separated list of HTTP streaming protocols to enable. Can contain none, one, or more of the following values:
|
<MediaCache> |
Container | Media Cache source access for VOD edge applications. |
<MediaCache>/<MediaCacheSourceList> |
String | Comma-separated list of Media Cache sources this VOD edge application can access. Use the wildcard (*) to allow every source configured on the system. Media Cache sources are HTTP-based servers and network-attached file systems that supply file-based content for re-streaming. For example, a VOD application on an Amazon EC2 instance could include amazons3 or dvrorigin. |
<SharedObjects> |
Container | How an application accesses remotely stored object data. |
<SharedObjects>/<StorageDir> |
String | Full path to the directory where the application reads and writes remotely stored object data. If unset, the application uses:
where |
<Client> |
Container | Client connections to streams. See the Client elements table for available child elements. |
<RTP> |
Container | RTSP/RTP streaming configuration. See the RTP elements table for available child elements. |
<WebRTC> |
Container | WebRTC publish and playback. Setup requires RTP tuning properties in addition to WebRTC settings. See the WebRTC elements table for available child elements. |
<SRTListener> |
Container | Used with SRT listener mode to configure a global or per-user passphrase for publishing and encrypting SRT streams. The passphrase must match on the source and destination devices. See the SRTListener elements table for available child elements. |
<MediaCaster> |
Container | Restreaming with the MediaCaster system. See the MediaCaster elements table for available child elements. |
<MediaReader> |
Container | A container element for custom MediaReader <Property> elements. MediaReader reads files for recording and VOD playback. |
<MediaWriter> |
Container | A container element for custom MediaWriter <Property> elements. MediaWriter writes files for recording and VOD playback. |
<LiveStreamPacketizer> |
Container | A container element for custom live stream packetizer <Property> elements. |
<HTTPStreamer> |
Container | A container element for custom HTTP streamer <Property> elements. |
<Manager> |
Container | A container element for custom WSE Manager <Property> elements. |
<Repeater> |
Container | Origin URL and query string for using the application as a live stream repeater. |
<Repeater>/<OriginURL> |
String | Origin URL used by the live stream repeater. For a DVR repeater, this is the URL of the DVR origin server to retrieve audio and video chunks from. |
<Repeater>/<QueryString> |
String | Query string used to connect to the origin. Can pass secure URL parameters for security validation. |
<StreamRecorder> |
Container | A container element for custom stream recorder <Property> elements. |
<Modules> |
Container | Modules available to this application. See the Module elements for available child elements. |
<Properties> |
Container | A container element for custom application <Property> elements. |
Connections element
The <Connections> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<AutoAccept> |
Boolean | Whether the application automatically accepts Adobe Flash client playback connection requests. If true, all requests are accepted automatically. If false, the application must call client.acceptConnection() server-side to accept a request. |
<AllowDomains> |
String |
Comma-delimited list of domain names or IP addresses whose RTMP client connections are accepted. Each entry is the domain or IP address of an Adobe Flash SWF file that connects to WSE, or the IP address of a connecting client. If unset, connections from all domains and IP addresses are accepted. For example, setting Allow-domains processing runs just before the |
Streams element
The <Streams> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<StreamType> |
String | Default stream type for this application. Stream types control live, VOD, recording, and origin/edge streaming. Example values:
|
<StorageDir> |
String | Full path to the directory where the application reads and writes media files. |
<KeyDir> |
String | Directory where HLS (Cupertino) AES-128 encryption keys are stored. |
<LiveStreamPacketizers> |
String | Comma-separated list of HTTP streaming packetization schemes for live source streams. Packetization makes a stream available for HTTP streaming and enables DVR. Can contain none, one, or more of the following values:
|
<Properties> |
Container | A container element for custom stream <Property> elements. |
Transcoder element
The <Transcoder> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<LiveStreamTranscoder> |
String | Default transcoder handler for this application. Set to transcoder to enable the transcoder. If unset, live source streams aren't transcoded. |
<Templates> |
String |
Comma-separated list of template names to search when matching a live source stream to a Transcoder template. WSE uses the first template file in the list that exists; if none exist, the stream isn't transcoded. Defaults to The default first entry uses |
<ProfileDir> |
String | Path to the Transcoder profiles, such as {com.wowza.wms.context.VHostConfigHome}/transcoder/profiles. |
<TemplateDir> |
String | Full path to the directory where the application looks for Transcoder templates. By default WSE looks in [install-dir]/transcoder/templates. To define a per-application folder, use directory path variables, for example ${com.wowza.wms.context.VHostConfigHome}/conf/${com.wowza.wms.context.Application}/profiles.
|
<Properties> |
Container | A container element for custom transcoder <Property> elements. |
DVR element
The <DVR> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<Recorders> |
String | Name of the default DVR recorder for this application. |
<Store> |
String | Set to dvrfilestorage on a single server or an origin. Leave empty on edge servers. |
<WindowDuration> |
Integer | Seconds of material available for DVR playback. Defaults to 0, which means there's no DVR window, so all data is available. |
<StorageDir> |
String | Full path to the directory where the application reads and writes Wowza nDVR data. Accepts directory path variables. |
<ArchiveStrategy> |
String | What the DVR store does with an old stream when a new stream with the same app instance and stream name starts. Defaults to append. Accepts one of the following values:
|
<Properties> |
Container | A container element for custom DVR recording <Property> elements. |
TimedText element
The <TimedText> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<VODTimedTextProviders> |
String | Comma-separated list of video-on-demand (VOD) caption providers. |
<Properties> |
Container | A container element for custom Timed text <Property> elements. |
Client element
The <Client> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<IdleFrequency> |
Integer | Milliseconds between idle events, which are the heartbeat of RTSP/RTP streaming and control how often new data is sent to the player. Set to -1 to use the VHost.xml value. |
<Access> |
Container | Default access an Adobe Flash client connection has to assets associated with a WSE application. See the Access elements table for available child elements. |
Access element
The <Access> element contains the children listed in the table below. An individual client's access can be modified through the WSE Java API. This is most commonly done in the onConnect or onConnectAccept event handler.
To control access, each of these settings compares the asset name (stream name or shared object name) to a comma-delimited list of names. If any part of the asset name matches one of the elements in the list, then the requested access is granted. The values are case-sensitive. If no parameter value is specified, then access is denied to all clients. If the parameter value is set to the wildcard (*) character, then access is granted to all clients.
| Element | Type | Description |
|---|---|---|
<StreamReadAccess> |
String | Controls access to view or listen to a NetStream object. |
<StreamWriteAccess> |
String | Controls access to write or publish to a NetStream object. |
<StreamAudioSampleAccess> |
String | Controls access to call SoundMixer.computeSpectrum() to grab a NetStream object's waveform data. |
<StreamVideoSampleAccess> |
String | Controls access to call BitmapData.draw() to snapshot a NetStream object. |
<SharedObjectReadAccess> |
String | Controls access to read values from a RemoteSharedObject. |
<SharedObjectWriteAccess> |
String | Controls access to write values to a RemoteSharedObject. |
For example, if StreamReadAccess is set to testa/testb;testc, then the following stream names would be granted the following access:
| Stream Name | Access Status |
|---|---|
| testc | Granted Access |
| testc/test | Granted Access |
| testC/test | Denied Access (incorrect case) |
| testa/testb | Granted Access |
| testa/testb123 | Granted Access |
| testa/testb/file123 | Granted Access |
| testa/test | Denied Access (incomplete match) |
RTP element
The <RTP> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<Authentication> |
Container | Authentication for RTSP connections. |
<Authentication>/<PublishMethod> |
String | Authentication method used to secure source RTSP connections: none, basic, digest, or block. |
<Authentication>/<PlayMethod> |
String | Authentication method used to secure playback RTSP connections: none, basic, or digest. |
<AVSyncMethod> |
String | Method used to synchronize the audio and video channels when receiving an RTP stream. Defaults to senderreport. Example values:
|
<MaxRTCPWaitTime> |
Integer | Maximum milliseconds WSE waits to receive an SR packet over the RTCP channel. If none arrive in that time, the server falls back to the rtptimecode method. |
<IdleFrequency> |
Integer | Milliseconds between RTP idle events, which send new media data and events to RTP or MPEG-TS sessions. |
<RTSPSessionTimeout> |
Integer | Milliseconds after which an idle RTSP session is considered stale and disconnected. WSE monitors RTSP sessions for periodic RTSP messages or RTCP receiver packets over RTP, and disconnects a session that sends none within this period. Set to 0 to turn off idle disconnect. |
<RTSPMaximumPendingWriteBytes> |
Integer | Maximum bytes that can wait to be written to an RTSP session. WSE tracks pending bytes on the RTSP/TCP connection and disconnects a session that exceeds this value. Set to 0 to turn off monitoring. |
<RTSPBindIpAddress> |
String | IP address WSE binds to when delivering RTP packets over UDP. With network address translation (NAT) routing, set this to the internal IP address of the network interface mapped to the external IP address. Without NAT, set it to the server's external IP address. |
<RTSPConnectionIpAddress> |
String | IP address exchanged in the Session Description Protocol (SDP) data on the (c=) line. Set this to the server's external IP address. |
<RTSPSsrcCheck> |
Boolean | Enables the Synchronization Source identifier (SSRC), which distinguishes one stream from another within the same RTP session. Set to false to disable SSRC checks when streaming over RTSP. New applications don't include this element, but it's present and set to true in the pre-configured live application. |
<RTSPOriginIpAddress> |
String | IP address exchanged in the Session Description Protocol (SDP) data on the (o-) line. Set this to the server's external IP address. |
<IncomingDatagramPortRanges> |
String |
UDP port ranges this application can use for stream ingestion. Accepts single ports and ranges. This example enables port <IncomingDatagramPortRanges>10000, 20000-20004</IncomingDatagramPortRanges> Applies only to ingestion that pulls streams with Session Description Protocol (SDP) files or MPEG-TS udp:// URLs. These values don't affect UDP ports assigned dynamically during RTSP port negotiation. |
<Properties> |
Container | A container element for custom RTP <Property> elements. |
WebRTC element
The <WebRTC> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<EnablePublish> |
Boolean | Enable WebRTC publishing to this application. |
<EnablePlay> |
Boolean | Enable WebRTC playback from this application. |
<EnableQuery> |
Boolean | Enable querying of published stream names for this application. |
<IceCandidateIpAddresses> |
String | IP address, transport, and port used for WebRTC streaming. UDP format: [wowza-streaming-engine-external-ip-address],udp. TCP format: [wowza-streaming-engine-external-ip-address],tcp,[port]. For multiple IP addresses, use a pipe character to separate the lists. |
<UDPBindAddress> |
String | Local IP address of the network card you want to use for WebRTC UDP traffic. |
<PreferredCodecsAudio> |
String | Comma-separated list of audio codecs, in order of preference, for stream ingestion. |
<PreferredCodecsVideo> |
String | Comma-separated list of video codecs, in order of preference, for stream ingestion. |
<DebugLog> |
Boolean | Enable WebRTC debug logging. |
<Properties> |
Container | A container element for custom WebRTC <Property> elements. See the WebRTC properties table for a full list of available configuration options. |
SRTListener element
The <SRTListener> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<Authentication> |
Container | Authentication for SRT connections. |
<Authentication>/<PublishMethod> |
String | Authentication method used to secure source SRT connections:
To bypass encryption, use |
MediaCaster element
The <MediaCaster> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<RTP> |
Container | Restreaming with the rtp MediaCaster type. |
<RTP>/<RTSP> |
Container | Restreaming with RTSP/RTP streams. |
<RTP>/<RTSP>/<RTPTransportMode> |
String | RTSP flavor used to re-stream an RTSP/RTP source such as an IP camera. Set to interleave for RTSP/RTP interleaved (RTP over TCP), or udp for non-interleaved mode (RTP over UDP). |
<StreamValidator> |
Container | Monitoring of native RTP and MPEG-TS encoder streams, resetting them if they become unhealthy. See the StreamValidator elements table for available child elements. |
<Properties> |
Container | A container element for custom MediaCaster <Property> elements. |
StreamValidator element
The <StreamValidator> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<Enable> |
Boolean | Set to true to activate the StreamValidator. |
<ResetNameGroups> |
Boolean | If true, resetting a stream that belongs to a MediaStreamNameGroup resets every stream in the group. If false, only the unhealthy stream resets. |
<StreamStartTimeout> |
Integer | Timeout in milliseconds for the first packet of any type (audio, video, or data). |
<StreamTimeout> |
Integer | Timeout in milliseconds for packets of any type (audio, video, or data) after the first. |
<VideoStartTimeout> |
Integer | Timeout in milliseconds for the first video packet. |
<VideoTimeout> |
Integer | Timeout in milliseconds for video packets after the first. |
<AudioStartTimeout> |
Integer | Timeout in milliseconds for the first audio packet. |
<AudioTimeout> |
Integer | Timeout in milliseconds for audio packets after the first. |
<VideoTCToleranceEnable>* |
Boolean | Set to true to monitor video timecode jumps. |
<VideoTCPosTolerance>* |
Integer | Maximum allowable positive gap, in milliseconds, between the current and previous video packet. |
<VideoTCNegTolerance>* |
Integer | Maximum allowable negative gap, in milliseconds, between the current and previous video packet. |
<AudioTCToleranceEnable>* |
Boolean | Set to true to monitor audio timecode jumps. |
<AudioTCPosTolerance>* |
Integer | Maximum allowable positive gap, in milliseconds, between the current and previous audio packet. |
<AudioTCNegTolerance>* |
Integer | Maximum allowable negative gap, in milliseconds, between the current and previous audio packet. |
<DataTCToleranceEnable>* |
Boolean | Set to true to monitor data timecode jumps. |
<DataTCPosTolerance>* |
Integer | Maximum allowable positive gap, in milliseconds, between the current and previous data packet. |
<DataTCNegTolerance>* |
Integer | Maximum allowable negative gap, in milliseconds, between the current and previous data packet. |
<AVSyncToleranceEnable> |
Boolean | Set to true to monitor audio/video sync timecode jumps. |
<AVSyncTolerance> |
Integer | Allowable timecode difference between the current and previous packet. |
<DebugLog> |
Boolean | Set to true to turn on verbose debug logging. |
*Note: The positive and negative tolerances define a single window. For example, if <VideoTCPosTolerance> is set to 3000 and <VideoTCNegTolerance> is set to -500, the timecode difference between an arriving video packet and the previous one must fall between -500 and 3000 milliseconds. Set any timeout or tolerance to 0 to turn that test off.
Modules
The <Modules> element contains the children listed in the table below.
| Element | Type | Description |
|---|---|---|
<Module> |
Container | Identifies the module. |
<Module>/<Name> |
String | Identifier for the module. Required. |
<Module>/<Description> |
String | A text description of the module. Optional. |
<Module>/<Class> |
String | The full package name and class name of the module. |
Property element
The <Property> element contains the children listed in the table below. Application properties are copied to child application instances at creation, and are available in the Java API through IApplicationInstance.getProperties().
| Element | Type | Description |
|---|---|---|
<Property> |
Container | The container element for a single custom property. |
<Property>/<Name> |
String | Name of the property. |
<Property>/<Value> |
— | Value of the property as defined by the type. |
<Property>/<Type> |
String | Type of property (Integer, Boolean, or String). |
Directory path variables
You can use these variables in any directory path setting, such as <StorageDir> and <TemplateDir>.
| Variable | Resolves to |
|---|---|
${com.wowza.wms.AppHome} |
Application home directory |
${com.wowza.wms.ConfigHome} |
Configuration home directory |
${com.wowza.wms.context.VHost} |
Virtual host name |
${com.wowza.wms.context.VHostConfigHome} |
Virtual host config directory |
${com.wowza.wms.context.Application} |
Application name |
${com.wowza.wms.context.ApplicationInstance} |
Application instance name |
