Media Communications Mesh

Tip

Full Documentation for Media Communications Mesh.

1. Introduction

Media Communications Mesh enables efficient, low-latency media transport for media microservices in Edge, Edge-to-Cloud, Private Cloud, and Public Cloud environments. The framework creates a secure, standards-based media data plane for inter-microservices communications using a new media proxy leveraging the Media Transport Library (MTL) and adds the necessary microservices control-plane communications infrastructure to implement any media control protocol.

1.1. Media Communications Mesh

• Framework Introduction: Media Communications Mesh is a framework designed for low-latency media transport. It caters specifically to Edge, Edge-to-Cloud, and Cloud environments, by connecting media microservices.
• Purpose: Its main role is to establish a secure data plane for media, allowing communication between microservices. This ensures media can be reliably transmitted across different environments.
• Technological Basis: The Media Transport Library (MTL) helps form the media data plane, and a control-plane communications infrastructure adds support for media control protocols.

✅ Key point: The main goal is to enable secure, fast, and standardized media communication between microservices, regardless of the environment (Edge or Cloud).

1.2. Media Proxy

• Core Functionality: The Media Proxy handles the routing and forwarding of media data, specifically audio and video streams, between mesh nodes.
• Low Latency & Efficiency: The focus is on ensuring low-latency and efficient usage of system resources, which is critical for real-time media applications.
• Service Mesh Role: It acts as a Data Plane component within a larger service mesh for media applications, utilizing MTL ST 2110 API, libfabric for RDMA API, memif shared memory APIs, and many more, to abstract the complexities involved in efficient media transport.

✅ Key point: Media Proxy handles the data transport layer of media streams, focusing on real-time efficiency and ensuring media routing between microservices in the mesh.

✅ More information about the Media Proxy component can be found in the media-proxy subdirectory.

1.3. SDK and FFmpeg Plugins

• Key Features: Zero Memory Copy, uses a zero-copy memory technique for ultra-low-latency media transfers between containers. This helps avoid data duplication, reducing time and resource overhead.
• Media Stream Compatibility: Supports compressed (like JPEG XS) and RAW uncompressed media formats, ensuring flexibility in how media is transported.
• Multiple Protocols: Works with SMPTE ST-2110 protocols, enhancing versatility in different media service setups.

✅ Key point: The system is optimized for zero-copy transmission with wide protocol compatibility, ensuring it can handle both compressed and uncompressed media streams efficiently.

✅ Detailed information about Media Communications Mesh SDK (further referred to as SDK) can be found in the sdk directory.

✅ Detailed information about FFmpeg with Media Communications Mesh plugin can be found in the ffmpeg-plugin directory.

2. Getting Started

2.1. Basic Build and Installation

2.1.1. Prerequisites

• Linux server (Intel Xeon processor recommended, e.g., Sapphire Rapids).
• Network Interface Card (NIC) compatible with DPDK (e.g., Intel Ethernet Controller E810-C).
• (Recommended) Update NIC drivers and firmware. For more information and latest drivers, see Support.

2.1.2. Steps

1. Clone the repository

   git clone https://github.com/OpenVisualCloud/Media-Communications-Mesh.git

2. Navigate to the Media-Communications-Mesh directory

   cd Media-Communications-Mesh

3. Install Dependencies, choose between OPTION A or OPTION B.

   • OPTION A: Use environment preparation scripts. The scripts were tested under environments with Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, CentOS Stream8, and CentOS Stream9, installed alongside 5.15 kernel. To use this option run the following commands:

     sudo ./scripts/setup_ice_irdma.sh

     and then

     sudo ./scripts/setup_build_env.sh

     Reboot the machine after the scripts are executed.

   • OPTION B: The following method is universal and should work for most Linux OS distributions.

     • XDP-tools with eBpf: Follow the simple guide XDP-tools for installation instructions.

     • MTL: Follow the MTL setup guide for installation instructions.

     • E810 driver: Follow the MTL NIC setup guide for installation instructions.

     • gRPC: Refer to the gRPC documentation for installation instructions.

     • Install required packages:

       • Ubuntu/Debian

         sudo apt-get update
         sudo apt-get install libbsd-dev cmake make rdma-core libibverbs-dev librdmacm-dev dracut

       • CentOS Stream

         sudo yum install -y libbsd-devel cmake make rdma-core libibverbs-devel librdmacm-devel dracut

     • Install the irdma driver and libfabric:

       ./scripts/setup_rdma_env.sh install

       More information about libfabric installation can be found in Building and installing libfabric from source.

     • Reboot

