Closed Caption Converter

CLI, Web Services API, & GUI Version 3


Version History        0

Overview        0

New In Version 3        1

Getting Started        1

GUI        1

Installation        1

Usage        1

CLI        3

Installation        3

Usage        3

Web Services API        3

Prerequisites        3

Usage        3

Caption Profiles (Supported Formats)        4

Profile Options        5

GUI        5

CLI and Web Services API        5

Features        6

Frame Rate Conversion        6

Timecode Offset        6

Segmentation & Conform        6

SCC Decode        6

Text Search        6

Fix Overlap        6

External Job Configuration        6

Workflow Processing        7

Support        8

Version History

Document Version

Software Version

Notes

Author

1.0.0

>3.0.30

Initial Draft

Nathaniel Deshpande

Overview

Closed Caption Converter is used to convert, and conform closed caption and subtitle files. The original version of Closed Caption Converter was a command line tool used to convert SubRip (srt) and Scenerist (scc) files used in broadcast environments. Closed Caption Converter now supports more than twenty different profiles (formats) and includes the options to segment or offset caption files in order to automate the creation of new versions. Closed Caption Converter is offered as both a command-line-interface (CLI) tool, web service API, and graphical interface available for Mac OSX (64 bit), Windows 7+ (32 bit and 64 bit), and Linux (64 bit). The GUI version is also available online as a web application (https://app.closedcaptionconverter.com). In this guide we hope to provide up-to-date information on Closed Caption Converter (GUI, API, and CLI). Based on user feedback we have added a Getting Started section for those who prefer to “learn by doing”.

Version

Intended Use

GUI/Desktop Application

The GUI version is the most popular and used by thousands of people. It can be installed locally on a person’s computer or accessed via the web address: https://app.closedcaptionconverter.com

The GUI version is intended to be used for converting one or more caption files at a time. The GUI version provides a simple interface for video editors, broadcasters, and content creators.

CLI (Command-Line-Interface) tool

The CLI version allows for software developers and media services teams to automate their caption workflows in order to be able to convert a dynamic number of caption files on demand.

The most common deployment includes installing the CLI onto virtual machines or instances on premise or in the cloud (e.g. SDVI, AWS, GCP, and Azure). Licensing is able to handle multiple instances running at a single time so that converting caption files can be done asynchronously.

Web Services API (Closed Caption Converter API)

The web services api allows for developers and software teams to integrate Closed Caption Converter into their applications. It is an extension of the CLI tool, but does not require a server to run.

This solution allows for software developers to quickly develop and support multiple caption formats quickly inside of their application.

This solution has been deployed as part of media asset management systems and video archiving libraries.

New In Version 3

Version 2 offered a number of improvements over the original release of Closed Caption Converter. The two most notable features included file segmentation support via external configuration (using JSON sidecar files), and extended format support for MCC, PAC, and CAP files.

One of the major design flaws in version 2 was that all caption formats were mapped directly to their extension - this made it difficult to support more than one caption format if it shared an identical file extension.

Introducing Caption Profiles

Version 3 looks to correct this issue by introducing the concept of Caption Profiles. Profiles allow a user to specify the exact file type they wish to encode (write) or decode (read).

Introducing Profile Options

Along with Caption Profiles, we have introduced new profile options including encoding and decoding options. These allow users to take advantage of optional features that may not be required. For example, WebVTT files can have positional data and metadata notes inserted if specified in the encoding options of the conversion job. EBU-STL files offer the ability to encode a number of different metadata fields into the output file including author, title, and creation date. For more information please refer to the Profile Options section below.

Getting Started

GUI

Installation

Download and install the latest version of Closed Caption Converted by visiting https://www.closedcaptionconverter.com/downloads.html. If you do not wish to install Closed Caption Converter, you may also use the web-based version by visiting https://app.closedcaptionconverter.com.

If you experience any issues please contact our support team using the information provided in the Support section of this document.

Usage

  1. Open Closed Caption Converter and login using your email address and password linked to your account. If this is your first time logging in, it will prompt you to create a password.
  2. Load your source caption file by clicking the file input control near the top of the window. Note: Users can also click and drag a file into the box using File Explorer (Windows) or Finder (Mac).

  3. If the source file has an extension that matches more than one Caption Profile - the Source Profile dropdown will appear. Select the profile for your source caption file.
  4. Select your target Caption Profile. Use the Target Extension dropdown list to filter to the Target Profiles.
  5. Click the Convert button near the bottom of the Job form in order to convert your caption file. When the job completes it will display the output to the Target Preview on the left. 
  6. Users can save the target preview output to file by clicking the Save button located under the Target Preview display. Note: When using the web application - the file will save to the default location configured by the Browser. This option usually defaults to Downloads.

CLI

Installation

No installation required. The CLI tool is available via the download link provided by your sales representative.

Usage

Note: This tutorial provides a brief walkthrough of converting a single file using the Window’s command terminal.

  1. Open the command line terminal
  2. Navigate to the location where ccconverter.exe is stored (or the appropriate naming for your operating system)
  3. Convert your source file by using the following command:
    ccconverter.exe --source path/to/source.srt --target path/to/target.scc

Note: Because both the SRT and SCC extensions map to a single profile name there is no requirement to provide a source or target profile. For a complete list of supported profiles, please reference the table below or simply run the CLI without any arguments.

Web Services API

Prerequisites

Before using the Web Services API, users will need to generate an API key using the Closed Caption Converter GUI application. This means that in order to use the Web Services API, a standard subscription must exist for Closed Caption Converter (either monthly, or yearly). Users can generate a key by clicking the “API Keys” button in Closed Caption Converter.

Usage

Note: In this example we’ll be using Postman (desktop client) to generate requests.

  1. Create a new POST request using the jobs api endpoint.
  2. Under the Authorization tab enter your api key (see prerequisites above).
  3. Under the headers tab include your account username/email.
  4. Under the Body tab include your source file and job config

The config parameter can be generated using the gui version of Closed Caption Converter. If you experience any issues please contact our support team using the information provided in the Support section of this document.

The web services API will always return a pre-signed URL and job Id. The pre-signed url is a temporary link to the converted output file.

Caption Profiles (Supported Formats)

*The display Name is the name displayed in Closed Caption Converter GUI.

**The Profile Name is the actual name used by Closed Caption Converter and should be passed in when using the CLI tool.

Display Name*

Profile Name**

Extension

Decode (Import)

Encode (Export)

Substation Alpha

subStationAlpha

ssa

Advanced Substation Alpha

subStationAlpha

ass

Scenerist V1.0

scenerist

scc

MacCaption 608/708

macCaption

mcc

SubRip Video Subtitle Script

subRip

srt

WebVTT

webVtt

vtt, webvtt

SubViewer

subViewer

sbv, sub

Sofni

sofni

sub

Micro DVD

microDvd

sub

DVD Architect

dvdArch

sub

Avid DS

avidDs

txt

Adobe Encore

adobeEncore

txt

Apple DVD Studio Pro

appleDvdStudioPro

txt

EZ Title

ezTitle

txt

PowerPixel Format

powerPixel

txt

ProCap Transfer

proCapTransfer

txt

QuickTimeText

quickTimeText

txt

EBU STL

ebuStl

stl

Spruce STL

spruceStl

stl

ScreenSystems Poliscript

ssPoliscript

pac

Cheetah (binary)

cheetahBin

cap

Cheetah (ASCII Text)

cheetahAscii

asc

Timed-Text Markup Language

ttml

ttml, xml

SMPTE-TT

smpteTtml

ttml, xml

Distribution Format Exchange Profile

dfxp

xml, dfxp

DLP Cinema

dlpCinema

xml,

Netflix TT Captions

netflixTtCaptions

xml

Netflix TT Subtitles

netflixTtSubtitles

xml

MAGIC TT

magicTt

xml

EBU TT

ebuTt

xml

Synchronized Accessible Media Interchange

sami

sami, smi

Comma-Separated Values

csv

csv

JSON

json

json

Profile Options

There are two types of Profile Options that can be specified when submitting a job (either through the GUI or external configuration file when using the CLI).

  1. Profile Decoding Options are processed against the source (input) file
  2. Profile Encoding Options are processed against the target (output) file.

GUI

Profile options are displayed as part of the Advanced Options menu. Simply click the Advanced Options toggle in order to reveal supported encoding or decoding options.

CLI and Web Services API

In order to utilize Encoding or Decoding Options, external job configuration must be used. The following is an example job that shows the Encoding Options.

{

    "source" : ".\\src\\external\\cc-lib\\samples\\scc\\file1.scc",

    "target" : ".\\test\\exports\\vttEncode.vtt",

    "decoding_options" : [],

    "encoding_options" : [

        {

            "name": "Encode Position",

            "selected" : true

        },

        {

            "name": "Encode Formatting",

            "selected" : true

        }

    ]

}

Note: In order to list all encoding or decoding options for a profile simply list the profile using the command: ccconverter.exe --list *profileName* or by viewing the job configuration pop-up in the GUI version of Closed Caption Converter.

Note: For a complete list of supported profiles, please refer to the Caption Profile section above. Users may also run Closed Caption Converter CLI using the help argument: ccconverter.exe --help

Features

Frame Rate Conversion

Closed Caption Converter supports multiple frame rates (23.976, 24, 25, 29.97, 30, 50, 59.94, and 60) which the user can specify per job. Source and target frame rates can be set independently. Please note the default frame rate is set to 29.97 (drop-frame 30). The source frame rate will default to the target frame rate configuration.

Timecode Offset

Closed Caption Converter is able to offset the timecode (adding and subtracting) of closed caption files as the final step prior to export. In order to apply an offset two arguments must be provided: offset value, and offset type. The offset value can be specified in either frames or SMPTE timecode. The offset type can either be set to “add” or “subtract”. Offset type is optional and will default to “add”.

Segmentation & Conform

Closed Caption Converter is able to segment closed caption files based on an incode (start time) and outcode (end time). The caption events that end after the start time or start before the end time are accepted (this means it is possible to have caption events that run past the specified segment and is considered accepted behavior). “Black” spacing can be added to a caption file by providing a “Black” segment with a duration. The name “Black” spacing can be attributed to “Commercial Black” used in broadcast environments as a way to make commercial breaks easily distinguishable.

SCC Decode

In order to help engineers while troubleshooting broadcast SCC files, Converter CLI provides a built-in SCC Decode function that will decode SCC files to a human readable format. The SCC codes are decoded to make them easily readable using the documented code chart: http://www.theneitherworld.com/mcpoodle/SCC_TOOLS/DOCS/CC_CODES.HTML

Text Search

The text search option is only available using the web services API or CLI. The output will be filtered to only include events that match the search criteria.

Fix Overlap

Fix Overlap is an option only available via the web services api or CLI. It allows for operators to easily correct bad caption files with overlapping events.

External Job Configuration

The Closed Caption Converter CLI and Web Services API provides the option to submit job properties via external JSON. This allows users to easily organize and archive past jobs.  

The easiest way to generate external job configuration files is to use the GUI version of Closed Caption Converter and submit an example job based on the functions a user may require. Once a job has been submitted, the example json config will be made available via the Job Configuration modal/pop-up.

Example: Execute CLI jobs via external json

ccapconverter --config /srv/storage/jobs/job101.json

Job101.json

{

    "source_file": "/srv/storage/input/test.scc",

    "target_file": "/srv/storage/output/test.srt",

    "offset"  : "01:00:00:00",

    "offset_type" : "subtract",

    "source_frame_rate": 25,

    "target_frame_rate": 29.97,

    "conform_job" : [

     {

         "duration": "00:00:00:10",

         "endTime": "00:00:00:10",

         "startTime": "00:00:00:00",

         "source": "black"

     },

     {

         "duration": "00:48:44:05",

         "endTime": "10:48:43:10",

         "startTime": "09:59:59:05",

         "source": "segment"

     }

 ]

}

Workflow Processing

Closed Caption Converter follows a basic process workflow when it comes to applying features to the source input file. This is important to understand when specifying job properties. All timecode offsets are applied in the final stage before final export - meaning that all segment timings must conform to the original source file timecodes.

 

The workflow process map shows the process used when applying filtering to caption data prior to export.

Support

Closed Caption Converter is a product developed by Closed Caption Creator Inc. Users with active accounts or support contracts can email:

support@closedcaptioncreator.com

Please feel free to attach any source files, screenshots, and job configurations (CLI only) directly to your email in order for us to provide better support to you. All source files are deleted from our systems after 90 days or following the closing of a support case.