Document toolboxDocument toolbox

Vidispine

Subtitles [VC 21.3 GEN]

Owned by Andreas Schmidt
Aug 31, 2021
4 min read

Vidispine supports adding subtitles to an item. They can then for example be exported to Final Cut. Subtitles can also be used with sequences and can be included in the video when a sequence is rendered.

Subtitle metadata fields and groups

To add subtitles to a Vidispine item, the metadata field group stl_subtitle must be used. The group should be placed within a timespan corresponding to the in- and out timecodes the subtitles should be displayed. Within this group, the following fields can be set:

  • stl_text. This sets the actual text which should be displayed. Multiple lines are delimited by a line feed character.

  • stl_justification. Determines the justification of multiple lines of text.

    left

    all lines are aligned to left border of text bounding box

    center

    all lines are aligned in center of text bounding box

    right

    all lines are aligned to right border of text bounding box

  • stl_xrelative. Horizontal position of base point relative to full video frame.

    0.0

    left border

    1.0

    right border

  • stl_yrelative. Vertical position of base point relative to full video frame.

    0.0

    top border

    1.0

    bottom border

  • stl_horizontalbase. Horizontal position of base point relative to text bounding box.

    0.0 (or left)

    base point is left border of bounding box.

    0.5 (or center)

    base point is center of bounding box.

    1.0 (or right)

    base point is right border of of bounding box.

  • stl_verticalbase. Vertical position of base point relative to text bounding box.

    0.0 (or top)

    base point is top border of of bounding box.

    0.5 (or middle)

    base point is middle of bounding box.

    1.0 (or bottom)

    base point is bottom border of bounding box.

  • stl_sizerelative. Height of font relative to full video frame.

  • stl_color. Color of text. Can be standard colors (red) or hexadecimal (#ff0000).

  • stl_outline. Type of outline.

    (none)

    no outline

    bar

    rectangular outline

    stroke

    fat stroke around text

  • stl_outlinecolor. Color of outline.

  • stl_outlinesize. Size (margin) of outline.

  • stl_font. Font of subtitle.

    monospace

    fixed-width font (default)

    sans

    sans-serif font

    serif

    font with serifs

Example

  • stl_justification=left

  • stl_xrelative=0.9

  • stl_yrelative=0.5

  • stl_horizontalbase=right

  • stl_verticalbase=top

The subtitle language can be extracted from the .stl file itself or set using jobmetadata, key subtitleLanguage; jobmetadata has a higher priority.

Example

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <timespan start="10@PAL" end="100@25">
    <group>
      <name>stl_subtitle</name>
      <field><name>stl_justification</name><value>left</value></field>
      <field><name>stl_vertical</name><value>6</value></field>
      <field><name>stl_text</name><value>some text&#13;&#10;actually two lines</value></field>
    </group>
  </timespan>
</MetadataDocument>

Rendering subtitles in a sequence

If you have a sequence attached to an item in Vidispine the subtitle metadata can be included in the output file. To do this, you need to use a shape tag where <burnSubtitles>true</burnSubtitles> is set in the <video> element. Note that overlapping subtitle timespans are not allowed and will cause the render job to fail.

Example

Let’s say we have an item VX-811 which has a sequence attached to it, and the following metadata:

<MetadataDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  ...
  <timespan start="72140@PAL" end="72260@PAL">
    <group>
      <name>stl_subtitle</name>
      <field><name>stl_justification</name><value>center</value></field>
      <field><name>stl_text</name><value>No, I am your father.</value></field>
    </group>
  </timespan>
  <timespan start="72320@PAL" end="72490@PAL">
    <group>
      <name>stl_subtitle</name>
      <field><name>stl_justification</name><value>center</value></field>
      <field><name>stl_text</name><value>No... that's not true!&#13;&#10;That's impossible!</value></field>
    </group>
  </timespan>
  ...
</MetadataDocument>

And we have the following shape-tag called MP4_512_SUB:

<TranscodePresetDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <format>mp4</format>
  <audio>
    <codec>aac</codec>
    <bitrate>96000</bitrate>
  </audio>
  <video>
    <scaling>
      <width>512</width>
      <height>288</height>
    </scaling>
    <codec>h264</codec>
    <bitrate>2000000</bitrate>
    <framerate>
      <numerator>1</numerator>
      <denominator>25</denominator>
    </framerate>
    <burnSubtitles>true</burnSubtitles>
  </video>
</TranscodePresetDocument>

Then a render job is started using:

POST /item/VX-811/sequence/render?tag=MP4_512_SUB
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine"><jobId>VX-1436</jobId><user>admin</user><started>2013-03-08T13:02:15.654Z</started><status>READY</status><type>CONFORM</type><priority>MEDIUM</priority></JobDocument>

This will render the sequence and include any subtitle metadata as subtitles in the output video.

SCC support

To export subtitle metadata for an item in SCC format, use the SCC export resource.

GET /item/VX-56/metadata/export/scc
Scenarist_SCC V1.0

00:00:00:00  942c 942c 9420 9420 9470 9470 54e5 f8f4

00:00:10:00  942f 942f

00:00:20:00  942c 942c

TTML support

Subtitles for an item can also be retrieved in TTML format using Export to TTML.

GET /item/{id}/metadata/export/ttml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tt xmlns:ns2="http://www.w3.org/ns/ttml#styling" xmlns="http://www.w3.org/ns/ttml" xmlns:ns4="http://www.w3.org/ns/ttml#metadata" xmlns:ns3="urn:ebu:tt:style" xmlns:ns5="http://www.w3.org/ns/ttml#parameter" xmlns:ns6="urn:ebu:tt:metadata" ns5:frameRate="25" ns5:cellResolution="50 30" ns2:extent="704px 576px" xml:lang="en">
  <head>
    <metadata>
      <ns6:documentMetadata>
        <ns6:documentTargetAspectRatio>4:3</ns6:documentTargetAspectRatio>
        <ns6:documentTotalNumberOfSubtitles>11</ns6:documentTotalNumberOfSubtitles>
        <ns6:documentMaximumNumberOfDisplayableCharacterInAnyRow>40</ns6:documentMaximumNumberOfDisplayableCharacterInAnyRow>
        <ns6:documentStartOfProgramme>00:00:00:00</ns6:documentStartOfProgramme>
        <ns6:documentCountryOfOrigin>GB</ns6:documentCountryOfOrigin>
        <ns6:documentPublisher>Institut fuer Rundfunktechnik   </ns6:documentPublisher>
      </ns6:documentMetadata>
    </metadata>
    <styling>
      <style xml:id="textCenter" ns2:textAlign="center"/>
      <style xml:id="defaultStyle" ns2:fontFamily="monospaceSansSerif" ns2:fontSize="1c 1c" ns2:lineHeight="normal" ns2:textAlign="center" ns2:color="white" ns2:backgroundColor="transparent" ns2:fontStyle="normal" ns2:fontWeight="normal" ns2:textDecoration="none"/>
      <style xml:id="whiteOnblackDH" ns2:fontSize="1c 2c" ns2:color="white" ns2:backgroundColor="black"/>
    </styling>
    <layout>
      <region xml:id="bottom" ns2:origin="10% 10%" ns2:extent="80% 80%" ns2:displayAlign="after" ns2:padding="0c" ns2:writingMode="lrtb"/>
      <region xml:id="top" ns2:origin="10% 10%" ns2:extent="80% 80%" ns2:displayAlign="before" ns2:padding="0c" ns2:writingMode="lrtb"/>
    </layout>
  </head>
  <body>
    <div xml:id="SGN1" style="defaultStyle">
      <p region="top" style="textCenter" begin="00:00:00:00" end="00:00:02:10">
        <br/>
        <span style="whiteOnblackDH">two-line</span>
        <br/>
        <span style="whiteOnblackDH">top</span>
      </p>
      <p region="top" style="textCenter" begin="00:00:02:14" end="00:00:04:21">
        <br/>
        <span style="whiteOnblackDH">one-line top</span>
      </p>
      ...
    </div>
  </body>
</tt>