Subtitle (Closed Caption)

Published 2014-10-28 | (Compatible with SDK 4.5,5.0,5.1 and 2013,2014 models)

The document describes how to implement closed captions regarding the Federal Communication Commission regulations

Contents

** This class will not be supported in 2015.

   All functionalities of AppsFramework are more improved, integrating with CAPH. Therefore Appsframework is not supported since 2015 Smart TV.

Introduction

To comply with the Federal Communications Commission’s (FCC) closed caption rule, Content Providers (CPs) must support closed captions for video. In particular, applications bundled with a device are considered to be part of the device, and are covered by more stringent rules pertaining to devices (Section 203 of the CVAA[1]). For these bundled applications, CP must use either their own solution or manufacturer’s solution for captioning. This solution must handle complicated closed caption user attributes as listed in the FCC rules. The definition of these attributes draws from the CEA 708 standard.

If you want to use Samsung’s solution, we support CEA-708, SMPTE-TT and SAMI formats.

If you want to use your own solution

Using CEA-708

If content contains CEA-708 captions, nothing has to be modified. The Samsung platform will parse CEA-708 data and render it based on the user’s closed caption attributes settings. The Samsung native UI supports user’s closed caption attributes settings.

Samsung supports CEA-708 with the following codecs:

  • MPEG-2 Video: ATSC A/53, user data
  • H.264/AVC: ATSC A/72, ATSC_user_data() Syntax using the H.264 SEI Syntax

Using SMPTE-TT or SAMI

Implementing closed captions using Samsung Player API

  1. If your application uses Closed captions, you should attach the JavaScript code below.

    <script type="text/javascript" src="$MANAGER_WIDGET/Common/af/2.1.0/loader.js"></script>

  2. Player API namespace sf.service.VideoPlayer enables application to play video with Samsung’s standard UI. To play video with subtitles, you should additionally pass the “subtitle” option.

    sf.service.VideoPlayer.play({
    url: "http://www.samsung.com/samsung.mkv",    // Video URL
    title: "Samsung movie",                       // Video title
    subtitle: {                                   // Subtitles option begins
        type: "sami",                             // Subtitles type. "sami" or "smpte-tt"
        url: "http://www.samsung.com/samsung.smi" // Subtitles data file path if needed
    }
});

    Currently, Player API supports two subtitles types, “sami” and “smpte-tt”. If the subtitles type needs a separate data file, pass the file’s URL as subtitles url option. The video will be played with requested subtitles.

  3. There are caption options in native OSD menu. End users can configure the styles of subtitles. The SMPTE-TT data may contain its own styles. In this case, the OSD menu’s configuration has higher priority than data’s configuration. For more detail, please refer to the table below:

    Caption options in OSD Menu Style from SMPTE-TT Applied Style
    Default Not specified Default Style
    Default Specified Style from SMPTE-TT data
    Specified * OSD Menu’s configuration

  4. In case of “sami” type subtitles, the sf.serviceVideoPlayer provides “SMI Setting” menu to end users. Users are allowed to change the subtitles language if this operation is supported by the “sami” data. Additionally, subtitles’ synchronization time can be increased or decreased by the user.

  5. There is also a “General” OSD menu level which contains the general subtitles options.

Implementing closed captions without Player API

How to get user attributes of closed captions from Samsung native UI

Closed captions are implemented as Closed Caption API to support putting attributes for Samsung native UI. An application using closed captions should get its object instance as demonstrated below:

var closedcaption = window.webapis.tv.closedcaption || {};

Once an application has access to the object’s instance, it can invoke a function for getting the closed captions attributes:

var retval = closedcaption.getClosedCaptionOption(index, param);

Details of getClosedCaptionOption and its parameters are listed in the table below.

Function: getClosedCaptionOption(index, property)
Gets the value of specified closed caption parameter.
Parameter index Refer to table below.
property Refer to table below.
Return If call is successful, returns currently set parameter value for the closed caption parameter. -1 in case of failure.
Example 
getClosedCaptionOption(PROFILE_CC_FCC, CAPTION_EDGE_TYPE);

