Using the ESUB-XF Subtitle Protocol

FAB Subtitler BCAST/XCD (starting from version 11.14) can receive live subtitles over TCP over the ESUB-XF protocol. The ESUB-XF protocol has many advantages. Only a few are listed below:

  • The description of the ESUB-XF protocol is available publicly here: https://www.fab-online.com/pdf/ESUB-XF.pdf
  • The protocol can be used universally to transport any type of subtitles (open subtitles, teletext subtitles, DVB subtitles, internet live streaming subtitles, …) so that colors, italic text and underlined text will be transported correctly.
  • The generation of the XML format containing the subtitle is very easy and well described in the ESUB-XF document

Practically the usage of the ESUB-XF protocol to send subtitles from FAB Subtitler LIVE to FAB Subtitler BCAST/XCD means that:

  • when FAB Subtitler LIVE is sending teletext subtitles it is assured that all teletext properties will be transported and the subtitle will appear on the receiver (teletext decoder) the same way as it is displayed in FAB Subtitler LIVE (this includes position, single/double text height, text and background color).
  • when FAB Subtitler LIVE is sending bitmap subtitles it is assured that all subtitle properties (position, underline, italic, text color) will be transported and the subtitle shall appear on the receiver (i.e. DVB subtitles, internet streaming subtitles) the same way as it is displayed in FAB Subtitler LIVE.

Configuring FAB Subtitler BCAST to receive subtitles over TCP using ESUB-XF protocol

  • In FAB Subtitler BCAST/XCD Options enable “Accept incoming subtitle connections” and click on “Protocol settings”

  • Continue with configuring “Protocols / Settings”

  • Define one or two TCP ports on which subtitles will be received. Multiple clients can send subtitles to the same TCP port at the same time.

  • You can define a list of IP addresses and make sure that FAB Subtitler BCAST/XCD will reject any connections that are not coming from the defined IP addresses.

  • The ESUB-XF protocol also supports logins using Username and Password. You can define the list of users by clicking on “Access restrictions”

  • When using multiple languages it is necessary to define the ESUB-XF language code that will be used for each language configured in FAB Subtitler BCAST/XCD in Options / Special / Languages

Configuring FAB Subtitler LIVE to transmit subtitles over TCP using ESUB-XF protocol

  • In FAB Subtitler LIVE Options add a ESUB-XF TCP connection

  • Enter the IP Address of FAB Subtitler BCAST/XCD, username, password.

  • The language code and name are used within the ESUB-XF protocol and they are important when FAB Subtitler BCAST/XCD is used to transmit subtitles for multiple languages. The same 3 letter language code must be defined for the language in FAB Subtitler BCAST/XCD language settings when multiple languages are used.

  • When “Display all subtitles transmitted by the destination” is selected then FAB Subtitler BCAST/XCD will send all transmitted subtitles (from all sources) back to FAB Subtitler LIVE which will display them in the top right corner of the application as seen below:

  • When “Do not report errors to connected clients” in FAB Subtitler BCAST is NOT checked then FAB Subtitler LIVE will report any transmission errors of FAB Subtitler BCAST directly on the screen.

Configuration of FAB Subtitler BCAST/XCD for reception of subtitles over ESUB-XF HTTP REST protocol

FAB Subtitler BCAST/XCD offers a HTTP REST API to receive subtitles over network.

  • Enable the Web server

  • Enable “Accept incoming network connections” and then click on Protocols / Settings

  • Enable HTTP REST API for ESUB-XF

Note that the users defined for the ESUB-XF TCP connections do not apply because the REST API authorization is used for all REST API functions.

Transmitting subtitles using the ESUB-XF HTTP REST protocol

The following URL is available to receive live subtitles:

HTTP POST ip_of_fabsubtitler_bcast_xcd:port/livesubtitling/esub-xf/displaysubtitle?sid=mycomputername

The HEADER must contain: “Content-Type: application/xml”

The BODY must contain the subtitle in XML format.

The following is an example of the HTTP POST request that sends a “send subtitle” to FAB Subtitler BCAST/XCD:

<?xml version="1.0" encoding="UTF-8"?>
<esub-xf xmlns="urn:esub-xf" framerate="25" timebase="msec">
  <subtitlelist language="eng" type="hardofhearing">
    <subtitle>
      <hregion>
        <line>First three words.</line>
        <line>Seconds line four words.</line>
      </hregion>
    </subtitle>
  </subtitlelist>
</esub-xf>

You can use the following command line with “curl” to HTTP POST the XML data:

curl -k -H "Content-Type: application/xml" http://127.0.0.1:8080/livesubtitling/esub-xf/displaysubtitle?sid=PCName -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><esub-xf xmlns=\"urn:esub-xf\" framerate=\"25\" timebase=\"msec\"><subtitlelist language=\"eng\" type=\"hardofhearing\"><subtitle><hregion><line>First three words.</line><line>Second line four words.</line></hregion></subtitle></subtitlelist></esub-xf>"

The following is an example of the HTTP POST request that sends a" delete subtitle" to FAB Subtitler BCAST/XCD:

<?xml version="1.0" encoding="UTF-8"?>
<esub-xf xmlns="urn:esub-xf" framerate="25" timebase="msec">
  <subtitlelist language="eng" type="hardofhearing">
    <subtitle />
  </subtitlelist>
</esub-xf>

You can use the following command line with “curl” to HTTP POST the XML data:

curl -k -H "Content-Type: application/xml" http://127.0.0.1:8080/livesubtitling/esub-xf/displaysubtitle?sid=PCName -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><esub-xf xmlns=\"urn:esub-xf\" framerate=\"25\" timebase=\"msec\"><subtitlelist language=\"eng\" type=\"hardofhearing\"><subtitle /></subtitlelist></esub-xf>"

It is necessary to indicate to FAB Subtitler BCAST/XCD that the transmission of subtitles is finished at the end of the program by sending the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<esub-xf xmlns="urn:esub-xf" framerate="25" timebase="msec">
  <subtitlelist language="eng" type="hardofhearing" />
</esub-xf>

You can use the following command line with “curl” to HTTP POST the XML data:

curl -k -H "Content-Type: application/xml" http://127.0.0.1:8080/livesubtitling/esub-xf/displaysubtitle?sid=PCName -d "<?xml version=\"1.0\" encoding=\"UTF-8\"?><esub-xf xmlns=\"urn:esub-xf\" framerate=\"25\" timebase=\"msec\"><subtitlelist language=\"eng\" type=\"hardofhearing\" /></esub-xf>"

This page was last updated on 2023-08-02