Differences

This shows you the differences between two versions of the page.

Link to this comparison view

en:tvipjsapi:4 [2018/12/24 15:38] (current)
Alexander created
Line 1: Line 1:
 +
 +
 +====== TVIP JavaScript API #4 ======
 +
 +**Version API #4**\\
 +Avaliable for firmwares version //​linux-qt// ​ **4.1.4** 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: ====
 +
 +  * Network interface info and statistics collection.
 +  * Support for a fallback URL redirection in case of page loading error.
 +  * Support for launching Home scree in "TV only" and "​Combined"​ portal modes.
 +  * Support for Home key handling by goind to an URL in "Whole system"​ 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:
 +<​code>​
 +{
 +  "​address":​ <​address>,​
 +  "​folder":​ <​folder>,​
 +  "​username":​ <​username>,​
 +  "​password":​ <​password>​
 +}
 +</​code>​
 +Here, //<​address>//​ - IP-adress, domain or  NetBIOS-server name, //<​folder>//​ - name of sharing content, //<​username>//​ и //<​password>//​ - optional authorization credentials.
 +
 +NFS:
 +<​code>​
 +{
 +  "​address":​ <​address>,​
 +  "​folder":​ <​folder>​
 +}
 +</​code>​
 +Here, //<​address>//​ - IP-adress or domain server name, //<​folder>//​ - full path to sharing catalog.
 +
 +\\ \\
 +
 +==== void enableCas(String name, Object options) ====
 +
 +Enable CAS/DRM support for media streams that played from current portal. CAS/DRM type is specified be //name//. CAS/DRM specific options are taken from key-value options object.
 +\\ \\
 +
 +==== void enableSpatialNavigation(bool enable) ====
 +
 +Enable/​disable spatial navigation for current web portal. It means keyboard navigation over buttons and links.
 +\\ \\
 +
 +====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 getDeviceId();​====
 +
 +Returns device model indetifier (like //s410//).
 +\\ \\
 +
 +
 +====String getDisplayMode();​====
 +
 +Returns current display mode ("​1080i",​ "​1080p",​ "​720p",​ "​576i",​ etc).
 +\\ \\
 +
 +
 +====List getDirectoryDirs(String directory);​====
 +
 +
 +Returns directory list in a specified //​directory//​.
 +<​code>​
 +[ "​Dir1",​ "​Dir2",​ "​Dir3"​ ]
 +</​code>​
 +\\ \\
 +
 +====List getDirectoryFiles(String directory);​====
 +
 +Returns file objects list in a specified directory //​directory//​. ​
 +Object contains file name and file size.
 +
 +<​code>​
 +[
 +  {
 +    "​name":​ "​file1",​
 +    "​size":​ 1234567
 +  },
 +  ​
 +  {
 +    "​name"​ : "​file2",​
 +    "​size"​ : 44444
 +  }
 +]
 +</​code>​
 +
 +//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.
 +
 +\\ \\
 +
 +====Object getNetworkDefaultRouteConfig();​====
 +
 +Returns object that contains default route information.
 +Example object:
 +<​code>​
 +{
 +   "​ipaddress":​ "​192.168.1.1",​
 +   "​interface":​ "​eth0",​
 +   "​metric":​ 1,
 +}
 +</​code>​
 +Fields: //​ipaddress//​ - gateway IP-address, //​interface//​ - network interface name, //metric// - network metric.
 +
 +\\ \\
 +
 +====List getNetworkInterfaces();​====
 +Returns list of network interfaces.
 +Example list:
 +<​code>​
 +["​eth0","​ip6tnl0","​sit0",​ "​wlan0"​]
 +</​code>​
 +\\ \\
 +
 +====Object getNetworkInterfaceStatus(String name);====
 +Returns object, that contains information about status of a network interface with //​name//​.Use getNetworkInterfaces method to find interface name.
 +Example object:
 +<​code>​
 +{
 +  "​dns1":"​8.8.8.8",​
 +  "​dns2":"",​
 +  "​fullduplex":​true,​
 +  "​gateway":"​192.168.1.1",​
 +  "​ipaddress":"​192.168.1.100",​
 +  "​mac":"​10:​27:​BE:​04:​04:​04",​
 +  "​mask":"​255.255.255.0",​
 +  "​running":​true,​
 +  "​speed":​100
 +}
 +</​code>​
 +Fields: //mac// - MAC-address of the interface (could be the same as Main MAC Address or not); //running// - //true//, if intreface is in connected state, //false// otherwhise; //​fullduplex//​ - //true//, if connection is in full duplex, //false// if half-duplex;​ //speed// - connection speed in Mbits/sec; //​ipaddress//​ - IP address on the interface (empty if no IP assigned); //mask// - netmask; ​ //gateway// - interface gateway; //dns1// и //dns2// - DNS server'​s addresses.
 +
 +\\ \\
 +
 +====Object getNetworkStatistics(String name);====
 +Returns object, that contains information about network interface statistics with //name//.
 +Example object:
 +<​code>​
 +{
 +  "​b_packets_received":​0,​
 +  "​b_packets_sent":​0,​
 +  "​bytes_received":​988250211,​
 +  "​bytes_sent":​80635584,​
 +  "​d_packets_received":​32,​
 +  "​d_packets_sent":​0,​
 +  "​m_packets_received":​27303,​
 +  "​m_packets_sent":​0,​
 +  "​packets_received":​974195,​
 +  "​packets_sent":​508277,​
 +  "​u_packets_received":​0,​
 +  "​u_packets_sent":​0
 +}
 +</​code>​
 +Fields: //​bytes_received//​ and //​bytes_sent//​ - how many total bytes were sent and received over the interface; //​packets_received//​ and //​packets_sent//​ - how many total packets were sent and received over the interface; //​u_packets_received//​ и //​u_packets_sent//​ - how many unicast packets were sent and received over the interface; //​b_packets_received//​ и //​b_packets_sent//​ - how many broadcast packets were sent and received over the interface; //​m_packets_received//​ и //​m_packets_sent//​ - how many multicast packets were sent and received over the interface; ​
 +\\ \\
 +
 +
 +====List getSmbWorkgroups();​====
 +
 +Returns windows network workgroup list.
 +Example:
 +<​code>​
 +['​WORKGOUP',​ '​MYGROUP'​]
 +</​code>​
 +
 +\\ \\
 +
 +====List getSmbServers(String group);====
 +
 +Performs servers search in specified //group// network group and returns NetBIOS server names \\
 +Example: \\
 +<​code>​
 +['​MYPC',​ '​USER2'​]
 +</​code>​
 +
 +\\ \\
 +
 +====List getSmbServerShares(String server);​====
 +
 +Returns names of available network shares by NetBIOS or IP address defined by //server// parameter.
 +Example:
 +<​code>​
 +['​shared folder',​ '​Downloads'​]
 +</​code>​
 +
 +\\ \\
 +
 +====bool getStandBy();​====
 +
 +Returns //true//, if device was transferred to Sleep/​StandBy with setStandBy command. Returns false otherwise. Only for "Whole system"​ mode.
 +\\ \\
 +
 +====List getStorageValues();​====
 +
 +Returns all mounted devices (local and network)
 +<​code>​
 +[
 + {
 +   "​label":​ <​label>,​
 +   "​path"​ : <​ospath>,​
 +   "​fstype"​ : <​file_system>,​
 +   "​writable":​ <​writable>,​
 +   "​status":​ <​status>,​
 +   "​size":​ <​size>,​
 +   "​free"​ <​free>​
 + },
 +
 +]
 +</​code>​
 +
 +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.
 +
 +\\ \\
 +
 +
 +====String getUdpProxyAddress();​====
 +
 +Returns UDP proxy settings, specified in preferences.
 +\\ \\
 +
 +====String getSecurityCode();​====
 +
 +Returns security (parental control) code, specified in security preferences. If Security is disabled, returns empty value.
 +\\ \\
 +
 +====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 removeFile(String path);====
 +
 +Removes file in //path//. Only works for allowed directories.
 +
 +\\ \\
 +
 +====void launchPreferences();​====
 +
 +Launches system preferences Tvip.
 +
 +\\ \\
 +
 +==== launchBrowser(String url, String backUrl);​====
 +
 +Launch Web browser and open page from //url//. If browser is exited, portal from //backUrl// will be loaded.
 +
 +\\ \\
 +
 +==== launchHomeScreen();​====
 +
 +Launch TVIP Home screen (does not work in "Whole system"​ mode).
 +
 +\\ \\
 +
 +====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//​
 +
 +\\ \\
 +
 +==== setHomeKeyUrl(String url);====
 +
 +In "Whole system"​ mode, if user press "​Home"​ button, STB will load provided URL.
 +\\ \\
 +
 +==== setOverrideErrorUrl(String url);====
 +
 +Sets up URL, which STB will try to load in case of page loading error.
 +\\ \\
 +
 +====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). Only for "Whole system"​ mode.
 +\\ \\
 +
 +====void setWebProxy(String proxy, Array exclude)====
 +
 +Sets Web-proxy server address for using with current portal. All following http requests will be made over this proxy. Params: //proxy// - proxy server address, //exclude// - array with web-servers,​ that should not go over proxy (IP subnet or domain).
 +
 +\\ \\
 +
 +====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:
 +<​code>​
 +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;
 +</​code>​
 +
 +\\ \\ 
 +
 +====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
 +
 +\\ \\
 +
 +====void attachExternelSubtitle(String url, String encoding)====
 +
 +Add subtitles from an external file (from //url//) to currently played media. This method should be called after playUrl. Optional parameter //​encoding//​ sets up character encoding of subtitle file.
 +
 +\\ \\
 +
 +====String getCurrentUrl();​====
 +
 +Returns URL of current or last played stream.
 +\\ \\
 +
 +
 +====String getCurrentUrlMode();​====
 +
 +Returns mode (second param of playUrl) of current or last played stream.
 +\\ \\
 +
 +
 +====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
 +<​code>​
 +{
 +  "​type":​ <​videotype>,​
 +  "​id":​ <id>,
 +  "​codec":​ <​codec>,​
 +  "​lang"​ : <​lang>​
 +}
 +</​code>​
 +
 +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.
 +
 +\\ \\
 +
 +==== int getCurrentSubtitleStreamIndex();​ ====
 +
 +Returns currently played subtitle stream index.
 +
 +\\ \\
 +
 +==== void setCurrentAudioStreamIndex(int index); ====
 +
 +Sets active audio stream (//​index//​).
 +
 +\\ \\
 +
 +==== void setCurrentSubtitleStreamIndex(int index); ====
 +
 +Sets active subtitle 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.
 +
 +<​code>​
 +{
 +  "​id":​ <id>,
 +  "​name":​ <​name>,​
 +  "​startTime":​ <​start>,​
 +  "​endTime"​ : <​end>,​
 +  "​url"​ : <​url>,​
 +  "​status"​ : <​status>​
 +}
 +</​code>​
 +
 +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.