Configuration
This topic contains detailed configuration guidelines to enable call recording for SIPREC:
Step | Reference | Description |
|---|---|---|
1 | Configure the SRC (Session Recording Client) for call recording. NoteThis configuration should be performed by the customer’s Telephony Engineer. | |
2 | Configure the Integration Adapter on the Collector. | |
3 | Configure the RTP Collector on the Collector. | |
4 | Configure the SIP RAM on the Collector. | |
5 | Configure Custom Metadata Fields on the Collector. |
SRC Configuration
SRC (Session Recording Client) configuration will vary depending on the telephony platform being used. Please refer to the telephony platform documentation.
Integration Adapter Configuration
The Integration Adapter configuration is specified in IntegrationAdapter.ini and Identity.ini. These files are automatically generated with default values when the Collector is started for the first time.
IntegrationAdapter.ini
[General] DownstreamAPIVersion=0 RecordByDefault=1 [JetStream] ServerURL=nats://u-capture.example.com:4222 [VoiceActivityDetection] WindowSizeMS=10 UseShortTermEnergy=1 MinEnergy=0.000060 UseZeroCrossingRate=0 MinZeroCrossingRate=0.000001 MaxZeroCrossingRate=0.187400 UseActivityTriggering=0 MinActivityMS=20 ActivityEndHangTimeMS=5000 [Licence] RecordPoolChannels=1000 PP0=P9XCS8KLATSJNHGN [INSTALLED PPS] PP0=/usr/lib/libPP_Matcher.so [Phones] DetectNewItems=1
Only configuration settings relevant to this SIPREC integration are listed here. For all other settings, leave these set to their default values.
Note
2024.2 introduced the support of NATS JetStream, therefore the NATS Streaming settings (STAN and STANChannels) have been depreciated. Uniphore recommends using the new JetStream settings however the depreciated NATS Streaming settings are still available. For the depreciated STAN settings and an example of those settings in context see Depreciated NATS Streaming Settings.
[General]
[General]DownstreamAPIVersion
Controls the format of messages sent downstream to consuming applications, either:
Set to
0(default) to use the original message format ofmetadatafor metadata, andmedia.<call_id>for media.Set to
1to use the formatcall.metadata.tenant.<tenant_id>.call.<call_id>for metadata andcall.media.tenant.<tenant_id>.call.<call_id>for media.
[General]RecordByDefault
Set to 1 to enable or 0 to disable recording by default, for newly discovered devices. If not specified, the default value is 1 (enabled).
[JetStream]
[JetStream]ServerURL
The URL of the NATS server.
[JetStream]Username
If the NATS server is configured for user based authentication, specify the username here. If not specified, no value is used.
[JetStream]Password
If the NATS server is configured for user based authentication, specify the password here. If a password is used, the NATS server should also be configured to use TLS to prevent the password from being sent over the network in the clear. If not specified, no value is used.
[JetStream]Token
If the NATS server is configured for token based authentication, specify the token here. If a token is used, the NATS server should also be configured to use TLS to prevent the token from being sent over the network in the clear. If not specified, no value is used.
[JetStream]TrustedCACertificatesFileName
If the NATS server is configured to use TLS, specify the trusted CA certificate chain here. This will be the CA certificate chain that was used to sign the server certificate. If not specified, no value is used.
[JetStream]ClientCertificateChainFilename
If the NATS server is configured to use TLS with mutual-authentication, specify the client certificate chain here. This will be the client certificate plus the CA certificate chain used to sign the client certificate. If not specified, no value is used.
[JetStream]ClientCertificateKeyFilename
If the NATS server is configured to use TLS with mutual-authentication, specify the client private key here. If not specified, no value is used.
[JetStream]SkipServerVerification
If the NATS server is configured to use TLS, disables verification of the server certificate. Not recommended. If not specified, the default value is 0.
[VoiceActivityDetection]
[VoiceActivityDetection]
This section of the ini file is used to define the VAD settings. If the default configuration values don’t work for the customer, it’s recommended that you disable VAD, then record and export some example calls to WAV. These files can then be passed through a test tool that will allow the trial of different configuration values to ensure the correct parts of the call are identified as voice. The best fit configuration can then be applied to the Collector. Please contact the Uniphore Development Support Team for details.
To disable Voice Activity Detection, simply disable the use of both Short-Term Energy and Zero Crossing Rate.
[VoiceActivityDetection]WindowSizeMS
The size of the window, in milliseconds, on which to perform VAD. The default is 10 milliseconds – we don’t recommend any other value at present.
[VoiceActivityDetection]UseShortTermEnergy
Enables/disables use of the Short-Term Energy algorithm. By default, this is enabled (1).
[VoiceActivityDetection]MinEnergy
The minimum energy required for the window to be considered as voice activity. Expressed as a decimal value between zero and one. Zero being absolute silence and one being maximum loudness. The default is 0.000060. This may seem like a low value, but generally background noise will be lower than this.
[VoiceActivityDetection]UseZeroCrossingRate
Enables/disables use of the Zero Crossing Rate (ZCR) algorithm. Use of ZCR is only recommended if it’s required that tones on channel do not trigger voice recording. If this is the case, ZCR should be used in conjunction with STE. By default, ZCR is disabled (0).
[VoiceActivityDetection]MinZeroCrossingRate
The minimum Zero Crossing Rate for the window to be considered as voice activity. The default is 0.000001. Human speech has a low ZCR, increasing this value may prevent voice from being detected. A lower limit is required because a ZCR of zero indicates that the sine wave is not crossing zero i.e. the waveform is flatline (silence).
[VoiceActivityDetection]MaxZeroCrossingRate
The maximum Zero Crossing Rate for the window to be considered as voice activity. The default is 0.187400.
[VoiceActivityDetection]UseActivityTriggering
Enables/disables use of activity triggering. By default this is disabled (0). If enabled (1), a voice recording will not be created until voice activity is detected on the channel. Likewise, the voice recording will be ended on cessation of voice activity on the channel. If disabled (0), voice recordings will be created and ended based on signalling as normal.
[VoiceActivityDetection]MinActivityMS
The minimum duration of voice activity, in milliseconds, that is required to invoke voice recording. The default is 20 milliseconds. This value must be a multiple of the window size and must be between 10 and 300 milliseconds.
[VoiceActivityDetection]ActivityEndHangTimeMS
The duration, in milliseconds, to continue the voice recording after voice activity has ceased. The default is 5000 milliseconds (5 seconds). This value must be a multiple of the window size. This prevents pauses in speech from causing excessive stopping and restarting of recording.
[Licence]
[Licence]RecordInternalCalls
Enable (1) or disable (0) the recording of internal calls (extension to extension calls). If not specified, the default value is 1.
[Licence]RecordPoolChannels
Defines how many concurrent channels can be captured by the Collector. Calls over this value will be discarded. If not specified, the default value is 1000.
[Licence]PP<0…N>
PP license code for the Collector. This will have been provided as part of the customer’s deployment information from Uniphore.
[Phones]
[Phones]SegLengthSecs
The maximum recording segment length in seconds. After this duration, recordings will be split. If not specified, the default value is 3600 (1 hour).
Note
For call segmentation to work in Communication Recording Agent, SegLengthSecs should be set to an extremely high value (e.g. 9999999). This will prevent call segmentation from being carried out by the Collector.
[Phones]DetectNewItems
Enable (1) or disable (0) the automatic detection (discovery) of new devices. The default is enabled (1). In general, leave this set to 1 (enabled) for initial system setup and device discovery – if the customer then wants to “lock down” their recordable devices, this can be changed to 0 (disabled).
[Recording]
[Recording]MaxPacketsInQueue
The maximum number of packets to queue for processing before discarding packets. If not specified, the default value is 65536.
[Recording]MaxPacketLength
The maximum packet length to process in bytes. If not specified, the default value is 9018 (18 bytes for the Ethernet header and FCS, plus a 9000 byte MTU).
[Recording]MediaFlushTimeoutMS
The maximum interval (in milliseconds) to flush media data to NATS Streaming. If not specified, the default value is 10000 (10 seconds). Realtime streaming solutions should set the value to 100.
[Recording]Triggers
Set the comma separated list for the priority of recording triggers, valid options are CTI, Activity, and Signalling.
Under normal operation, the first trigger listed is used – if the source of that trigger fails then the next working trigger source in the list is used to determine when to trigger recording.
[Recording]DelayedCallEndTimeoutMS
Determine how long (in milliseconds) to continue capturing each call after the call end signal has been received, this is to allow any remaining audio to be captured. If not specified, the default value is 1000 (1 second)
[Recording]Policy
Determine which calls should be recorded, either internal extension to extension calls (Internal), external calls (External), or both internal and external calls (All). If not specified, the default value is to record just external calls (External).
Note
This setting replaces the now depreciated [Licence]RecordInternalCalls setting.
[CallSuppression]
[CallSuppression]MaxSuppressCount
The maximum number of times a given recording can be suppressed. If not specified, the default is 3 times (3).
[CallSuppression]MaxSuppressTime
The maximum length of time a given period of suppression will last. If not specified, the default is 15 seconds (15).
[CallSuppression]StopCapture
When call capture is suppressed, send (true) or do not send (false) a request that the audio feed from the 3rd party system be stopped. If not specified, the default is to send the request (true).
[CallSuppression]StopOnCallEnd
Determine if the suppression for a device is ended when the suppressed call on that device ends. If not specified, the default is false.
[STAN]ServerURL
Set to the URL of the NATS Streaming Server associated with this Collector.
[STAN]ClusterID
Defines the NATS Streaming cluster ID – must be set to stan-cluster.
[STAN]ClientID
A string that identifies this NATS Streaming client. The Collector ID is appended to this to ensure it is unique. If not specified, the default value is RedBox-IntegrationAdapter.
[STAN]Username
If the NATS Streaming Server is configured for user based authentication, specify the username here. If not specified, no value is used.
[STAN]Password
If the NATS Streaming Server is configured for user based authentication, specify the password here. If a password is used, the NATS Streaming Server should also be configured to use TLS to prevent the password from being sent over the network in the clear. If not specified, no value is used.
[STAN]CertificateChainFilename
If the NATS Streaming Server is configured to use TLS, specify the trusted CA certificate chain here. This will be the CA certificate chain that was used to sign the server certificate. If not specified, no value is used.
[STAN]ClientCertificateChainFilename
If the NATS Streaming Server is configured to use TLS, specify the client certificate chain here. This will be the client certificate plus the CA certificate chain used to sign the client certificate. If not specified, no value is used.
[STAN]ClientCertificateKeyFilename
If the NATS Streaming Server is configured to use TLS, specify the client private key here. If not specified, no value is used.
[STAN]Ciphers
If the NATS Streaming Server is configured to use TLS, this value can be used to restrict the allowed ciphers. If not specified, no value is used.
An example of the depreciated NATS Streaming settings:
[STAN] ServerURL=nats://abcd.dev.mycompany.com:4222 ClusterID=stan-cluster ClientID=RedBox-IntegrationAdapter-1 ConnectionTimeoutMS=15000 RetryWaitMS=15000 Username= Password= SkipServerVerification=0 CertificateChainFilename= ClientCertificateChainFilename= ClientCertificateKeyFilename= Ciphers= [STANChannels] Alerts=RedBox.Collector.Alert EventLogs=RedBox.Collector.EventLogs ConfigRequests=RedBox.Collector.ConfigRequests ConfigEvents=RedBox.Collector.ConfigEvents Media=media Metadata=metadata
Identity.ini
TenantID=dcedc429-11a9-4408-84a7-c781363c62e1 TenantName=test CollectorID=0f89817f-e324-48ca-bcb6-3d61f292755b CollectorName=collector1
TenantId
Set to the unique identifier of the tenant associated with this Collector. If no tenants are defined, the default test tenant will be used dcedc429-11a9-4408-84a7-c781363c62e1
TenantName
The name of the tenant to which the Collector belongs (optional).
CollectorId
The unique identifier for this Collector. A UUID will be automatically generated and written to Identity.ini on first start.
CollectorName
The name of the Collector (optional).
RTP Collector Configuration
The RTP Collector works in sync with the SIP RAM. The SIP RAM manages the SIP dialog and the RTP Collector owns the RTP session.
The RTP Collector configuration is specified in RTPCollector.ini – this file is automatically generated with default values on first start. An example is shown below:
[MediaPorts] Min=25000 Max=65535 [SRTCP] UseSRTCPWhenSRTP=1 [docker0] Use=0 IPv4Address=10.0.2.15 [<adapter-name>] Use=1 IPv4Address=10.0.2.42 IPv6Address=2001:db8::1234:5678
Settings
Only config settings relevant to this SIPREC integration are listed here. For all other settings, leave these set to their default values.
[MediaPorts]
Defines the RTP media port range to capture data from.
[MediaPorts]Min
The beginning of the media port range. Default is 25000.
[MediaPorts]Max
The end of the media port range. Default is 65535.
[SRTCP]UseSRTCPWhenSRTP
Enables/disables the expectation that RTCP will also be encrypted when SRTP is being used for a given session. If not specified, defaults to 1 (enabled).
[<adapter-name>]
The RTP Collector discovers all available network adapters on start-up – they’re listed by their device name (GUID). The adapter’s IPv4 address is displayed for ease of identification. By default, all adapters are enabled for media traffic. Enable (Use=1, default) or disable (Use=0) adapters as needed.
It’s important that only adapters reachable by the telephony system are used. Adapters are load balanced, so sessions will be evenly distributed across all enabled adapters.
[<adapter name>]AdvertisedIPv4Address
Overrides the IPv4 address advertised for the given network adapter. This is useful when you need an ingress address that is not an address belonging to the RTP Collector itself. If not specified, then defaults to the adapter’s IPv4 address.
SIP RAM Configuration
The SIP RAM configuration is specified in SIP_RAM.ini – this file is automatically generated with default values on first start. An example is shown below:
[SIPRAMSettings] Protocol=udp SIPPort=5060 MaxConcurrentCalls=1000 ExtensionField=from [SIP] MessageLogging=1 [SecureConnections] Ciphers= ClientVerificationMode=Mandatory [SRTP] Disabled=0 Mode=2 [RTPCollector1] Host=localhost Port=6500 TimeoutMS=1000 [Control] ListenPort=6501 [Codecs] Count=23 0=G.711 mu-law 1=GSM 06.10723.1 3=ADPCM 32 kbit/s 4=ADPCM 64 kbit/s 5=G.711 a-law 6=G.722 7=G.728 8=ADPCM 44.1 kbit/s 9=ADPCM 88.2 kbit/s 10=G.729 11=G.722.1 24 kbit/s 16 Khz 12=G.722.1 32 kbit/s 16 Khz 13=G.722.1 24 kbit/s 32 Khz 14=G.722.1 32 kbit/s 32 Khz 15=G.722.1 48 kbit/s 32 Khz 16=G.726 16 kbit/s 17=G.726 24 kbit/s 18=G.726 32 kbit/s 19=G.726 40 kbit/s 20=AMR Narrow-Band 21=AMR Wide-Band 22=Opus [SIPRegistration1] AoR= Password= OutboundProxy= [SIPREC] ExtensionModuleDirectory=/usr/local/lib/SIPREC
Settings
Only config settings relevant to this SIPREC integration are listed here. For all other settings, leave these set to their default values.
[SIPRAMSettings]IP
The hostname or IP address of the Integration Adapter. If not specified, defaults to localhost.
[SIPRAMSettings]Protocol
The SIP transport protocol to use (udp, tcp, tls, or any). Default is udp.
[SIPRAMSettings]SIPPort
The port to listen for SIP communications on. Default is 5060. If [SIPRAMSettings]Protocol is an explicit protocol, then [SIPRAMSettings]SIPPort describes an explicit port for that protocol. If [SIPRAMSettings]Protocol is any, then [SIPRAMSettings]SIPPort describes the base port used for non-secure SIP and secure SIP uses the base port plus one.
[SIPRAMSettings]MaxConcurrentCalls
The number of active SIP sessions allowed before new sessions will be rejected with a SIP 503 response. Default is 1000. This setting should match the channel count - see [Licence]RecordPoolChannels.
[SIPRAMSettings]ExtensionField
Allows the SIP RAM to be configured to take the user from the to header as the recorded extension. If not specified, defaults to from.
[SIP]MessageLogging
Enables (1) or disables (0) logging of SIP messages. If not specified, defaults to 1.
[SecureConnections]Ciphers
Allows the TLS and DTLS ciphers to be overridden.
[SecureConnections]ServerCertificatePath
The path to the server certificate that identifies the Uniphore SIP User Agent. This is only required where TLS or DTLS transports are in use. The certificate file must be PEM encoded.
[SecureConnections]ServerKeyPath
Specifies the PEM format private key file that corresponds to the SIP RAM server certificate. If not specified, no certificate is used.
[SecureConnections]ClientVerificationMode
Determine the client certificate verification behaviour. Valid values include Optional (Default, the client certificate is validated if the client presents one. If no certificate is sent, the connection is still accepted), None (The client certificate verification is completely disabled. Invalid or missing certificates are ignored), and Mandatory (The client must present a valid certificate. The TLS handshake is rejected if no valid certificate is provided).
This setting must be set to None if the client sends a certificate.
[SRTP]Disabled
Disables use of SRTP (set to 1). If not specified, defaults to 0.
[SRTP]Mode
Specifies the negotiation mode for setting up SRTP. If not specified, defaults to 2 (best effort). Acceptable values are:
1 (mandatory – if the peer does not support SRTP, the session will fail)
2 (best effort – if the peer supports SRTP, SRTP will be used)
3 (fallback)
4 (multiple media descriptor)
[ RTPCollector<1…N>]Host
The hostname or IP address of the RTP Collector. If not specified, defaults to localhost.
[RTPCollector<1…N>]Port
The port on which to communicate with the given RTP Collector. If not specified, defaults to 6500.
[RTPCollector<1…N>]TimeoutMS
The duration, in milliseconds, to wait for a response from the given RTP Collector before considering the request timed out. If not specified, defaults to 1000.
[ Control]ListenPort
The port on which to listen for client connections from services wishing to control the SIP RAM. If not specified, defaults to 6501.
[Codecs]
This section contains the enabled codecs in priority order. Values must be entered as shown below (case and whitespace sensitive) – possible values are as follows:
G.711 a-lawG.711 mu-lawG.722G.722.1 24 kbit/s 16 KhzG.722.1 32 kbit/s 16 KhzG.722.1 24 kbit/s 32 KhzG.722.1 32 kbit/s 32 KhzG.722.1 48 kbit/s 32 KhzG.723.1G.726 16 kbit/sG.726 24 kbit/sG.726 32 kbit/sG.726 40 kbit/sG.728G.729ADPCM 32 kbit/sADPCM 44.1 kbit/sADPCM 64 kbit/sADPCM 88.2 kbit/sAMR Narrow-BandAMR Wide-BandGSM 06.10Opus
[SIPRegistration<N>]AoR
The Address of Record to register. Should be of the form:
<schema>:<user>@<domain>[:<port>][;transport=<protocol>]
Where:
Schema is either
siporsips.User is the user to register.
Domain is the domain to which the user belongs.
Port (optional) default:
5060for udp and tcp,5061for tls and dtls. An integer between1and65535.Protocol (optional) default:
udpif[SIPRAMSettings]Protocol=any, otherwise the specified protocol. Acceptable values areudp,tcp,tls, anddtls.
[SIPRegistration<N>]Password
The password to use when presented with an authentication challenge. Will be removed on first start and the value encrypted and stored in [SIPRegistration<N>]Password.Encrypted.
[SIPRegistration<N>]Password.Encrypted
The encrypted password. Do not modify.
[SIPRegistration<N>]OutboundProxy
The hostname or IP address of the outbound proxy (optional).
Configure Custom Metadata Extensions
Since SIPREC metadata XML varies between telephony platforms, we recommend that you take a Wireshark trace or review SIP messages.txt and examine the XML data to analyze the structure and available fields. A sample set of recording metadata is shown below:
<?xml version="1.0" encoding="UTF-8"?>
<recording xmlns='urn:ietf:params:xml:ns:recording:1'>
<datamode>complete</datamode>
<group group_id="NzI0MDc5MDAtYmI2ZS0xMA==">
<associate-time>2018-10-26T16:59:38Z</associate-time>
<callData xmlns='urn:ietf:params:xml:ns:callData'>
<fromhdr>
"01159377100" <sip:01159377100@172.16.250.4:5060>;tag=gK082281ca
</fromhdr>
<tohdr>
<sip:01483920633@192.168.1.13:5060>;tag=0_3017003168-335468980
</tohdr>
<callid>524346_134154658@172.16.250.4</callid>
<gcid>524346</gcid>
</callData>
</group>
<session session_id="NzQ0MTQxM2UtYmI2ZS0xMA==">
<group-ref>NzI0MDc5MDAtYmI2ZS0xMA==</group-ref>
<start-time>2018-10-26T16:59:38Z</start-time>
</session>
<participant participant_id="NzI0MDc5MDEtYmI2ZS0xMA==">
<nameID aor="01159377100@172.16.250.4:5060">
<name xml:lang="en">01159377100</name>
</nameID>
</participant>
<participant participant_id="NzI0MDc5MDItYmI2ZS0xMA==">
<nameID aor="01483920633@192.168.1.13">
<name xml:lang="en"> </name>
</nameID>
</participant>
<stream stream_id="NzI0MDc5MDQtYmI2ZS0xMA=="
session_id="NzQ0MTQxM2UtYmI2ZS0xMA==">
<label>1</label>
</stream>
<stream stream_id="NzI0MDc5MDUtYmI2ZS0xMA=="
session_id="NzQ0MTQxM2UtYmI2ZS0xMA==">
<label>2</label>
</stream>
<sessionrecordingassoc session_id="NzQ0MTQxM2UtYmI2ZS0xMA==">
<associate-time>2018-10-26T16:59:38Z</associate-time>
</sessionrecordingassoc>
<participantsessionassoc participant_id="NzI0MDc5MDEtYmI2ZS0xMA=="
session_id="NzQ0MTQxM2UtYmI2ZS0xMA==">
<associate-time>2018-10-26T16:59:38Z</associate-time>
</participantsessionassoc>
<participantsessionassoc participant_id="NzI0MDc5MDItYmI2ZS0xMA=="
session_id="NzQ0MTQxM2UtYmI2ZS0xMA==">
<associate-time>2018-10-26T16:59:38Z</associate-time>
</participantsessionassoc>
<participantstreamassoc participant_id="NzI0MDc5MDEtYmI2ZS0xMA==">
<associate-time>2018-10-26T16:59:38Z</associate-time>
<send>NzI0MDc5MDQtYmI2ZS0xMA==</send>
<recv>NzI0MDc5MDUtYmI2ZS0xMA==</recv>
</participantstreamassoc>
<participantstreamassoc participant_id="NzI0MDc5MDItYmI2ZS0xMA==">
<associate-time>2018-10-26T16:59:38Z</associate-time>
<send>NzI0MDc5MDUtYmI2ZS0xMA==</send>
<recv>NzI0MDc5MDQtYmI2ZS0xMA==</recv>
</participantstreamassoc>
</recording>Create a Custom.ini file – an example is shown below:
[CallID] Location=group.callData.callid Regex=^[\w-]+ FieldId=96 [GCID] Location=group.callData.gcid FieldId=1000
In this example, the value of the group.callData.callid element, up until the ‘@’, will be populated into field ID 96 (AnnotationText1) and the value of the group.callData.gcid element will be populated into field ID 1000 (AnnotationText2).
Each configured item takes the following format:
[<Name>] Location=<Location> Regex=<Regex> FieldId=<DatabaseFieldID>
Item | Description |
|---|---|
| Name of the configured value. Must be unique in the Custom.ini file. |
| The XML path to the element of interest. Relative to recording. Case sensitive. Where multiple instances of an element exist, an array index may be specified. If no index is specified, index zero is assumed. E.g. |
| Optional. Required if it is desirable to capture only a part of the element value. A standard regular expression. Use of www.Regex101.com is advised. |
| The ID of the database field that should be used to store this value. Field ID’s are listed in Database Field IDs. The selected database field can be mapped to an appropriate Metadata field using the Communication Recording Agent mapping features. |
The SIP RAM service or Collector must be restarted for changes to this configuration to take effect.
SIPREC Recording Control
The recordable item is configured for recording in the SRC and then a call has been made.