Subtitle (Closed Caption)
The document describes how to implement closed captions regarding the Federal Communication Commission regulations
** 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.
- Case 1: CEA-708 - see Using CEA-708.
- Case 2: SMPTE-TT / SAMI - see Using SMPTE-TT or SAMI.
If you want to use your own solution
- Case 3: own solution - see Using own Closed Captions 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
-
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>
-
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.
-
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 -
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.
-
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:
- Starting position inside subtitles string that the property should be applied to
- ”?”- attribute start marker
- charColor: decimal value of hexadecimal character’s color representation
- ”;” - delimiter for each attribute
- bgColor: decimal value of hexadecimal background’s color representation
- ”;” - delimiter for each attribute
- winColor: decimal value of hexadecimal caption window’s color representation
- “&” - delimiter if one string has serveral different attributtes (optional)
- 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:
- From first character to nineth character, the subtitles character color and background color are black and caption window color is red.
- 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 |
[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)
|