Development -> Planning -> Media Exchange Feature

The main purpose of OpenSIPS is to behave as a SIP proxy, without interfering with the media between the user agents. There are however cases where one might need to push a certain media stream towards one (or both) call participants, for example for playing back music on hold messages, recording a call, or playing certain announcements. The purpose of the Media Exchange module is to facilitate OpenSIPS users to be able to take media from a call, coming from or going to a media announcement SIP server, and push it into an existing call.

1.  Script primitives

1.1  media_send_to_uri(URI[, leg[, body[, headers]]])

• Description: behaves as a B2B user agent client to initiate a call to a SIP URI and then stream the media to the SDP received in the 200 OK response.
• Parameters:
  • URI: SIP destination where to push the current call media
  • leg: the leg that is going to be streamed: caller, callee, or both
  • body: custom body to use in INVITE
  • headers: extra headers to add in INVITE
• Usage scenarios:
  • Call Recording

1.2  media_send_from_call(callid[, leg])

• Description: starts streaming the media of a current call identified by the callid to the SDP in the request body.
• Parameters:
  • callid: the identifier of the callid to pull media from
  • leg: the leg that is going to be streamed: caller, callee, or both
• Usage scenarios:
  • Call listening - a different endpoint calls in to listen the conversation

1.3  media_fetch_from_uri(URI[, leg[, body[, headers[, nohold]]]])

• Description: sends an invite to the URI specified. The response SDP is fetched and pushed towards one of the call’s legs, resulting in two way audio between the leg and the new call. The other leg is put on hold.
• Parameters:
  • URI: SIP destination where to send INVITE
  • leg: the leg to mix the media received from the created leg
  • body: custom body to use in INVITE
  • headers: custom headers added to the INVITE
  • nohold: do not put the other leg on hold
• Usage scenarios:
  • Playback music on hold - when an entity puts a call on hold, one can trigger an invite to an external SIP media server to push music on hold to the other leg

1.4  media_fetch_to_call(callid, leg[, nohold])

• Description: pushes the SDP of a new call (new INVITE message) in an existing proxied call’s leg, resulting in two way audio between. The other leg is put on hold.
• Parameters:
  • callid: the identifier of the callid to pull media from
  • leg: the leg that is going to be mixed: caller, callee, or both
  • nohold: do not put the other leg on hold
• Usage scenarios:
  • A call announcement comes from an external SIP media server

1.5  media_terminate([leg[, nohold]])

• Description: terminates an ongoing media session mixing, whether the media is only streamed, or a leg is mixed. If the other leg is involved in a different media mixing, this leg is put on hold.
• Parameters:
• leg: the leg for which to terminate the media mixing
• nohold - do not put on hold the leg
• Usage scenarios:
  • terminate a music on hold playback when the call has been resumed
  • stop recording or listening of a call

2.  MI primitives

2.1  media_send_from_call_to_uri

• Description: similar to the script function media_send_to_uri, but used through MI
• Extra parameters:
  • callid: the callid of the call that needs to push the media for

2.2  media_fetch_from_call_to_uri

• Description: similar to the script function media_fetch_from_uri, but used through MI
• Extra parameters:
  • callid: the callid of the call that needs to fetch media for