media gateway developer guide - Genetec/DAP GitHub Wiki

The Media Gateway Role is a core component of Security Center that exposes live and playback video streams to external applications using standard RTSP URLs. It acts as a bridge between Security Center's video management and third-party systems, enabling secure, scalable, and standards-based video access.

The Media Gateway consists of two main components:

• Media Gateway Role: Manages Media Gateway Agents across one or more servers and handles load balancing of stream requests.
• Media Gateway Agents: Execute on assigned servers and handle the actual RTSP connections from external applications.

The Media Gateway follows the RFC 2326 standard for RTSP protocol implementation.

The Media Gateway requires a valid Security Center license with the "Number of RTSP streams" option. This license determines the maximum number of concurrent RTSP streams that can be served.

• Multiple Role Instances (Security Center 5.10+): Starting with Security Center 5.10, it is possible to create more than one Media Gateway Role within the same system, including on the same server. Each Media Gateway Role must be configured to use unique ports or application paths to avoid conflicts. This allows for flexible deployment scenarios, such as segregating access for different network segments or use cases.
• Multi-Server Support: The Role can be assigned to multiple servers for load balancing and redundancy.
• Default Port: The default RTSP port is 654 (different from the standard Media Router port 554). This can be configured in the Config Tool.

The URI format used for accessing live or playback streams via the Media Gateway is structured as follows:

rtsp://<username>:<password>@<authority>:<port>/<cameraId>/<stream>?<parameters>

• username: (Optional) Security Center user credential.
• password: (Optional) Password for the username. For RTSP connections, the Media Gateway role can be configured with explicit passwords for Security Center users.
• authority: The Media Gateway server IP address or hostname.
• port: The port number configured for the Media Gateway (default: 654).
• cameraId: The GUID (Global Unique Identifier) of the camera.
• stream: Specifies the stream type: live, playback, or any other configured streams (remote, highres, lowres).
• parameters: Optional. Used for specifying playback options such as time range.

For live streaming, the URI does not require parameters:

rtsp://<authority>/<cameraId>/live

rtsp://192.168.1.10:654/00000001-0000-babe-0000-00408ca1eb95/live

Playback allows you to retrieve recorded video streams for a specific time range or from a specific start time.

If no range or Range is provided, playback defaults to the last 5 minutes of recorded video.

• Playback Range: The playback start time can be specified in two supported ways:

  • As a URL Parameter (start time only): The range query parameter supports an ISO 8601 format without the clock= prefix.

    rtsp://<authority>/<cameraId>/playback?range=YYYY-MM-DDTHH:MM:SS  
    

    Example:

    rtsp://10.200.78.109:654/00000001-0000-babe-0000-df7434997b3b/playback?range=2025-06-17T04:17:00  
    

  • As a Request Header (start and optional end time): For full control over the playback range, use the Range header in the RTSP PLAY request:

    Range: clock=YYYYMMDDTHHMMSSZ-YYYYMMDDTHHMMSSZ  
    

    Example:

    Range: clock=20250617T041700Z-20250617T042000Z  
    

Note: The URL-based range parameter accepts only a single start time in YYYY-MM-DDTHH:MM:SS format. For specifying a full-time range (start and end), use the Range header instead.

• Default Playback of the Last Five Minutes

  rtsp://<authority>/<cameraId>/playback  
  

• Playback from a Specific Time

  rtsp://<authority>/<cameraId>/playback?range=<start>  
  

PLAY rtsp://192.168.1.10:654/00000001-0000-babe-0000-00408ca1eb95/playback RTSP/1.0
CSeq: 3
Session: 12345678
Range: clock=20211208T083000Z-20211208T084000Z

Some cameras support multiple video streams with different resolutions or purposes. The availability of these streams depends on the camera model and its configuration in Security Center:

• Remote Stream:

  rtsp://<authority>/<cameraId>/remote
  

• High Resolution Stream (HighRes):

  rtsp://<authority>/<cameraId>/highres
  

• Low Resolution Stream (LowRes):

  rtsp://<authority>/<cameraId>/lowres
  

The Media Gateway can be configured using the MediaGateway.gconfig file located in:

C:\Program Files (x86)\Genetec Security Center 5.X\ConfigurationFiles\

If this file does not exist, create it manually. After making changes to the configuration file, you must deactivate and reactivate the Media Gateway Role from the Config Tool for the changes to take effect.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <MediaGateway
    RelativeSequenceLength="600"
    MaximumLiveSessionCount="50"
    MaximumPlaybackSessionCount="50"
    DisableLoadBalancing="false"
    UpperUdpPortBound="6900" />
