With Wowza Streaming Engine™ 4.9.6 and later, you can use the Wowza Streaming Engine REST API to set up SRT listener mode when ingesting and publishing Secure Reliable Transport (SRT) streams.
SRT listener mode offers a simplified configuration. Multiple SRT streams can be pushed directly to Wowza Streaming Engine without the need to create separate .stream files for each incoming stream. Additionally, this mode reduces the effort required to manage firewall settings and to open numerous UDP ports when connecting SRT listener streams.
This guide explains how to achieve the SRT listener mode programmatically with the Wowza Streaming Engine REST API. We include configuration steps for using a global passphrase or per-user encryption for better security.
For the non-programmatic approach and additional information about these workflows, see Ingest and publish an SRT stream with Wowza Streaming Engine.
Overview
The SRT listener mode setup requires a one-time Server.xml, VHost.xml, and Application.xml configuration.
You can use a global passphrase or per-user encryption for better security. The global passphrase is a single encryption key shared between the sender and authorized receivers. This method simplifies setup and is ideal for public or semi-private streams.
With per-user encryption, you can assign a unique passphrase for each user to prevent unauthorized access. This prohibits one user from intercepting another user's stream. If a passphrase is compromised, only the affected user is impacted, not the entire system.
Before you start
Before you start working with the steps in this guide, we recommend that:
- You are familiar with using curl for making HTTP requests. For more, see Query the REST API using cURL.
- You are familiar with using FFmpeg as your encoder for streaming. For more, see the FFmpeg Streaming Guide.
- You have reviewed the Authenticating requests section to better understand how to authenticate API requests.
- You have reviewed Access reference documentation for the Wowza Streaming Engine REST API to display the reference documentation locally.
- You have reviewed Ingest and publish an SRT stream with Wowza Streaming Engine for the manual configuration details for this workflow.
1. Configure your Server.xml
The first step is to update the Server.xml configuration file located at [install-dir]/conf/Server.xml to include:
<VHostListeners>
<VHostListener>
<BaseClass>com.wowza.wms.protocol.srtListener.SRTVHostListener</BaseClass>
</VHostListener>
</VHostListeners>
Sample request
curl -X PUT \
--basic -u "user:password" \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://localhost:8087/v2/servers/_defaultServer_/vhostlisteners" \
-d'
{
"serverName": "_defaultServer_",
"vhostListeners": [
{
"baseclass": "com.wowza.wms.protocol.srtListener.SRTVHostListener",
"order": 0
}
]
}'
Sample response
{
"success": true,
"message": "Saved",
"data": null
}
2. Configure your VHost.xml
Next, modify the VHost.xml configuration file located at [install-dir]/conf/VHost.xml. We suggest making a backup copy of this configuration file before modifying it.
This step adds only the required SRTListener properties and initially sets a global passphrase. Optional SRT listener properties can't be set via the REST API. You can override the global passphrase and set a per-user passphrase later.
<SRTListener> <!-- Basic listener configuration --> <srtListenerLocalPort>4008</srtListenerLocalPort> <srtListenerLocalIPAddress>127.0.0.1</srtListenerLocalIPAddress> <srtPassPhrase>[my-global-srt-passphrase]</srtPassPhrase> </SRTListener>
Sample request
curl -X PUT \
--basic -u "user:password" \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_" \
-d'
{
"HostPorts": [
{
"HTTPProviders": [
{
"authenticationMethod": "none",
"baseClass": "com.wowza.wms.http.HTTPCrossdomain",
"requestFilters": "*crossdomain.xml"
},
{
"authenticationMethod": "none",
"baseClass": "com.wowza.wms.http.HTTPClientAccessPolicy",
"requestFilters": "*clientaccesspolicy.xml"
},
{
"authenticationMethod": "none",
"baseClass": "com.wowza.wms.http.HTTPProviderMediaList",
"requestFilters": "*jwplayer.rss|*jwplayer.smil|*medialist.smil|*manifest-rtmp.f4m"
},
{
"authenticationMethod": "none",
"baseClass": "com.wowza.wms.http.HTTPServerVersion",
"requestFilters": "*ServerVersion"
}
],
"ipAddress": "*",
"name": "Default Streaming",
"port": "1935",
"sslEnable": false,
"type": "Streaming",
"webRtcEnable": false
},
{
"HTTPProviders": [
{
"authenticationMethod": "admin-basic",
"baseClass": "com.wowza.wms.http.HTTPServerInfoXML",
"requestFilters": "serverinfo*"
},
{
"authenticationMethod": "admin-basic",
"baseClass": "com.wowza.wms.http.HTTPConnectionInfo",
"requestFilters": "connectioninfo*"
},
{
"authenticationMethod": "admin-basic",
"baseClass": "com.wowza.wms.http.HTTPConnectionCountsXML",
"requestFilters": "connectioncounts*"
},
{
"authenticationMethod": "admin-basic",
"baseClass": "com.wowza.wms.transcoder.httpprovider.HTTPTranscoderThumbnail",
"requestFilters": "transcoderthumbnail*"
},
{
"authenticationMethod": "admin-basic",
"baseClass": "com.wowza.wms.http.HTTPProviderMediaList",
"requestFilters": "medialist*"
},
{
"authenticationMethod": "none",
"baseClass": "com.wowza.wms.http.HTTPServerVersion",
"requestFilters": "*ServerVersion"
}
],
"ipAddress": "*",
"name": "Default Admin",
"port": "8086",
"sslEnable": false,
"type": "Admin",
"webRtcEnable": false
}
],
"srtListenerLocalPort": 4008,
"srtListenerLocalIPAddress": "127.0.0.1",
"srtPassPhrase": "[my-global-srt-passphrase]"
}'
Sample response
{
"success": true,
"message": "Saved",
"data": null
}
3. Create a live application
In this section, we create an srtListener application and update the Application.xml file located at [install-dir]/conf/[application-name]/. You can encrypt your stream using a global passphrase or a per-user passphrase. Toggle between the following tabs to select the best method for your use case.
Encrypt with a global passphrase
The sample request in this section creates the srtListener live application and encrypts it using a global passphrase. srtListener is only a placeholder, so update the application name to fit your workflow. The PublishMethod in this case is set to none.
<SRTListener> <Authentication> <!-- basic: Enable SRT listener mode for you application and require per-user passphrase --> <!-- none: Enable SRT listener mode for your application and use global passphrase --> <!-- block: Disable SRT listener mode for your application --> <!-- To bypass encryption, use none and don't specify an srtPassPhrase in the VHost.xml --> <PublishMethod>none</PublishMethod> </Authentication> </SRTListener>
Sample request
curl -X POST \
--basic -u "user:password" \
-H 'Accept: application/json; charset=utf-8' \
-H 'Content-Type: application/json; charset=utf-8' \
http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/srtListener \
-d '{
"appType": "Live",
"name": "srtListener",
"description": "A test app for SRT listener mode using a global passphrase",
"httpCORSHeadersEnabled": true,
"streamConfig": {
"streamType": "live",
"liveStreamPacketizer": [
"cupertinostreamingpacketizer",
"mpegdashstreamingpacketizer"
]
},
"srtListenerAuthenticationMode": "none"
}'
Sample response
{
"success": true,
"message": "Application (srtListener) created successfully.",
"data": null
}
Encrypt with a per-user passphrase
The sample request in this section creates the srtListener live application and encrypts it using a per-user passphrase. srtListener is only a placeholder, so update the application name to fit your workflow. The PublishMethod in this case is set to basic.
<SRTListener> <Authentication> <!-- basic: Enable SRT listener mode for you application and require per-user passphrase --> <!-- none: Enable SRT listener mode for your application and use global passphrase --> <!-- block: Disable SRT listener mode for your application --> <!-- To bypass encryption, use none and don't specify an srtPassPhrase in the VHost.xml --> <PublishMethod>basic</PublishMethod> </Authentication> </SRTListener>
Sample request
curl -X POST \
--basic -u "user:password" \
-H 'Accept: application/json; charset=utf-8' \
-H 'Content-Type: application/json; charset=utf-8' \
http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/srtListener \
-d '{
"appType": "Live",
"name": "srtListener",
"description": "A test app for SRT listener mode using a per-user passphrase",
"httpCORSHeadersEnabled": true,
"streamConfig": {
"streamType": "live",
"liveStreamPacketizer": [
"cupertinostreamingpacketizer",
"mpegdashstreamingpacketizer"
]
},
"srtListenerAuthenticationMode": "basic"
}'
Sample response
{
"success": true,
"message": "Application (srtListener) created successfully.",
"data": null
}
4. Add authentication for per-user encryption
You can skip this step if using a global passphrase. However, you must run this request when encrypting an SRT stream with a per-user passphrase. The request adds a source username and password to authenticate your live source. Passwords are saved to the publish.password file.
Note: In this context, the source password serves as the passphrase to encrypt and decrypt SRT video streams when using SRT listener mode. It's part of the AES encryption feature built into the SRT protocol, ensuring only authorized receivers who know the passphrase can view the stream. SRT passphrases must be between 10 and 79 characters.
Sample request
curl -X POST \
--basic -u "user:password" \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://localhost:8087/v3/servers/_defaultServer_/publishers" \
-d'
{
"publisher": "[my-srt-user]",
"password": "[my-srt-user-passphrase]"
}'
Sample response
{
"success": true,
"message": "",
"data": null
}
5. Restart your server
Restart your server for all configuration changes to take effect.
Sample request
curl -X PUT \ --basic -u "user:password" \ -H 'Accept:application/json; charset=utf-8' \ -H 'Content-Type:application/json; charset=utf-8' \ "http://localhost:8087/v2/servers/_defaultServer_/actions/restart"
Sample response
{
"success": true,
"message": "Restarting server in 5 seconds",
"data": null
}
6. Publish your stream
Start a stream and send it to your Wowza Streaming Engine server. Toggle between the following tabs to select the best method for your use case.
Publish using a global passphrase
When using FFmpeg as your encoder and a global passphrase, your command looks similar to:
ffmpeg -re \ -i elephantsDream.mp4 \ -c copy \ -f mpegts \ "srt://[srt-listener-public-ip-address]:[srt-listener-port]?passphrase=[global-passphrase]&pbkeylen=32&mode=caller&streamid=#!::m=publish,r=[application-name]/[stream-name]"
The placeholder values in the previous ffmpeg command can be described as follows:
- srt-listener-public-ip-address: Use the public IP address of the Wowza Streaming Engine instance where you're sending the SRT stream. This is the srtListenerLocalIPAddress value from your VHost.xml configuration.
- srt-listener-port: Use the srtListenerLocalPort value from your VHost.xml configuration.
- global-passphrase: Use the srtPassPhrase value from your VHost.xml configuration.
- application-name: Use the application name and instance for your live application.
- stream-name: Specify a stream name or stream key to use when the stream is published in Wowza Streaming Engine.
Publish using a per-user passphrase
When using FFmpeg as your encoder and a per-user passphrase, your command looks similar to:
ffmpeg -re \ -i elephantsDream.mp4 \ -c copy \ -f mpegts \ "srt://[srt-listener-public-ip-address]:[srt-listener-port]?passphrase=[user-passphrase]&pbkeylen=32&mode=caller&streamid=#!::m=publish,u=[user-name],r=[application-name]/[stream-name]"
The placeholder values in the previous ffmpeg command can be described as follows:
- srt-listener-public-ip-address: Use the public IP address of the Wowza Streaming Engine instance where you're sending your SRT stream. This is the srtListenerLocalIPAddress value from your VHost.xml configuration.
- srt-listener-port: Use the srtListenerLocalPort value from your VHost.xml configuration.
- user-passphrase: Use the source password you created for per-user passphrase encryption.
- user-name: Use the source username you created for per-user passphrase encryption.
- application-name: Use the application name and instance for your live application.
- stream-name: Specify a stream name or stream key to use when the stream is published in Wowza Streaming Engine.
7. Test playback
To test playback of the SRT stream over the streaming protocols you enabled for your application, go to our Wowza Test Player. If using the default application instance, you can play back an HLS stream with:
https://[server-ip-address]:1935/[application-name]/_definst_/[stream-name]/playlist.m3u8
