TVIP JavaScript API #2

Version API #2
Avaliable for firmwares version linux-qt 3.4.0 or higher.

Set-top-boxes TVIP display Web-content using WebKit engine.

JavaScript API in Set-top-boxes Tvip is based on the following main objects:

window.TvipStb contains basic methods for operating with hardware;
window.TvipPlayer contains methods for control mediaplayer;
window.TvipRecorder contains methods for recorder control;
window.TvipEvent contains callback methods;

Objects do not require an explicit creation or any initialization and is accessible from any Web-page that is open in STB browser.

The main changes:

Support work with the manager of the mount (adding SMB and NFS share).
Sleep mode is now controlled via JS API in the portal mode “for the whole system”.
Possibility to remap for IR remote all systems commands in the portal mode “for the whole system”.
Support HDMI-CEC events.
Support events for transition application into background mode.

Description methods of objects JS API

TvipStb

bool addMountPoint(int id, bool temp, int type, String name, Object options);

Add or change mount point with indicated id. If temp equal false, then mount point will be saved after device reload, if true - then mount point will be deleted after reload or application restart.The possible mount points types (type): 1 - SMB, 2 - NFS. Point name at mount system (for example, at pop-up message): name. Parameter options set specific options as object:

SMB:

{
  "address": <address>,
  "folder": <folder>,
  "username": <username>,
  "password": <password>
}

Here, <address> - IP-adress, domain or NetBIOS-server name, <folder> - name of sharing content, <username> и <password> - optional authorization credentials.

NFS:

{
  "address": <address>,
  "folder": <folder>
}

Here, <address> - IP-adress or domain server name, <folder> - full path to sharing catalog.

int getApiVersion();

Returns API version.

String getCurrentLanguageCode();

Returns id of currently active interface language ('en', 'ru').

String getCurrentTimezone();

Returns currently time zone (for example, Europe/Moscow).

String getDisplayMode();

Returns current display mode (“1080i”, “1080p”, “720p”, “576i”, etc).

List getDirectoryDirs(String directory);

Returns directory list in a specified directory.

[ "Dir1", "Dir2", "Dir3" ]

List getDirectoryFiles(String directory);

Returns file objects list in a specified directory directory. Object contains file name and file size.

[
  {
    "name": "file1",
    "size": 1234567
  },
  
  {
    "name" : "file2",
    "size" : 44444
  }
]

name -file name, size - file size in bytes.

String getEnvValue(String name);

Gets variable from the browser store. If name not found, empty string returns.

String getMainMacAddress();

Returns main MAC address as string. Usually it's Ethernet interface MAC.

List getSmbWorkgroups();

Returns windows network workgroup list. Example:

['WORKGOUP', 'MYGROUP']

List getSmbServers(String group);

Performs servers search in specified group network group and returns NetBIOS server names
Example:

['MYPC', 'USER2']

List getSmbServerShares(String server);

Returns names of available network shares by NetBIOS or IP address defined by server parameter. Example:

['shared folder', 'Downloads']

List getStorageValues();

Returns all mounted devises (local and network)

[
 {
   "label": <label>,
   "path" : <ospath>,
   "fstype" : <file_system>,
   "writable": <writable>,
   "status": <status>,
   "size": <size>,
   "free" <free>
 },

]

