Plugin Development Guide

Previously we published this blog post to introduce the general structure of the plugin mechanism in the Ant Media Server. Also, we had a community event where we discussed the plugin mechanism with the Ant Media Server community. You can access it from youtube.

This blog post will be a guide to tell how you can create a plugin from scratch. But I strongly recommend starting a plugin development by taking our SamplePlugin Project as a basis.

Step 1: Creating Main Plugin Class

To create the Main Class for your plugin you should

• create your main plugin class in the io.antmedia.plugin package
• add the following annotation where the value would be the plugins bean name

  @Component(value="your_plugin_bean_name")

• implement ApplicationContextAware to get ApplicationContext
• implement IStreamListener to be informed for stream start/finish events

Step 2: Accessing Ant Media Server

Since main class implements ApplicationContextAware, at the creation of plugin, setApplicationContext(ApplicationContext applicationContext) method will be called. Using applicationContext parameter, you can access the AntMediaApplicationAdapter and other beans used in Ant Media Server. For example, you can get AntMediaApplicationAdapter and Vertx instances with the following snippet.

@Override
public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
  this.applicationContext = applicationContext;
  AntMediaApplicationAdapter app = getApplication();
  app.addStreamListener(this);
}

public AntMediaApplicationAdapter getApplication() {
  return ((IApplicationAdaptorFactory) applicationContext.getBean(AntMediaApplicationAdapter.BEAN_NAME)).getAppAdaptor();
}

Step 3: Register Plugin as a Stream Listener

To get stream start/finish events from Ant Media Server, you should register the plugin as a StreamListener. You should access AntMediaApplicationAdapter instance first and then register the plugin as a StreamListener. Here are the related lines in the example of Step 2.

AntMediaApplicationAdapter app = getApplication();
app.addStreamListener(this);

Step 4: Register Plugin as a Frame Listener or Packet Listener

To get encoded packets or decoded frames you should register the plugin as a PacketListener or FrameListener to the Ant Media Server. You should access AntMediaApplicationAdapter instance first and then register the plugin as a PacketListener or FrameListener as following. Please note that you don’t have to register both, most of time you will need only one of them.

public void register(String streamId) {
  AntMediaApplicationAdapter app = getApplication();
  app.addFrameListener(streamId, frameListener);
  app.addPacketListener(streamId, packetListener);
}

Step 5: Processing Frames

There are some points that you should pay attention to not to affect Ant Media Server operations. If the plugin will work on the frames, then you should do the following.

• Determine the plugin type. For plugin types please check this.
• If it is asynchronous or the last point then copy the frame and process it in a different thread to prevent the Ant Media Server blocking. In Ant Media Server, we are using Vertx thread pools for multi-threading. You can also use it in your plugins. In Step 2, we got the Vertx bean also.
• If it is synchronous then modify the incoming frame and process on it and return in the same thread. But the process duration is important. For real-time streaming, it should be less than the frame period.

Step 6: Creating Rest API (optional)

If you want to make your plugin accessible by a REST API, you can create a REST class in io.antmedia.rest package and add the following annotations to determine the path

@Component
@Path("/sample-plugin")

About Ant Media Server

Ant Media Server is a real-time streaming software that uses WebRTC technology to enable adaptive, ultra-low latency streaming with a latency of less than 0.5 seconds. Ant Media Server is both horizontally and vertically scalable. It may be used on-premises or in the cloud. Ant Media serves a diverse range of businesses and sectors, including education, gambling, broadcasting, auctioning, and surveillance, in more than 120 countries. For more information about Ant Media Server, please contact us. If you’re looking to build a streaming solution with adaptive bitrate streaming, ultra-low latency, and highly scalable features you can get started for free now.