Table: Closed caption parameters

Index Parameters
PROFILE_CC CAPTION_FONT_SIZE
CAPTION_FONT_STYLE
CAPTION_FG_COLOR
CAPTION_FG_OPACITY
CAPTION_BG_COLOR
CAPTION_BG_OPACITY
CAPTION_LANGUAGE_TYPE
PROFILE_CC_FCC CAPTION_EDGE_TYPE CAPTION_EDGE_COLOR
CAPTION_FONT_SIZE CAPTION_SIZE_SMALL
CAPTION_SIZE_STANDARD
CAPTION_SIZE_LARGE
CAPTION_SIZE_EXTRA_LARGE
CAPTION_SIZE_DEFAULT
CAPTION_FONT_STYLE CAPTION_FONT_DEFAULT
CAPTION_FONT_STYLE0
CAPTION_FONT_STYLE1
CAPTION_FONT_STYLE2
CAPTION_FONT_STYLE3
CAPTION_FONT_STYLE4
CAPTION_FONT_STYLE5
CAPTION_FONT_STYLE6
CAPTION_FONT_STYLE7
CAPTION_FONT_STYLE8
CAPTION_FONT_UNDEFINED

CAPTION_FG_COLOR

CAPTION_BG_COLOR

CAPTION_EDGE_COLOR

 CAPTION_COLOR_DEFAULT
CAPTION_COLOR_WHITE
CAPTION_COLOR_BLACK
CAPTION_COLOR_RED
CAPTION_COLOR_GREEN
CAPTION_COLOR_BLUE
CAPTION_COLOR_YELLOW
CAPTION_COLOR_MAGENTA
CAPTION_COLOR_CYAN

CAPTION_FG_OPACITY

CAPTION_BG_OPACITY

 CAPTION_OPACITY_SOLID
CAPTION_OPACITY_FLASH
CAPTION_OPACITY_TRANSLUCENT
CAPTION_OPACITY_TRANSPARENT
CAPTION_OPACITY_DEFAULT
CAPTION_EDGE_TYPE CAPTION_EDGE_NONE
CAPTION_EDGE_RAISED
CAPTION_EDGE_DEPRESSED
CAPTION_EDGE_UNIFORM
CAPTION_EDGE_DROP_SHADOWED
CAPTION_LANGUAGE_TYPE CAPTION_LANGUAGE_AUTO
CAPTION_LANGUAGE_JPN
CAPTION_LANGUAGE_ENG
CAPTION_LANGUAGE_GER
CAPTION_LANGUAGE_FRE
CAPTION_LANGUAGE_ITA
CAPTION_LANGUAGE_RUS
CAPTION_LANGUAGE_CHS
CAPTION_LANGUAGE_KOR
CAPTION_LANGUAGE_SPA
CAPTION_LANGUAGE_UNDEFINED

How to download external captions file

An application implementing downloading of captions as a file should get the object instance of download plugin as demonstrated below:

var downloadsmi = window.webapis.download || {};

Once your application acquired the object’s instance, it can request the download of required file:

var retval = downloadsmi.requestDownload(Url, FileName, OnEvent);

Details of requestDownload and its parameters are below.

Function: requestDownload (Url, FileName, OnEvent)
Request to start download using http or https. This function is asynchronous, result status will be delivered to widget as an event.
Parameter Url Source url to download from (URL can start with http or https).
FileName Destination file name on the device
OnEvent Callback function for download status. It receives file path as an argument.
Return
If call is successful, returns 0.
-1 in case of failure.
Example 
var o = window.webapis.download || {};
o.requestDownload("http://www.testsmi.com/test.smi", "captionfile.smi", function (downloadedSubtitleFilePath) {
    if (downloadedSubtitleFilePath) {
        alert("[caption file] Download completed, downloaded file path: " + downloadedSubtitleFilePath);
    } else {
        alert("[caption file] Download failed. ");
    }
});

