Stamp Plugin

Add video overlays to live streams based on instructions received on its REST API

About Stamp

Stamp module for Ant Media Server allows adding a dynamic image and text overlays on top of live video streams controlled by REST API calls.

Highlights

If you want to display Custom User Interface or dynamically add video overlays with the help of Text, XML, CSV, and RSS files while live streaming, the Stamp module is just the right fit for your need.

You may accomplish a wide range of use cases; few of them may be used to decorate your live video stream with scores, stock prices, clock, and captions driven by REST API calls.

Features

  • Fully customizable text overlays with rich visual effects (shadow, color, font, wrapping, alignments)
  • Fading, scrolling effects
  • Dynamic tickers
  • Images (jpg, png, animated gif files, from URL or POSTed in)
  • Easy to use REST API ready to be controlled from the command line, scoring system, or your own system.

Testimonial : The stamp plugin was awarded first prize at the Real-Time Streaming Hackathon 2022, where it powered the live score overlays of a demo broadcast Klask board game match to illustrate its integration capabilities.

Getting Started:

Before Starting
You need to have an active Ant Media Server(AMS) license. You can subscribe through AWS and deploy AMS with just one click. Or directly subscribe to a self-hosted license on our website. Please contact us for details

Deployment

Download the ams-stamp-x.y.z.jar file from here and place it under the /usr/local/antmedia/plugins directory of your media server.

As Stamp module commercial plugin, and you purchased a license, then copy the license file into the /usr/local/antmedia/conf directory. If you don’t obtain a license file, the trial will start for a limited time.

Restart Ant Media Server using sudo systemctl restart antmedia.service

You should see the below messages when your Live application starts up:

22:42:06,506 [Loader:/LiveApp] INFO  i.a.AntMediaApplicationAdapter - LiveApp started
22:42:06,509 [Loader:/LiveApp] INFO  io.antmedia.plugin.StampPlugin - Stamp Plugin is starting in LiveApp
22:42:06,509 [Loader:/LiveApp] ERROR io.antmedia.plugin.StampPlugin - No Stamp license file found in default location conf so entering trial mode
22:42:06,509 [Loader:/LiveApp] INFO  io.antmedia.plugin.StampPlugin - Stamp version: 1.0.0 - License fingerprint: TRIAL-1
22:42:06,509 [Loader:/LiveApp] INFO  io.antmedia.plugin.StampPlugin - Stamp license owner: nobody
22:42:06,509 [Loader:/LiveApp] INFO  io.antmedia.plugin.StampPlugin - Stamp license expiration date: 2022.12.08

Open the configuration settings of LiveApp and turn on Adaptive Streaming, add at least one rendition:

Screenshot 2023 05 09 at 09.59.18

To secure the REST API of Stamp it is highly recommended to configure JWT token authentication based on this guide.

By default the LiveApp has the Enable IP Filter for RESTful API restriction turned on. If you wish to access the Stamp API from external servers, please turn this setting off or set the desired source IPs.

Publish a stream to LiveApp and verify that the logs contain these messages. You can publish the stream from vMix, OBS or just simply use ffmpeg from command line:

wget https://streamtoolbox.com/download/big_buck_bunny_720p_h264.mov
ffmpeg -re -i big_buck_bunny_720p_h264.mov -c copy -f flv rtmp://localhost:1935/LiveApp/bunny
22:42:20,111 [vert.x-worker-thread-25] INFO  io.antmedia.plugin.StampPlugin - Registering Stamp frame listener in stream myStream

You might see messages related to frame processing time, especially when the stream starts and the very first frames are modified. After an initial warmup these messages should go away if you are running with the right capacity server.

22:42:20,514 [vert.x-worker-thread-31] WARN  i.antmedia.plugin.stamp.StampEngine - Frame processing on myStream took 31ms which is above the 85.0% of the interval calculated from the 29.0 fps in LiveApp. If you see this message often, your server is struggling with the load.

Verify that you see a calibration grid and a welcome message when you play back your published stream:

Screenshot 2023 05 09 at 10.01.28

Send in an example API request from the command line:

curl --location --request POST 'http://localhost:5080/LiveApp/rest/stamp/instructions' \
--header 'Content-Type: application/json' \
--data-raw '{"id": "overlay-1","start":"now+1","duration": 30,"text":"Hello Stamp!",\
"style":{"color":"red","size":42},"position": {"x": 0.5, "y": 0.5, "anchor":"center-center"}}'

You should see the hello message showing up on the video stream shortly.

Screenshot 2023 05 09 at 10.02.51

Once you reached this point, it makes sense to turn off the calibration grid:

echo "stamp.calibrate.grid=false" | sudo tee /usr/local/antmedia/conf/stamp.conf
sudo systemctl restart antmedia.service

Using

Here is an illustration of API calls that can give you a kickstart.

Text in the middle of the screen with fade-in: 

Screenshot 2023 05 09 at 10.06.16

curl --location --request POST 'http://localhost:5080/LiveApp/rest/stamp/instructions'
 --header 'Content-Type: application/json' --data-raw '
{
    "id": "myText1",
    "start": "now",
    "duration": 120,
    "text": "Hello Stamp",
    "position": {"x": 0.5, "y": 0.5, "anchor": "center-center"},
    "style": {"font":"Verdana", "size":40, "style": "bold", "color": "yellow"},
    "transitionIn": {"type": "fade", "duration": 5},
    "shadow": {"radius": 3 }
}
'

Image downloaded from external URL:

Screenshot 2023 05 09 at 10.07.29

{
    "id": "img-1234",
    "start": "now+2",
    "duration": 30,
    "image": "https://streamtoolbox.com/images/streamtoolbox-white-transparent-logo.png",
    "position": {"x": 100, "y": 100, "anchor": "top-left"},
    "transitionIn": {"type": "fade", "duration": 5},
    "transitionOut": {"type": "fade", "duration": 5}
}

Ticker at the bottom of the screen:

Screenshot 2023 05 09 at 10.08.34

{
  "start": "now+1", "end": "2100.12.31 12:00:00",
  "text": "This is really breaking news here",
  "position": {"x": 0.5, "y": 0.9},
  "style": {"font":"Verdana", "size":62, "style": "bold", "color": "yellow"},
  "transitionIn": {"type":"ticker", "speed": 4}
}

Big clock in the top left corner:

Screenshot 2023 05 09 at 10.09.29

Support

Please contact StreemToolBox at help@streamtoolbox.com

Screenshots

Ready to Use Video Overlay Plugin