Chapter 13. JavaScript TV API

The JavaScript TV API provides access to Platform objects through a generated JavaScript wrapper interface.

TV System Object

The TVSystem object enables the apps to directly interact with the device hardware and get system specific information. Most functions are read-only.

When using the Simulator, the TV API porting layer has been implemented to emulate the TV device on the app developer's PC using a local properties file. The TVSystem properties which would normally come from the partner's device are stored in the file $HOME/YCTV-ADK/YCTV-SIM-XXX/TVSystemProperties.txt so that app developers can test these properties without the TV device. This file is only used in conjunction with the Simulator.

Special Settings

Certain tv.system properties are also provided by the specialSettings.get() function. Yahoo recommends that app developers use the specialSettings.get() function in lieu of the tv.system properties when available. These include:

Properties

Properties returned from the specialSettings.get() function. Be sure to test for valid values. Not all properties are implemented by all device partners.

Property

Type

Description

continentCode

String

Returns the two character continent code ('AF' for Africa, 'AS' for Asia, 'EU' for Europe, 'NA' for North America, 'SA' for South America, 'OC' for Oceania, and 'AN' for Antarctica) obtained from the user of the device.

countryCode

String

Returns the two character country code (ISO 3166) obtained from the user of the device.

locationCode

int

Returns the five character postal/zip code integer where the device is located. Obtained from the user of the device. The code is interpreted by country.

timezoneCode

blob

Returns the time zone code blob. Obtained from the user of the device. For example, {cc:"US", zn:widget.getLocalizedString("timezone_name_America_Los_Angeles"), zo:"UTC-08", zd:"07"} is used for Pacific Daylight Time. This property may not be supported by all device partners.

Device Hardware Interface

You can use the tv.system global namespace to acces the device hardware interface for apps. Be sure to test for valid values. Not all properties are implemented by all device partners.

The TVSystem object is found in the global TVMasterControl object.

Example

Aspect Ratio Constants

The aspect ratio of the display.

Name

Description

ASPECT_NOT_AVAILABLE

The aspect is not available.

ASPECT_OTHER

The aspect is not defined.

ASPECT_SQUARE

The video aspect ratio is square.

ASPECT_4X3

The video aspect ration is standard video or 4x3.

ASPECT_16X9

The video aspect ration is widescreen or 16x9.

Display Type Constants

Specifies the type of the display. This information is often used by apps for determining capabilities for screensavers.

Name

Description

DISPLAY_NOT_AVAILABLE

The display type is not available.

DISPLAY_PLASMA

The display type is PLASMA.

DISPLAY_DLP

The display type is DLP.

DISPLAY_LCD

The display type is LCD.

DISPLAY_OLED

The display type is OLED.

DISPLAY_OTHER

The display type is not defined by this list.

VChipStatus Constants

V-chips read information encoded in the rated program and block programs from the device based upon the selected rating. This status indicates the availability and status of a V-Chip in the device.

Name

Description

VCHIP_NOT_INSTALLED

The device is not equipped with the VChip.

VCHIP_ENABLED

The VChip control has been enabled by the user.

VCHIP_NOT_ENABLED

The VChip control has not been enabled by the user.

Network Status Constants

Indicates the status of the device's connection to the network.

Name

Description

NETWORK_STATUS_NOT_AVAILABLE

The network status is not available.

DISCONNECTED

The network is disconnected. No uplink and no associated wireless network is available.

CONNECTED

The network status is connected. The uplink is available.

Properties

Property

Type

Description

OEM

String

The name of the Device Partner or Original Equipment Manufacturer (OEM) returns an empty string if not available. It can be used for device partner identification and specific customizations.

deviceDescription

String

Returns a basic short description of the device provided by the device partner, returns an empty string if not available.

deviceId

String

Device partner determined device ID. The ID should be unique across all devices for a given device partner, returns and empty string if not available. It is useful for unique device identification.

deviceVersion

String

Device partner determined device version number, returns and empty string if not available. It is useful for device/version specific customizations.

deviceSoftwareVersion

String

Device partner software version. Returns an empty string if not available. It is useful for software specific customizations.

clock

double

Returns the clock time (in seconds since 1970). This function returns the real time acquired from time data sent by the guide tables, which may differ from time returned by the OS. Returns the OS time, if guide specified time is not available.

aspectRatio

int

Returns the current aspect ratio constant (e.g. ASPECT_16x9)

menuLanguage

String

Returns the language tag (IETF BCP 47) in which the user interface will be displayed (for example “es-MX” for Mexican Spanish and “fr-CA” for Canadian French). This property may not be implemented by all device partners.

country

String

Returns the country code (ISO 3166) in which the device is located, returns an empty string when not available. Country is obtained from the user of the device. This property may not be implemented by all device partners. Use the specialSettings.get('countryCode') function to check the country code.

deviceModel

String

Returns a string that specifies the device model as defined by the device partner. Returns an empty string when not available.

deviceClass

String

Returns a string that specifies the device class as defined by the device partner (e.g. Large Screen, Small Screen). Returns an empty string when not available.

deviceBrand

String

Returns a string with the brand name (e.g. PAVV, Scientific Atlanta). Returns an empty string when not available.

networkType

String

Returns a string with the available network interfaces. The string is a list of strings separated by ampersands (e.g. WiredEthernet=Ethernet1&WiFi=802.11n). This model supports multiple Ethernet and WiFi interfaces. Returns an empty string when not available.

wirelessSignalStrength

String

Returns a string with the signal strength value within the range 0 to 100. Decimal points are not supported. Returns an empty string when not available.

deviceDisplayType

int

Returns the display type of the TV. Display type values are defined constants.

vChipStatus

int

Returns the current status of the VChip. VChip status types are defined constants.

vChipRatingSystem

String

Returns the TV rating system string (e.g. US TV RATINGS). The valid list of TV rating system strings is defined in a configuration file. Returns an empty string when not available. The setting of the VChip rating is performed by a device partner specific API and is not exposed to apps.

locationCode

String

Postal/zip code string where the device is located. The code is interpreted by country. Returns an empty string if not available. This property may not be implemented by all device partners. Use the specialSettings.get('locationCode') function to check the location code.

deviceInfo

String

Returns a generic string that specifies device specific name-value pairs. The format is:

myString = “name1=value1;name2=value2;…”;

The names/values are device partner specific. The maximum number of characters in the string is 256. Returns an empty string when not available.

power

TVPower

Current state and previous state of the device's power status.

onAspectRatioChanged

function

Callback function triggered when aspect ratio changes.

onMenuLanguageChanged

function

Callback function triggered when menu language has changed.

Table of Contents