6 Anchoring Media Sessions
This chapter explains how to use the Oracle Communications WebRTC Session Controller Media Engine (Media Engine) features to anchor media sessions.
About the WebRTC Session Controller Media Server
You use Media Engine to:
-
Establish communication between a WebRTC-enabled browser and a Session Initiation Protocol (SIP) or a public switched telephone network (PSTN) device.
-
Establish communication between two end points (WebRTC-enabled browsers, or SIP or PSTN based devices) that do not share a common codec they can use to communicate directly.
-
Enable a content service provider to forcibly anchor a call for example, to lawfully intercept it.
In the WebRTC Session Controller JsonRTC protocol, you use the WscMediaFactory interface in the oracle.wsc.feature.webrtc.template.media package to interact with Media Engine. It includes these methods:
-
createSdpOffer - Can contain the media session ID, SDP data, fromMediaConfigName, and toMediaConfigName to use, and the From and To URLs to use for communication. See "About Media Engine Sessions" for details on the supported sessions.
-
createSdpAnswer - Contains the media session ID and SDP data.
-
createReleaseRequest - Contains the media session ID to release. This method releases the media or resources currently being used by the callee.
-
isAvailable - Confirms that a Media Engine can be used. This is useful in cases where your Groovy script uses the Media Engine functionality if one is available, or does its own internal processing (attempts to connect the two client directly) if not.
See WebRTC Session Controller Configuration API Reference for details on this interface and these methods.
Figure 6-1 shows a flow of SDP data between two clients, in this case a WebRTC-enabled browser and a SIP endpoint. The two Signaling Engines may be different nodes in a clustered implementation, or they may be the same instance. This flow also shows where the processSdpOffer, processSdpAnswer, and createReleaseRequest actions occur.
In a typical scenario, Signaling Engine sends a createSdpOffer message to the Media Engine that includes all possible codecs that the caller supports. The Media Engine then returns modified SDP data including a list of the codecs that it supports and allows.
Further, the callee's SDP data, including a list of supported codecs, is sent from the SIP proxy to Signaling Engine in a 200/OK message, as shown in Figure 6-1. Signaling Engine then sends a createSdpAnswer to Media Engine with the list of codecs. If any codecs sent by Signaling Engine match the codecs supported by the Media Engine, the Media Engine returns the codecs it supports. Or, if Media Engine is configured to do so, it may attempt to convert the media stream to a alternate codec that the callee can use.
Once the media session has terminated, you send a createReleaseRequest message to the media server to release any resources the media server has allocated.
This code snippet from the Signaling Engine default call package, FROM_NET/INVITE/request criteria shows how to set up media anchoring:
if(Constants.ME_CONFIG_NAME_NET && sdpString!=null) {
def sdpOffer = context.mediaFactory.createSdpOffer("1", sdpString, Constants.ME_CONFIG_NAME_NET, null, sipAddressToString(sipRequest.to), sipAddressToString(sipRequest.from));
def ascFuture = sdpOffer.send()
context.getTaskBuilder("processMediaResponseToSendWebMsg").withArg("ascFuture", ascFuture).withArg("webMessage",webMessage).onSuccess(ascFuture).build();
}
else{
webMessage.send()
}
This Groovy code tests whether a Media Engine is available, and if so sends a createSdpOffer request to the Media Engine with SDP data. If no Media Engine is available sends a webMessage.
This code snippet from the Script Library shows one example of handling a reply from Media Engine:
void processMediaResponseToSendWebMsg(TemplateContext context) {
def resp = context.taskArgs.ascFuture.get();
def newSdp = resp.getSdp();
def webMessage = context.taskArgs.webMessage
if (webMessage.payload) {
webMessage.payload.sdp = newSdp
} else {
webMessage.payload = [sdp : newSdp]
}
webMessage.send()
}
It processes the response and sends the new SDP data back to the original caller.
About Media Engine Sessions
Table 6-1 lists the supported Media Engine session types, as assigned to the Groovy constant, ME_CONFIG_NAME_DMA, in the Groovy library, lists their Media Engine config names, and describes how they are used.
Table 6-1 Media Engine Session Types
| Session Type | Config Name | Description |
|---|---|---|
|
Web to Web Conditional Anchoring |
web-to-web-anchor-conditional |
Used when WebRTC-enabled browsers are allowed to communicate directly. If for some reason they cannot communicate directly, they can communicate through WebRTC Session Controller |
|
Web to Web Forced Anchoring |
web-to-web-anchored |
Forces all media flows through Media Engine. |
About Using createSdpOffer to Modify INVITE SDP Data
You use the createSdpOffer method to direct Media Engine to process SDP data sent by the calling end point. You either send SDP data with this method for Media Engine to process, or send the name of a media configuration that the node uses to determine for itself which SDP data to use. The Media Engine replies to Signaling Engine with the new or modified SDP data. Signaling Engine then uses the SDP data returned in the call's media session.
createSdpOffer includes these parameters:
-
A set of SDP data to use.
-
A media configuration name. The Media Engine uses the media configuration to select SDP data to return to the Signaling Engine. Media configuration names must be preconfigured on the Media Engine. See "About Media Engine Sessions" for details.
-
A fromURI.
-
A toURI.
You can send a session_id value with createSdpOffer to identify a specific media session. For example, createSdpAnswer requires a session_id to function.
You use the send() method from the oracle.wsc.feature.webrtc.template interface, WscMessage package to send createSdpOffer. See WebRTC Session Controller Configuration API Reference for details on send().