Adding text overlays using TORNADO and Overlay Templates

Adding text overlays using TORNADO and Overlay Templates

Adding text overlays to an image using TORNADO is accomplished by using the Overlays Template. You can refer to MT-TN-50 Overlay File Format Specification for details on the template format.

In this document we will use a template comprising of a Text element using a tag to capture the timecode of the source clip and Rich Text Markup to define the color and transparency of the text. The template will then be sent to TORNADO via it's REST API and saved to it's internal list for later retrieval. You can refer to the Overlays API reference for usage details.

The first step is to create the Overlay Template. This is a simple XML file that will be sent to TORNADO via it's Overlays REST API.

The following example shows the Overlay Template that will display the text TIMECODE 00:00:00:00 using the color red with a 50% alpha and that is bottom-left aligned relative to the composition's container and has a 5% horizontal position from the left and 5 % vertical position from the bottom:
  1. <?xml version="1.0" encoding="UTF-8" ?>
        <Text hpos="5" vpos="5" halign="left" valign="bottom">{\col(#ff000088) TIMECODE $Timecode$}</Text>

Once the template is defined, it can be sent as a payload using a POST request to the http://<ip_address>:<posrt_number>/overlays endpoint. If desired the template can be saved as an XML file and it's path can be passed to the overlay JSON parameter when the transcoding job is created.

The response to this request will contain the UUID as well as the overlay's XML file location on disk. The UUID will be later used to reference this template for usage in a transcoding job.
  1. {
        "uuid": "d4d3e88b-54df-4852-959d-9df6dd0c793a",
        "name": "",
        "filename": "C:\\Users\\Sebastian\\AppData\\Roaming/Marquise Technologies/mediabase/TORNADO/session/overlays/d4d3e88b-54df-4852-959d-9df6dd0c793a.xml"
Next, a transcoding job will be able to use the overlay template by using it's UUID as the value of the overlay JSON parameter. Alternatively, if the template was saved as an XML file then it's path can be used as the value of the overlay JSON parameter.
  1. {
        "context": "xcode",
        "input": "D:/MEDIA/Input/video.mp4",
        "output": "D:/MEDIA/Output/overlay_test.mp4",
        "preset": "D:/PRESETS/preset_mp4_8-baseline-15Mbit.xml",
        "overlay": "d4d3e88b-54df-4852-959d-9df6dd0c793a"
The response to the operation will contain the job details including the overlay parameter and it's value:
  1. {
        "uuid": "11870ae7-3bda-4cb5-89b3-129ef2ab5812",
        "priority": 0,
        "status": "queued",
        "requesttimestamp": "2022-07-01T13:14:54.569+00:00",
        "input": "D:/MEDIA/Input/video.mp4",
        "output": "D:/MEDIA/Output/overlay_test.mp4",
        "preset": "D:/PRESETS/preset_mp4_8-baseline-15Mbit.xml",
        "overlay": "d4d3e88b-54df-4852-959d-9df6dd0c793a",
        "context": "xcode"

    • Related Articles

    • TORNADO Integration Guide & API

      Access TORNADO User's Guide and API web pages : TORNADO_API_Reference TORNADO_BasicIntegration_Guide
    • Where can I find the DCI certificates ?

      The software certificate as well as the validation chain can be found in the following directory: \User\‎$yoursessionname‎$\AppData\Roaming\Marquise Technologies\certificates You need to show the hidden folders in your OS browser to be able to see ...
    • About Color range

      MIST supports both FULL and HEAD color ranges. FULL refers to the full color range data signal (0 -1023 values). HEAD (SMPTE) is about the TV legal levels (64-940 values) commonly used by the TV broadcasting system. The deliverable must always be ...
    • HDMI video output does not work on some formats

      Depending on the video I/O card used, some video formats (mostly UHD/4K) will prevent HDMI output when using a RGB 16bit pixel format. This issue is related to the lack of resources of the video I/O card. Please check your card manufacturer the ...
    • ISDCF Audio Channel Assignments

      The ISDCF has published a recommendation for assigning audio channels for SMPTE or Interop DCP.  You can find it using this link:  ISDCF-Doc4-Audio-channel-recommendations.pdf You can find additional technical details on their website: