How to receive SAP packets and process them

We were asked to look at SAP (Session Announcement Protocol) and how we could make it work with Wowza Streaming Engine.

It turns out it is a relatively simple protocol but there are few gotchas which did trip us up however we have come up with an application module that should meet most needs along with a server listener to start applications when the server starts (so applications can listen for SAP packets).

If you are not completely familiar with SAP, do have a Google, however it is possible that multiple addresses can be announced to, thus the simplest method was to provide properties at the application level so each application can listen for different addresses if needed.

The SAP protocol also does not provide a ‘stream name’ so this presented a challenge, as in order for Wowza Streaming Engine to take in a stream it does need to have a name/filename. To solve this we generate a MD5 of the SDP information presented in the SAP packet and use that as the SDP filename. As an MD5 is not the most memorable name so we have also provided the ability to map the MD5 to an actual name via a text file.

The module DOES NOT support encrypted or compressed SAP packets but does support add and delete sessions.

To configure the application level add the following module as the last module in the Modules section.

Module setup:

<Module>
<Name>SAPReceiver</Name>
<Description>SAPReceiver</Description>
<Class>guru.thewowza.example.sap.module.Receiver</Class>
</Module>

The defaults are as follows

- SAP Address to listen on 239.255.255.255
- SAP Port to listen on 9875
- Interface to listen on – first found (Java default)
- SAP MD5 to stream name text file – sapSDPMap.txt

The MD5 to stream name text file should be put in the <StorageDir> location which by default is the /content/ folder. It is a simple text file and consists of a MD5:StreamName so examples being

60a4adf69187e461c216e74e88c13f8b:demoSDPStream

If a MD5 is not found in the file then that is used as the stream name. The .sdp suffix is automatically added to the md5 or stream name found in the file. Unfortunately the only method to determine what the MD5 will be is to announce the stream and either stop Wowza Streaming Engine or unannounce the stream.

The following is a list of application level properties that can be set/changed

twgSAPSDPMapFile – This sets the filename, default us sapSDPMap.txt. It does NOT change the location. This must set with StorageDir parameter.

<Property>
<Name>twgSAPSDPMapFile</Name>
<Value>sapSDPMap.txt</Value>
<Type>String</Type>
</Property>

twgSAPMulitcastAddress – This is the multicast address to listen for SAP packets on. The default is 239.255.255.255.

<Property>
<Name>twgSAPMulitcastAddress</Name>
<Value>239.255.255.255</Value>
<Type>String</Type>
</Property>

twgSAPMulticastPort – This is the port the SAP packets are sent to. The default for SAP is 9875, however you can change it with this property.

<Property>
<Name>twgSAPMulticastPort</Name>
<Value>9875</Value>
<Type>Integer</Type>
</Property>

twgSAPMulticastInterface – When using multicast it is common for a server to have multiple interfaces. This allows you to set, by IP address, the interface to use to receive SAP announcements. DO NOT SET THIS UNLESS YOU NEED TO!

<Property>
<Name>twgSAPMulticastInterface</Name>
<Value>10.18.5.23</Value>
<Type>String</Type>
</Property>

twgSAPExpireTime – The default to expire SAP announcements. When SAP announcements are made for a stream they should be fairly regular and when a session stops a remove/delete should be sent. If the announcements stop and the delete/remove is not sent/missed this setting automatically expires the session. It is in milliseconds. The default is 1 hour (SAP specification).

<Property>
<Name>twgSAPExpireTime</Name>
<Value>3600000</Value>
<Type>Long</Type>
</Property>

twgSAPDebug – You can see the SAP packets being received. You can see the decoding taking place and the information received. It is very verbose.

<Property>
<Name>twgSAPDebug</Name>
<Value>true</Value>
<Type>Boolean</Type>
</Property>

One of the issues we also faced is that as an application module it will not start unless (i) a connection is made or (ii) we force it to start upon startup of Wowza Streaming Engine.

We have included in the code a server listener that you can configure to start up applications to receive SAP announcements (you do need to configure the module on the applications in question as well).

To use the server listener add the following to the ServerListeners section of your Server.xml

<ServerListener>
<BaseClass>guru.thewowza.example.sap.listener.Receiver</BaseClass>
</ServerListener>

By default it will start the application called ‘live’ however you can configure two properties to change this behaviour

twgSAPReceiverLoadVhost – The Vhost name to use. Only one is permitted and the default is ‘_defaultVHost_’ and this property does not need setting.

<Property>
<Name>twgSAPReceiverLoadVhost</Name>
<Value>_defaultVHost_</Value>
<Type>String</Type>
</Property>

twgSAPReceiverApplications – This should be a comma separated list of application/applicationInstance names. The default is live/_definst_

<Property>
<Name>twgSAPReceiverApplications</Name>
<Value>live/_definst_</Value>
<Type>String</Type>
</Property>

You can download an example Application.xml, sapSDPMap.txt and Server.xml along with a jar file and source code from Here.


Comments are closed.