Important

On application exit, the caption file must be deleted. For this, you can use the removeFile function. Its details can be found below.

Function: removeFile(FileName)
Removes a file from device.
Parameter FileName Name of file to be deleted.
Return
If call is successful, returns 0.
-1 in case of failure.
Example 
webapis.download.removeFile("captionfile.smi");

How to handle caption data (Text & Provider’s caption attribute)

AVPlay object from Media API lets you use an external SMPTE-TT or SMI file for subtitles.

The subtitles callback, onsubtitle(), is called when a single subtitles string should be displayed on the screen. This callback has 3 parameters: sync time, subtitles text string and subtitles text string properties.

The first and second parameters are intuitve. The third parameter supports three possible string values representing respectively: character color, background color and caption window color. The parameters are concatenated with the position of subtitle part that the property should be applied to.

The third parameter is constructed, as follows:

  1. Starting position inside subtitles string that the property should be applied to
  2. ”?”- attribute start marker
  3. charColor: decimal value of hexadecimal character’s color representation
  4. ”;” - delimiter for each attribute
  5. bgColor: decimal value of hexadecimal background’s color representation
  6. ”;” - delimiter for each attribute
  7. winColor: decimal value of hexadecimal caption window’s color representation
  8. “&” - delimiter if one string has serveral different attributtes (optional)
  9. Repeat from step 1 in order to apply different styles for next part of subtitles string

Example:

1?charColor=4278190080;bgColor=4278190080;winColor=4294901760&10?charColor=4278190080;bgColor=4278190080;winColor=0;

For example, for the string from the code sample above, the explanation is as follows:

  1. From first character to nineth character, the subtitles character color and background color are black and caption window color is red.
  2. From tenth character to the last character, the subtitles character color and background color are black and caption window is transparent.

Please refer to the table below for color values.

Hex Decimal Name
0xFF00FFFF 4278255615 “aqua”
0xFF000000 4278190080 “black”
0xFF0000FF 4278190335 “blue”
0xFFFF00FF 4294902015 “fuchsia”
0xFF808080 4286611584 “gray”
0xFF00FF00 4278255360 “green”
0xFF00FF00 4278255360 “lime”
0xFF800000 4286578688 “maroon”
0xFF000080 4278190208 “navy”
0xFF808000 4286611456 “olive”
0xFFFFA500 4294944000 “orange”
0xFF800080 4286578816 “purple”
0xFFFF0000 4294901760 “red”
0xFFC0C0C0 4290822336 “silver”
0xFF008080 4278222976 “teal”
0xFFFFFFFF 4294967295 “white”
0xFFFFFF00 4294967040 “yellow”
0x00000000 0 “transparent”
0x00000000 0 NULL

Using own Closed Captions Solution

The CP must fully comply with all FCC’s requirements relating to the user attributes of closed captions.

