|
| 1 | +# NMOS GStreamer Plugins |
| 2 | + |
| 3 | +This repository contains GStreamer plugins that integrate AMWA NMOS functionality into your pipelines. |
| 4 | +Specifically, it provides an **NMOS Audio Receiver** (`nmosaudioreceiver`), **NMOS Video Receiver** (`nmosvideoreceiver`), and **NMOS Sender** (`nmossender`) that can dynamically that can receive and send ST2110 audio/video streams configured by the NMOS control panel. |
| 5 | + |
| 6 | +## Table of Contents |
| 7 | + |
| 8 | +## Table of Contents |
| 9 | + |
| 10 | +1. [Overview](#overview) |
| 11 | +2. [Building from Source](#building-from-source) |
| 12 | +3. [Installing the Plugin](#installing-the-plugin) |
| 13 | + - [Installing via Script](#option-1-installing-via-script) |
| 14 | + - [Installing Manually](#option-2-installing-manually) |
| 15 | + - [Environment Variable](#option-3-environment-variable) |
| 16 | + - [Verifying Installation](#verifying-the-installation) |
| 17 | +4. [Using the Plugin](#using-the-plugin) |
| 18 | + - [Inspecting the Plugin](#inspecting-the-plugin) |
| 19 | + - [Example Pipelines](#example-pipelines) |
| 20 | + - [NMOS Interface](#nmos-interface) |
| 21 | +5. [Notes and Troubleshooting](#notes-and-troubleshooting) |
| 22 | +6. [License](#license) |
| 23 | + |
| 24 | + |
| 25 | +--- |
| 26 | + |
| 27 | +## Overview |
| 28 | + |
| 29 | +The **NMOS plugins** communicate with an NMOS registry (using the AMWA [IS-04](https://specs.amwa.tv/is-04/) and [IS-05](https://specs.amwa.tv/is-05/) APIs) to automatically register and control the NMOS resources that send/receive raw ST2110 video/audio streams. |
| 30 | + |
| 31 | +## Building from Source |
| 32 | + |
| 33 | +To build the plugin, follow the build steps in the [**README**](/) inside the root directory of this project. The binary files for the plugin will then be created in `/build/Release/plugins/`. |
| 34 | + |
| 35 | +## Installing the Plugin |
| 36 | + |
| 37 | +Once you've built the plugin, you need to install it so that GStreamer can detect and use it. |
| 38 | + |
| 39 | +### Option 1: Installing via Script |
| 40 | + |
| 41 | +To simplify installation, you can use the provided installation script. This script installs the NMOS GStreamer plugins system-wide. |
| 42 | + |
| 43 | +Run the following command: |
| 44 | +```bash |
| 45 | +./scripts/install_custom_gstreamer_plugins.sh |
| 46 | +``` |
| 47 | + |
| 48 | +If the script is in a different directory, provide the path to your compiled plugins: |
| 49 | +```bash |
| 50 | +./scripts/install_custom_gstreamer_plugins.sh /path/to/your/plugins |
| 51 | +``` |
| 52 | +By default, the script assumes that the compiled plugins are located in: |
| 53 | +```bash |
| 54 | +../build/Release/plugins/ |
| 55 | +``` |
| 56 | +**Removing the NMOS Plugins** |
| 57 | + |
| 58 | +If you want to remove the NMOS plugins, run: |
| 59 | +```bash |
| 60 | +./scripts/install_custom_gstreamer_plugins.sh -r |
| 61 | +``` |
| 62 | +or |
| 63 | +```bash |
| 64 | +./scripts/install_custom_gstreamer_plugins.sh --remove |
| 65 | +``` |
| 66 | +This will delete nmossender, nmosvideoreceiver, and nmosaudioreceiver from the system. |
| 67 | + |
| 68 | +### Option 2: Installing Manually |
| 69 | + |
| 70 | +If you prefer a manual installation, follow these steps: |
| 71 | +1. **Locate Your Compiled Plugins** |
| 72 | + |
| 73 | +After building the project, the compiled .so (Linux), .dylib (macOS), or .dll (Windows) files will be in: |
| 74 | +``` |
| 75 | +/build/Release/plugins/ |
| 76 | +``` |
| 77 | + |
| 78 | +2. **Copy the Plugins to a GStreamer Plugin Directory** |
| 79 | + |
| 80 | +Copy the plugins to the GStreamer plugins folder. |
| 81 | +By default it should be ``/usr/lib/x86_64-linux-gnu/gstreamer-1.0`` for Linux. |
| 82 | + |
| 83 | +### Option 3: Environment Variable |
| 84 | + |
| 85 | +The last option for the plugin usage envolves setting environment variable `GST_PLUGIN_PATH` to the directory where the binary files are saved. This way for the current shell session GStreamer will also look for plugins in the specified path. Choosing this option will require the setting of the variable everytime a new session is created. |
| 86 | + |
| 87 | +i.e. |
| 88 | + |
| 89 | +```bash |
| 90 | +export GST_PLUGIN_PATH=/home/gst-plugins/ |
| 91 | +``` |
| 92 | + |
| 93 | +### Verifying the installation |
| 94 | + |
| 95 | +Check if GStreamer recognizes the plugins: |
| 96 | +```bash |
| 97 | +gst-inspect-1.0 | grep "nmos" |
| 98 | +``` |
| 99 | +If the installation was successful, you should see output similar to: |
| 100 | +``` |
| 101 | +nmossender: nmossender: NMOS Sender |
| 102 | +nmosvideoreceiver: nmosvideoreceiver: NMOS Video Receiver |
| 103 | +nmosaudioreceiver: nmosaudioreceiver: NMOS Audio Receiver |
| 104 | +``` |
| 105 | + |
| 106 | +## Using the Plugin |
| 107 | + |
| 108 | +### Inspecting the Plugin |
| 109 | + |
| 110 | +When using these plugins, you can inspect them along with all the properties you can change, capabilities, and info with the following command: |
| 111 | + |
| 112 | +```bash |
| 113 | +gst-inspect-1.0 nmos(sender/videoreceiver/audioreceiver) |
| 114 | +``` |
| 115 | + |
| 116 | +Some of the more important properties to change are as follows: |
| 117 | + |
| 118 | +| Property | Description | |
| 119 | +|------------------------------|-----------------------------------------------------------| |
| 120 | +| `node-id` | NMOS Node ID (UUID) | |
| 121 | +| `node-config-file-location` | Path to the node configuration JSON file (String) | |
| 122 | +| `device-id` | NMOS Device ID (UUID) | |
| 123 | +| `device-label` | A label for the NMOS Device (String) | |
| 124 | +| `device-description` | A description of the NMOS Device (String) | |
| 125 | +| `receiver-id` | NMOS Receiver ID (UUID) | |
| 126 | +| `receiver-label` | A label for the NMOS Receiver (String) | |
| 127 | +| `receiver-description` | A description of the NMOS Receiver (String) | |
| 128 | +| `destination-address` | IP address for the outgoing/incoming RTP stream (String) | |
| 129 | + |
| 130 | +**Important Note:** Currently, the node fields for the NMOS interface connection aren't configurable by properties but instead by a JSON file. An example can be found at `/cpp/demos/config/`. |
| 131 | + |
| 132 | +### Example Pipelines |
| 133 | +----- |
| 134 | +#### Sender (Audio): |
| 135 | +```bash |
| 136 | +gst-launch-1.0 audiotestsrc is-live=true wave=square ! audio/x-raw, format=S24BE, rate=48000, channels=2, layout=interleaved ! nmossender destination-address="192.168.1.1" destination-port=5004 |
| 137 | +``` |
| 138 | + |
| 139 | +#### Audio Receiver: |
| 140 | +```bash |
| 141 | +gst-launch-1.0 -v nmosaudioreceiver destination-address="192.168.1.1" receiver-id="9dd4cb3e-7d28-411d-9939-b8e439bd8c2a" ! queue ! audioconvert ! wavescope ! ximagesink sync=false |
| 142 | +``` |
| 143 | +----- |
| 144 | + |
| 145 | +#### Sender (Video): |
| 146 | +```bash |
| 147 | +gst-launch-1.0 videotestsrc is-live=true timestamp-offset=1 pattern=ball ! videoconvert ! "video/x-raw, format=UYVP, sampling=YCbCr-4:2:2, width=460, height=240, clock-rate=9000, framerate=50/1" ! nmossender destination-address="192.168.1.1" source-address="192.168.1.1" destination-port=9999 |
| 148 | +``` |
| 149 | +#### Video Receiver: |
| 150 | +```bash |
| 151 | +gst-launch-1.0 -v nmosvideoreceiver destination-address="192.168.1.1" receiver-id="9dd4cb3e-7d28-411d-9939-b8e439bd8c2a" ! queue ! videoconvert ! autovideosink sync=false |
| 152 | +``` |
| 153 | +----- |
| 154 | +### NMOS Interface |
| 155 | + |
| 156 | +The NMOS Interface allows users to manage senders and receivers through a graphical user interface. It provides an overview of active streams, transport methods, and detailed configurations. |
| 157 | + |
| 158 | +The NMOS page can be accessed through the following link ```http://localhost:8010/admin/``` |
| 159 | + |
| 160 | +- **Senders Management**: Displays active senders, transport type (e.g., RTP Multicast), and allows toggling activation. |
| 161 | +- **Receivers Management**: Lists available receivers, their bindings, supported media formats, and current connections. |
| 162 | +- **Detailed View**: Clicking on a node, device, sender or receiver provides detailed configuration options, including transport settings and associated flows. |
| 163 | +- **Connection Setup**: Users can establish connections between senders and receivers through a simple UI inside the receiver page, where they can freely connect and disconnect them. |
| 164 | + |
| 165 | +Note: When changing the parameters inside the connect tab, be sure to activate the activation mode ```activate_immediate``` if you want to change the connection dynamically. |
| 166 | + |
| 167 | +## Notes and Troubleshooting |
| 168 | + |
| 169 | +- **State Management:** The plugin automatically transitions to PLAYING when valid SDP data is received. If the receiver is disabled from the NMOS registry side, the pipeline tears down its internal elements. |
| 170 | +- **Flush and Dynamic Reconfiguration:** If you dynamically change streams at runtime (e.g., the NMOS registry activates a new source), the plugin will remove old elements and construct new ones on the fly without restarting the entire pipeline. |
| 171 | +- **Verbose Debug:** If you need to see more logs, you can enable GStreamer debug categories: |
| 172 | + |
| 173 | +```bash |
| 174 | +GST_DEBUG=nmosaudioreceiver:5 gst-launch-1.0 nmosaudioreceiver ... |
| 175 | +``` |
| 176 | + |
| 177 | +### Dependencies |
| 178 | + |
| 179 | +- GStreamer (1.18+ recommended) |
| 180 | + |
| 181 | +## License |
| 182 | + |
| 183 | +This project is licensed under the Apache 2.0 License. |
| 184 | +Please see the LICENSE file on the root directory for more details. |
0 commit comments