Timecode

Transform supports SMPTE/EBU timecode as metadata attached to a video or audio stream.

Timecode may appear in multiple locations within a media container. For example timecode may be located in a separate track or embedded in the video stream as vertical blanking, ancillary or user data. Each timecode location is represented by a specific metadata type. See Metadata Types for a complete list of the supported timecode types.

Timecode Extraction

Use the detach operator to extract timecode time metadata from a video stream. Typically timecode is extracted from a specific location represented by the root metadata element type. If not specified the operator searches all root elements.

For example the following composition extracts timecode from the MPEG-2 GOP header.

input:
  container:
  - name: input
    video:
    - name: v1
      detach:
      - type: time
        root: gopt

{
  "input": {
    "container": [
      {
        "name": "input",
        "video": [
          {
            "name": "v1",
            "detach": [
              {
                "type": "time",
                "root": "gopt"
              }
            ]
          }
        ]
      }
    ]
  }
}

Timecode Insertion

Use the attach operator to insert timecode metadata into a video stream.

For example the following composition inserts MPEG-2 GOP timecode into a QuickTime timecode track. See the QuickTime Movie documentation for details on the TimeCodeMode property.

input:
  container:
  - name: input
    video:
    - name: v1
      detach:
      - type: time
        root: gopt
output:
  container:
  - type: 'mov '
    properties:
      TimeCodeMode: 1
    video:
    - route:
      - name: v1
      attach:
      - type: time
        root: movt

{
  "input": {
    "container": [
      {
        "name": "input",
        "video": [
          {
            "name": "v1",
            "detach": [
              {
                "type": "time",
                "root": "gopt"
              }
            ]
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "type": "mov ",
        "properties": {
          "TimeCodeMode": 1
        },
        "video": [
          {
            "route": [
              {
                "name": "v1"
              }
            ],
            "attach": [
              {
                "type": "time",
                "root": "movt"
              }
            ]
          }
        ]
      }
    ]
  }
}

Timecode Overlay

Use the overlay operator is used to display "burned-in" timecode. For example the following composition will overlay timecode from an MXF input to a QuickTime output.

---
input:
  container:
  - name: input
    video:
    - name: v1
      detach:
      - type: time
        root: mxfm
output:
  container:
  - type: 'mov '
    name: output
    video:
    - overlay:
      - name: v1
      - name: v1
        filter:
        - type: tcbm
          properties:
            TimeScale: 30000
            FrameDuration: 1001
            BitmapWidth: 250
            BitmapHeight: 50
            FontSize: 18
            StringForegroundColor: red
            RegionBackgroundColor: green
        - type: bmvc
          properties:
            TimeScale: 30000
            FrameDuration: 1001
      encode:
        type: h264
        properties:
          OutputFormat: avc1

{
  "input": {
    "container": [
      {
        "name": "input",
        "video": [
          {
            "name": "v1",
            "detach": [
              {
                "type": "time",
                "root": "mxfm"
              }
            ]
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "type": "mov ",
        "name": "output",
        "video": [
          {
            "overlay": [
              {
                "name": "v1"
              },
              {
                "name": "v1",
                "filter": [
                  {
                    "type": "tcbm",
                    "properties": {
                      "TimeScale": 30000,
                      "FrameDuration": 1001,
                      "BitmapWidth": 250,
                      "BitmapHeight": 50,
                      "FontSize": 18,
                      "StringForegroundColor": "red",
                      "RegionBackgroundColor": "green"
                    }
                  },
                  {
                    "type": "bmvc",
                    "properties": {
                      "TimeScale": 30000,
                      "FrameDuration": 1001
                    }
                  }
                ]
              }
            ],
            "encode": {
              "type": "h264",
              "properties": {
                "OutputFormat": "avc1"
              }
            }
          }
        ]
      }
    ]
  }
}

Timecode Bitmap Converter

The tcbm filter converts timecode metadata to a subtitle stream in bmap format.

Property	Type	Description
`BitmapWidth`	integer	Specifies the width, in pixels, of the timecode region.
`BitmapHeight`	integer	Specifies the height, in pixels, of the timecode region.
`StringForegroundColor`	string	Specifies the foreground color of the timecode text as a TTML color: `#rrggbbaa`, `rgba(r,g,b,a)` or `namedcolor`.
`StringBackgroundColor`	string	Specifies the background color of the timecode text as a TTML color.
`RegionBackgroundColor`	string	Specifies the background color of the timecode region.

Bitmap Video Converter

The bmvc filter converts a subtitle stream in bmap format to a video stream in rgba format. The converter supports the following properties:

Property	Type	Description
`Timescale`	integer	The time scale of the video stream in ticks/seconds.
`FrameDuration`	integer	The nominal duration of each video frame in ticks.

Timecode Override

When the frame rate of an output video stream is changed the input timecode is no longer valid. By default the input timecode is not preserved and the output timecode starts at 00:00:00:00.

Use the Metadata Processor mplm to override the timecode of an output stream. For example, the following composition uses the Tachyon filter to convert the output frame rate to 23.976 and start the timecode at 01:00:00:00.

---
input:
  container:
  - name: input
    video:
    - name: v1
output:
  container:
  - name: output
    type: 'mp4 '
    video:
    - route:
        name: v1
      filter:
      - type: tdec
        properties:
          EnableMotionCompensation: true
          TimeScale: 24000
          FrameDuration: 1001
          Width: 1920
          Height: 1080
          FieldOrder: 1
      - type: mplm
        properties:
          DisableDeformatter: true
          SourceInserters:
          - Type: tcoi
          SourceVitcTimecode: 01:00:00:00

{
  "input": {
    "container": [
      {
        "name": "input",
        "video": [
          {
            "name": "v1"
          }
        ]
      }
    ]
  },
  "output": {
    "container": [
      {
        "name": "output",
        "type": "mp4 ",
        "video": [
          {
            "route": {
              "name": "v1"
            },
            "filter": [
              {
                "type": "tdec",
                "properties": {
                  "EnableMotionCompensation": true,
                  "TimeScale": 24000,
                  "FrameDuration": 1001,
                  "Width": 1920,
                  "Height": 1080,
                  "FieldOrder": 1
                }
              },
              {
                "type": "mplm",
                "properties": {
                  "DisableDeformatter": true,
                  "SourceInserters": [
                    {
                      "Type": "tcoi"
                    }
                  ],
                  "SourceVitcTimecode": "01:00:00:00"
                }
              }
            ]
          }
        ]
      }
    ]
  }
}