Refer the original text of the regulations (IP Captioning Order, Jan 12, 2012 (FCC-12-9A1)).

 (1) Presentation. All apparatus shall implement captioning such that the caption
     text may be displayed within one or separate caption windows and supporting
     the following modes: text that appears all at once (pop-on), text that scrolls
     up as new text appears (roll-up), and text where each new letter or word
     is displayed as it arrives (paint-on).
 (2) Character color. All apparatus shall implement captioning such that characters
     may be displayed in the 64 colors defined in CEA-708 and such that users are
     provided with the ability to override the authored color for characters and
     select from a palette of at least 8 colors including: white, black, red, green,
     blue, yellow, magenta, and cyan.
 (3) Character opacity. All apparatus shall implement captioning such that users
     are provided with the ability to vary the opacity of captioned text and select
     between opaque and semi-transparent opacities.
 (4) Character size. All apparatus shall implement captioning such that users are
     provided with the ability to vary the size of captioned text and shall provide
     a range of such sizes from 50% of the default character size to 200% of
     the default character size.
 (5) Fonts. All apparatus shall implement captioning such that fonts are available
     to implement the eight fonts required by CEA-708 and § 79.102(k). Users must
     be provided with the ability to assign the fonts included on their apparatus
     as the default font for each of the eight styles contained in § 79.102(k).
 (6) Caption background color and opacity. All apparatus shall implement captioning
     such that the caption background may be displayed in the 64 colors defined in
     CEA-708 and such that users are provided with the ability to override
     the authored color for the caption background and select from a palette of
     at least 8 colors including: white, black, red, green, blue, yellow, magenta,
     and cyan. All apparatus shall implement captioning such that users are provided
     with the ability to vary the opacity of the caption background and select
     between opaque, semi-transparent, and transparent background opacities.
 (7) Character edge attributes. All apparatus shall implement captioning such that
     character edge attributes may be displayed and users are provided the ability
     to select character edge attributes including: no edge attribute, raised edges,
     depressed edges, uniform edges, and drop shadowed edges.
 (8) Caption window color. All apparatus shall implement captioning such that
     the caption window color may be displayed in the 64 colors defined in CEA-708
     and such that users are provided with the ability to override the authored color
     for the caption window and select from a palette of at least 8 colors including:
     white, black, red, green, blue, yellow, magenta, and cyan. All apparatus shall
     implement captioning such that users are provided with the ability to vary
     the opacity of the caption window and select between opaque, semi-transparent,
     and transparent background opacities.
 (9) Language. All apparatus must implement the ability to select between caption
     tracks in additional languages when such tracks are present and provide the ability
     for the user to select simplified or reduced captions when such captions are
     available and identify such a caption track as "easy reader".
(10) Preview and setting retention. All apparatus must provide the ability for
     the user to preview default and user selection of the caption features required
     by this section, and must retain such settings as the default caption configuration
     until changed by the user.
(11) Safe Harbor. Apparatus which implement Society of Motion Picture and Television
     Engineers Timed Text format (SMPTE ST 2052-1:2010: "Timed Text Format (SMPTE-TT)"
     2010) (incorporated by reference, see § 79.100) with respect to the functionality
     in subparts (1) through (10) of this paragraph shall be deemed in compliance with
     subpart (c) of this section.

Summary

Attribute Requirement
Character Color

Support 64 colors (provider’s color)

Support minimum 8 user’s colors (override) [2]
Character Opacity Opaque and semi-transparent opacities
Character Size 50% ~ 200% of default size
Fonts 8 fonts described in CEA-708 [3]

Caption Background

Color and Opacity

Support 64 colors (provider’s color)

Support minimum 8 user’s colors (override) [2]

Opaque, semi-transparent, and transparent
Character Edge Attributes

No edge, raised, depressed,

Uniform, drop shadow edges
Caption Window Color

Support 64 colors (provider’s color)

Support minimum 8 user’s colors (override) [2]

Opaque, semi-transparent, and transparent
Language Selection When multi-language captions exist
Preview and setting retention Support preview and setting retention of user selection

Example application

1.You can download the example video application here.

Figure 1. Screenshot of video play application using the caption options.

 

2.You can download the example application here.

Pressing the direction keys on the remote will result in changing and displaying closed captions options.

Figure 2. Screenshot of initialized example application showing one of the closed caption options.

Footnotes

[1] Communications and Video Accessibility Act
[2] (1, 2, 3) Minimum 8 colors: white, black, red, green, blue, yellow, magenta and cyan.
[3]

8 fonts described in CEA-708:

0 - Default (undefined)
1 - Monospaced with serifs (similar to Courier)
2 - Proportionally spaced with serifs (similar to Times New Roman)
3 - Monospaced without serifs (similar to Helvetica Monospaced)
4 - Propotionally spaced without serifs (similar to Arial and Swiss)
5 - Casual font type (similar to Dom and Impress)
6 - Cursive font type (similar to Coronet and Marigold)
7 - Small capitals (similar to Engravers Gothic)