Media Gateway API

Use MediaFactory to obtain the service API instance and to build request payloads: 

import com.oracle.sdp.mgs.MediaFactory;
import com.oracle.sdp.mgs.api.MediaGatewayServiceApi;

MediaFactory factory = MediaFactory.getInstance();
MediaGatewayServiceApi api = factory.createMediaGatewayServiceApi();
The Media Gateway API supports the following operations:
  • Create a media session: createMediaSession(CreateMediaRequest req)

    This method returns the session ID and the state

  • Modify a media session: modifyMediaSession(String sessionId, ModifyMediaRequest req)
  • Deactivate a media session: deactivateMediaSession(String sessionId, MediaSessionActionRequest req)
  • Delete a media session: deleteMediaSession(String sessionId, MediaSessionActionRequest req)
  • Get media session status: getMediaSessionStatus(String sessionId)

Building a Create Media Request

A typical create request includes:

  • callId – SIP Call-ID (or another call correlation identifier). Used to generate a unique session identifier.
  • mediaSessionPurpose – The purpose or type of the media session (for example, external RTP streaming).
  • IngressMediaStream – This may include identifiers (e.g. streamId), OfferedSDP (media type, direction, connection, codecs), and optional metadata.
  • EgressMediaStream – This may include identifiers, a Connection (destination IP/port), egress source type (e.g. UDP), and optional codecs and metadata.

Use the MediaFactory builders to construct the request and related objects. 

CreateMediaRequest req = factory.createCreateMediaRequestBuilder()
    .callId(callId)
    .mediaSessionPurpose(MediaSessionPurpose.EXTERNAL_STREAM)
    .addIngressMediaStream(ingressStream)
    .addEgressMediaStream(egressStream)
    .build();

The ingress and egress streams are build from the following methods:

  • factory.createIngressMediaStreamBuilder()
  • factory.createEgressMediaStreamBuilder()

In addition, review the other factory methods createIdentifiersBuilder(), createOfferedSDPBuilder(), createConnectionBuilder(), and createCodecBuilder()

Table 18-1 Parameters for Create

Field Required Description
CallId Yes SIP Call-ID header; used to generate unique session ID.
MediaSessionPurpose Yes Purpose/type of the session.
Ingress MediaStreams Yes (if purpose ≠ CUSTOM) List of media streams feeding into the system.
Egress MediaStreams Yes (if purpose ≠ CUSTOM) List of media streams for outgoing media.
Custom Pipeline Yes (if purpose = CUSTOM) Optional GStreamer pipeline description (string) for custom media processing.
SessionMetadata Yes Optional free-form key-value pairs for custom tags, analytics, participant info.

Table 18-2 Ingress Media Streams

Field Required Description
identifiers Yes Stream identification.
ingressSourceType Yes Type of ingress stream.
OfferedSDP Yes Connection details, media type, direction, and offeredCodecList.
streamMetadata Optional Optional stream-specific metadata.

Table 18-3 Offered SDP

Field Required Description
mediaType Yes Type of media.
mediaDirection Optional Media direction.
connection Yes Connection details (MediaSourceIp, mediaSourcePort).
offeredCodecs Yes List of codecs offered by source.

Table 18-4 Egress Media Streams

Field Required Description
identifiers Yes Stream identification.
egressSourceType Yes Type of egress stream.
connection Yes Connection details (IP, port, URL, etc.).
outputCodecs Yes List of codecs expected by sink.
streamMetadata Optional Optional stream-specific metadata.

Table 18-5 Identifiers Object

Field Applies to Required Description
streamId Ingress and Egress Yes Unique stream identifier.
  • In ingress streams, the combination of call_id + stream_id must be unique.
  • In egress streams, streamId is set in outgoing RTP packets.
participantId Ingress No
  • participantId is present in EgressMediaStream only.
participantId Egress Yes
  • participantId is present in EgressMediaStream only.

Table 18-6 Connection Object

Field Required Description
mediaSourceIp Conditional Source IP address.
mediaSourcePort Conditional Source port.
destinationIp Conditional Egress IP.
destinationPort Conditional Egress port.

Table 18-7 Codec Object

Field Required Description
name Yes Codec name (for example, "PCMU", "PCM-16", "opus").
parameters Yes Codec-specific parameters.

Table 18-8 Codec Parameters Object

Field Required Description
rtpPayloadType Conditionally required RTP payload type for RTP streams.
samplingRate Yes Sample rate in Hz.
channelCount Yes Number of audio channels.
targetBitrate Optional Target bitrate in bps.
formatParams Optional Codec FMTP parameters (for example, "minptime=10;useinbandfec=1").
format Yes Audio formats (for example, "S16LE").

Table 18-9 Stream Metadata Fields

Field Applies to Required Description
description Ingress and Egress No Free text description or notes about this stream.
streamDirection Ingress No Set the stream direction.
streamDirection Egress Yes Set the stream direction.
custom Ingress and Egress No Free-form custom key-value pairs.

Table 18-10 Session Metadata Fields

Field Required Description
description No Free text description or notes about this stream.
sessionId Yes The session ID
custom No Free-form custom key-value pairs.

Building a Modify Media Request

A typical modify request includes stream modifications like add, update, or remove. Use the MediaFactory object to create builders.

ModifyMediaRequest req = factory.createModifyMediaRequestBuilder()
    .addIngressMediaStream(ingressStream) 
    .addEgressMediaStream(egressStream)   
    .build();

The ingress and egress streams are built from the following methods:

  • factory.createIngressMediaStreamBuilder()
  • factory.createEgressMediaStreamBuilder()

Also see the other factory methods like createOfferedSDPBuilder() or createCodecBuilder().

Table 18-11 Parameters for Modify

Field Required Description
ingressMediaStreams optional List of media streams feeding into the system
egressMediaStreams optional List of media streams for outgoing media
sessionMetadata optional Optional free-form key-value pairs for custom tags, analytics, participant info

Building a Delete Media Request

A typical delete request includes the Reason set to either 'delete' or 'bye'.

MediaSessionActionRequest deleteRequest = factory.createMediaSessionActionRequestBuilder()         
    .reason("delete")
    .build();

Table 18-12 Parameters for Delete

Field Required Description
reason optional Optional reason for deactivate (e.g., "call hold")

Updating Application State

The createMediaSession. modifyMediaSession, deleteMediaSession all return the MediaSessionUpsertResponse. This response tells you:
  • the media session identifier
  • the current session state (such as ACTIVE or ERROR)
  • optionally, the MediaSessionDetails that include information about connections and codecs.

You may use this information to update your application state.