</configuration>

Increase Playback Duration and Set Session Limits:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <MediaGateway
    RelativeSequenceLength="600"
    MaximumLiveSessionCount="100"
    MaximumPlaybackSessionCount="50" />
</configuration>

Expand UDP Port Range for High-Volume Deployments:

The default UDP port range (6000-6500) supports approximately 500 concurrent UDP connections. For deployments requiring more connections, increase the upper bound:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <MediaGateway UpperUdpPortBound="6900" />
</configuration>

The Scale header in RTSP controls the playback speed of the media stream.

* Non-key frames will be removed from the stream.

Important Notes:

• All reverse playback is key-frame only.
• Forward speeds of 6x and above are key-frame only.
• If an unsupported scale value is requested, the Media Gateway automatically adjusts it to the nearest supported value.
• When using a negative scale with a Range, playback starts at the end of the range. Without a Range, reverse playback will return only the first frame and stop.
• Recordings with extremely low frame rates (e.g., one frame per minute) cannot be played back.

PLAY rtsp://192.168.1.10:654/00000001-0000-babe-0000-00408ca1eb95/playback?range=2021-12-08T08:30:00 RTSP/1.0
CSeq: 3
Session: 12345678
Scale: 2

The Media Gateway supports multicast streaming but does not allow clients to specify multicast addresses. Instead, the Media Gateway server assigns the multicast address based on its configuration.

The Media Gateway optionally supports authentication. When enabled, credentials are required to stream video.

• User Credentials: The username corresponds to a Security Center user. The Media Gateway role can define a password for that user explicitly, which may differ from their Security Center password. Authentication uses the RTSP digest mechanism.
• Allowed Users: The user must be added to the Media Gateway role's allowed user list in the Config Tool.

RTSPS provides secure, encrypted RTSP connections using TLS.

• User Credentials: RTSPS connections require Security Center credentials (username and password). Unlike RTSP, custom Media Gateway passwords are not used.
• Privilege Requirement: Users must have the "Log On Using SDK" privilege.
• Encryption: RTSPS provides TLS encryption for secure transmission.
• Protocol: Use rtsps:// instead of rtsp:// in the connection URI.

The Media Gateway is able to load balance the stream requests through its different agents. For this to work, you need to assign two or more servers to the Media Gateway Role under the Resources tab.

Load balancing is automatic and based on current stream count. Each new connection is directed to the Agent with the fewest active streams. Redirection only occurs when Agents have uneven load.

For live streams, the Media Gateway directs new connections to an Agent that is already serving the same camera stream when possible, avoiding redundant stream ingestion.

Redirection is transparent to most RTSP clients. The Media Gateway handles the distribution of connections across Agents without requiring special client-side implementation.

When an Agent/server fails:

1. The Media Gateway Role stops redirecting new connections to the failed Agent.
2. Existing streams on the failed Agent are interrupted; clients must reconnect.
3. When clients reconnect, the Media Gateway redirects them to an available Agent.
4. When the failed Agent comes back online, the Media Gateway reintegrates it into the load balancing pool for new connections.

For applications that need to connect to a specific Media Gateway Agent (for example, to maintain session affinity or for testing purposes), you can bypass load balancing in two ways:

1. Add URL Parameter: Add ?redirected=true to the RTSP URL to prevent the connection from being redirected.

   rtsp://<authority>/<cameraId>/live?redirected=true
   

2. Disable Load Balancing System-Wide: Create or edit the MediaGateway.gconfig file and add:

   <?xml version="1.0" encoding="utf-8"?>
   <configuration>
     <MediaGateway DisableLoadBalancing="true" />
   </configuration>

   After modifying the configuration, restart the Media Gateway Role from the Config Tool.

The Media Gateway delivers compressed video directly from Security Center to the RTSP client in its original format. The format depends on the camera or video stream configuration in Security Center. Supported formats are:

• H.264 (AVC)
• H.265 (HEVC)
• MJPEG
• AV1 (Security Center 5.13.3.0 and later)

The third-party RTSP client is responsible for decoding the video stream. The client must support the codec configured on the camera in Security Center. If the client does not support the codec, reconfigure the camera stream to use a compatible codec.

The Media Gateway does not transcode video streams for third-party RTSP clients. Transcoding requires significant computational resources, so the Media Gateway prioritizes efficient delivery of the original compressed stream to minimize latency. RTSP clients always receive the stream in the codec configured on the camera in Security Center.

Transcoding is available for Security Center Web Client and mobile client connections through the HTTP and WebSocket interfaces. Third-party integrations using RTSP are not affected by transcoding configuration.