4. Build the Media Proxy binary

   To build Media Communications Mesh and make SDK available for development, run:

   ./build.sh

   By following these instructions, you'll be able to perform the basic build and installation of the Media Communications Mesh application.

2.2. Basic Usage – Standalone

The program "media_proxy" and SDK library will be installed on the system after the successful execution of build.sh script. To run Media Proxy, execute the following command:

media_proxy

which should result in:

INFO: TCP Server listening on 0.0.0.0:8002
INFO: gRPC Server listening on 0.0.0.0:8001

This will start the Media Proxy in blocking mode and confirm that the build was successful. To close it, press Ctrl+C.

2.3. Build for Docker

2.3.1. Prerequisites

• Linux server (Intel Xeon processor recommended, e.g., Sapphire Rapids).
• Network Interface Card (NIC) compatible with DPDK (e.g., Intel Ethernet Controller E810-C).
• (Recommended) Update NIC drivers and firmware. For more information and latest drivers, see Support.
• Docker engine (recommended with Buildx toolkit) configured and installed.

2.3.2. Build Docker Images

1. Clone the repository

   git clone https://github.com/OpenVisualCloud/Media-Communications-Mesh.git

2. Navigate to the Media-Communications-Mesh directory

   cd Media-Communications-Mesh

3. Build Docker images

   [!WARNING] Depending on your Docker installation, this step may require being run as root.

   Run the command below from the root directory of the repository to build all of the Dockerfiles:

   ./build_docker.sh

2.4. Basic Usage – Docker

After running the build_docker.sh the following Docker images will be available in the current Docker context if the script runs successfully:

• mcm/sample-app:latest
• mcm/media-proxy:latest
• mcm/ffmpeg:latest
• mcm/ffmpeg:6.1-latest

Media Proxy can be run inside a container now. To check it, execute the following command:

docker run --privileged -it -v /var/run/mcm:/run/mcm -v /dev/hugepages:/dev/hugepages mcm/media-proxy:latest

which should result in:

INFO: TCP Server listening on 0.0.0.0:8002
INFO: gRPC Server listening on 0.0.0.0:8001

This will start the Media Proxy as a container and confirm that the build was successful. To close it, press Ctrl+C.

2.5. Parameters and Ports

Running the Media Proxy with:

media_proxy

should result in:

INFO: TCP Server listening on 0.0.0.0:8002
INFO: gRPC Server listening on 0.0.0.0:8001

This will start Media Proxy with two ports opened to listen for control messages:

• gRPC port (default 8001) is for service mesh control plane connection.
• TCP port (default 8002) is for the connection with SDK.

To get the full list of all supported parameters, use the -h flag:

media_proxy -h

which should print the usage information:

Usage: media_proxy [OPTION]
-h, --help              Print this help and exit.
-d, --dev=dev_port      PCI device port (defaults: 0000:31:00.0).
-i, --ip=ip_address     IP address for media data transportation (defaults: 192.168.96.1).
-g, --grpc=port_number  Port number gRPC controller (defaults: 8001).
-t, --tcp=port_number   Port number for TCP socket controller (defaults: 8002).

3. Known Issues

• There is a bug with the default docker.io package installation (version 20.10.25-0ubuntu1~22.04.2) with Ubuntu 22.04.3 LTS. The USER command and chown command do not work as expected. It is preferred to install the docker-ce package, following an instruction from Docker Docs.

• The Authentication function of the Media Proxy interfaces is currently missing. This feature is still under development, and the current implementation is weak in defending against network attacks.

4. Support

If you encounter any issues or need assistance, there are several ways to seek support:

• Update NIC Firmware and Drivers: Check for your NIC firmware and/or drivers update: Intel® Ethernet Linux Driver Repositories.

• Project Documents: Search for solutions in the project documents.

• Discussions: Ask questions and seek help in the Discussions section on the project's GitHub page.

• Issue Submission: Report bugs and specific issues by submitting them on the Issues page of the project's GitHub repository.

Before submitting an issue, please check the existing documentation and discussions to avoid duplication and streamline the support process.

We are here to help, so don't hesitate to reach out if you need assistance.

5. Note

This project is under development. All source code and features on the main branch are shared for the purpose of testing or evaluation, and not production ready.