Object fields:
label - Resource name(label) visible to user;
path - mount point
fstype - FS type (e.g. vfat, ntfs, ext2, ext3, nfs, cifs;
writable - write access (“1” - yes, “0” - no);
status - mount point status (“0” - need mount, “1” - mount in progress, “2” - mount successfully, “3” - mount error, “4” - umount in progress, “5” - unmounted, “6” - umount error),
size - FS size,
free - Available free space.

bool hasDirectory(String osPath);

Returns true, if directory osPath exists. Otherwise returns false.

bool hasFile(String osPath);

Returns true, if file (not directory) with defined name osPath exists, false otherwise.

void launchPreferences();

Launches system preferences Tvip.

void logDebug(String message);

Outputs debugging message to terminal(Linux) or logcat(Android).

void rebootSystem();

Reboots system.

void removeMountPoint(int id);

Removes mount point from mount manager. id - Mount point identifier

void setColorKey(int color);

Setups UI color that could be consider as transparent for video layer. color in RGB model.

void setCustomHeader(String header, String value);

Defines HTTP-header for browser. header - header name, value - header value. If value is empty, previously defined header will be purged.

void setEnvValue(String name, String value);

Saves variable in browsers persistent storage. All variables are available for all browser pages.

void setDirectoryListFilters(String filters);

Setups filename filter for getDirectoryFiles and getDirectoryDirs. | Will be count as delimiter.
? and * applicable as well.
e.g. *.avi|*.mp3

void setPassKeyKeyboard(bool enabled);

If enabled=true, Cursor key press(on remote) event will be pass to Java Script directly, instead of default virtual keyboard handler.

void setPassKeyMenu(bool enabled);

If enabled==true, Remote “Menu” button press event will be pass to JS, instead of Tvip menu call.

void setPassKeySysInfo(bool enabled);

If enabled==true, remote press “S.INFO” event will be passed to JS, instead of Tvip system info call.

void setPassKeySettings(bool enabled);

If enabled==true, remote press “Settings” will be passed to JS, instead of Tvip settings menu call.

void setStandBy(bool enabled);

Switches STB in sleep mode (enabled==true) or return it to operation mode (enabled==false).

void showVirtualKeyboard(bool show);

Virtual keyboard show (show=true) or hide (show=false).

void reset();

Resets settings:
transparent color;
HTTP-header;
file filter.

TvipPlayer

void reset();

Resets playback. If we don't need playback after page change this routine should be called.

void playUrl (String url, String mode);

Starts playback defined URL(local path also welcome).

Parameter mode can be:

vod - URL contains VOD-file (with final length specified);

live - URL contains live TV-stream (Timeshift and DVR are welcome);

Examples:

playUrl ("udp://239.1.1.1", "live"); // Start play multicast-stream;
playUrl ("http://domain.tv/movies/movie.mkv", ""); // Start play file via http;
playUrl ("http://domain.tv/hls/playlist.m3u8", ""); // Start play HLS-video;

void setVideoWindow(int x, int y, int w, int x, boolean onTop);

Sets up video window size. Position seting up according current video out mode.

If w = 0 и h = 0, Full screen mode used.

If onTop = true, video window drows above UI.

void stop();

Stops playback if any.

void pause();

sets playback on pause.

void unpause();

Continues playback.

void seek(int position);

Sets playback position in milliseconds. Keep in mind that beginning of playback is minPosition see below

int getCurrentPositionMsec();

Returns current playback position.

int getMinPositionMsec();

Returns minimal playback position (e.g. content beginning)

int getMaxPositionMsec();

Returns maximum playback position (e.g. content ends).

void setVolume();

Sets volume level from 0 to 100

int getVolume();

Returns current volume level from 0 to 100

void setMute(bool mute);

Turns off (mute=true) or turns on (mute=false) sound.

bool getMute();

Returns true, if muted, otherwise false;

String getContainerType();

Returns the type of container being played (e.g. mpegts, avi, matroska)

int getStreamsCount();

Returns content being played media streams count (audio, video, subtitles etc)

Object getStreamInfo(int index);

Returns an object with media stream info

{
  "type": <videotype>,
  "id": <id>,
  "codec": <codec>,
  "lang" : <lang>
}

Here:
videotype - media stream type;
“v” - video,
“a” - audio,
“s” - subtitles;
id - PID;
codec - codec name;
lang - Audio stream ISO 639 language code.

int getCurrentVideoStreamIndex();

Returns currently played video stream index.

int getCurrentAudioStreamIndex();

Returns currently played audio stream index.

void setCurrentAudioStreamIndex(int index);

Sets active audio stream (index).

void setAspectRatio (String ratio)

Sets aspect ratio.
Available values:
“box” - Original
“full” - Full screen
“zoom” - Zoomed.

TvipRecorder

String addRecord(String name, String url, String path, String start, String end);

Adds new record job.
Here:
name - record name,
url - stream URL (MPEGTS via UDP, RTP, HTTP are supported.)
path - Local path to record,
start и end - start/stop time in UNIX TIMESTAMP or “YYYYMMDDTHHmmss” format.
Returns unique record job id.

bool cancelRecord(String id, bool removeFile);

Removes record job by id. If removeFile=true, stream stored to storage also will be removed.
Returns true in success.

void updateStartEndTime(String id, String start, String end);

Updates start time or(and) end time of recording id. If we need to set only one parameter leave second one empty.
Fromat for start end see at addRecord

List getRecordIds();

Returns currently added jobs list.

Object getRecord(id);

Returns object (by id) with record parameters.

{
  "id": <id>,
  "name": <name>,
  "startTime": <start>,
  "endTime" : <end>,
  "url" : <url>,
  "status" : <status>
}

Here:
<id>, <name>, <start>, <end> - corresponds with addRecord routine parameter;
<status> - record status:
“waiting” - waiting for record,
“recording” - record in progress,
“finished” - record finished,
“error” - error occurred.

TvipEvent

TvipEvent consist of Callback functions, which may be overloaded for events capturing.

onPlayerStateChange(int oldState, int newState);

Calls on mediaplayer playback status change. oldState - previous player status, newState - new player status.

Player possible status:

1 - Retrieving new URL;
2 - получение метаданных;
3 - Metadata received;
4 - Decoders preparation;
5 - Playback;
6 - End of content;
7 - Stopping playback;
8 - Playback stopped;
9 - Playback on hold;
10 - Seek new position is in progress;
11 - Error occured;

onSystemEvent(String codename, Object args);

On system event.
Examples codename:

“mounted” - External storage connected and ready to use (args[“label”] - device label).
“unmounted” - External storage is gone (args[“label”] - device label).
“onpause” - Web-app window goes to background (eg, active Home or Settings screen).
“onresume” - Web-app window become active (Calls on application resume).
“cec_sleep” - HDMI connected TV turns OFF.
“cec_wake” - HDMI connected TV turns ON.

Table of Contents

TVIP JavaScript API #2

The main changes:

Description methods of objects JS API

TvipStb

bool addMountPoint(int id, bool temp, int type, String name, Object options);

int getApiVersion();

String getCurrentLanguageCode();

String getCurrentTimezone();

String getDisplayMode();

List getDirectoryDirs(String directory);

List getDirectoryFiles(String directory);

String getEnvValue(String name);

String getMainMacAddress();

List getSmbWorkgroups();

List getSmbServers(String group);

List getSmbServerShares(String server);

List getStorageValues();

bool hasDirectory(String osPath);

bool hasFile(String osPath);

void launchPreferences();

void logDebug(String message);

void rebootSystem();

void removeMountPoint(int id);

void setColorKey(int color);

void setCustomHeader(String header, String value);

void setEnvValue(String name, String value);

void setDirectoryListFilters(String filters);

void setPassKeyKeyboard(bool enabled);

void setPassKeyMenu(bool enabled);

void setPassKeySysInfo(bool enabled);

void setPassKeySettings(bool enabled);

void setStandBy(bool enabled);

void showVirtualKeyboard(bool show);

void reset();

TvipPlayer

void reset();

void playUrl (String url, String mode);

void setVideoWindow(int x, int y, int w, int x, boolean onTop);

void stop();

void pause();

void unpause();

void seek(int position);

int getCurrentPositionMsec();

int getMinPositionMsec();

int getMaxPositionMsec();

void setVolume();

int getVolume();

void setMute(bool mute);

bool getMute();

String getContainerType();

int getStreamsCount();

Object getStreamInfo(int index);

int getCurrentVideoStreamIndex();

int getCurrentAudioStreamIndex();

void setCurrentAudioStreamIndex(int index);

void setAspectRatio (String ratio)

TvipRecorder

String addRecord(String name, String url, String path, String start, String end);

bool cancelRecord(String id, bool removeFile);

void updateStartEndTime(String id, String start, String end);

List getRecordIds();

Object getRecord(id);

TvipEvent