Broadcast API Usages

Overview

This document describes how to play, access, and use television services broadcast on satellite, cable, or terrestrial environment through the Samsung Product Broadcast API.
The API provides the ability to tune in to a broadcasting channel, get information about a channel's possible subtitles, closed captions, and audio tracks, and the ability to select the desired track according to the user's needs.

Prerequisites

• Device with DVB / ATSC / ISDB tuner, connected to an antenna.

• To play broadcasting content, use the Broadcast API.

• To use this API, add the following code to the "index.html" file.

   <script type='text/javascript' src='$WEBAPIS/webapis/webapis.js'></script>
  

API Usages

webapis.broadcast.getVersion

Get the version of the Samsung Prodct Broadcast API.

webapis.broadcast.enableDataService

Enable the broadcast data service, which provides support for subtitles or captions and other broadcast functionalities. This method should be called at the beginning of the web application.

webapis.broadcast.disableDataServce

Disable the broadcast data service. This method should be called before the web application finishes.

webapis.broadcast.tuneDirect

Directly tune in to the selected broadcasting channel.

• Tuning in DVB terrestrial service

  Sample code:

  function onsuccess(windowRect, type) {
    var channelObject = {
      'broadcastStandard': 'DVB',
      'frequency': 642000000 / 1000, 
      'bandwidth': '8MHz',    'programNumber':  17604,
      'modulationType': '8PSK',
      'channelType': 'DTV'
    };
    
    window.webapis.broadcast.tuneDirect(channelObject, function() {console.log("tuneDirect success");}, function() {console.log("tuneDirect error");});
    document.getElementById('test').innerHTML += JSON.stringify(channelObject);
  }
  
  function onerror(error) {
    console.log('tizen.tvwindow.show Error : ' + JSON.stringify(error));
  }
  
  tizen.tvwindow.show(onsuccess, onerror, ["0px", "0px", "1920px", "1080px"], "MAIN", "BEHIND");
  

• Tuning in DVB cable service

  Sample code:

  function onsuccess(windowRect, type) {
    var channelObject = {
      {
    		broadcastStandard: 'DVB',
    		channelType: 'CDTV',
    		modulationType: 'QAM64',
    		bandwidth: '8MHz',
    		frequency: 722000,
    		programNumber: 1031,
    		major: 1,
    	};
    	
    	window.webapis.broadcast.tuneDirect(channelObject, function() {console.log("tuneDirect success");}, function() {console.log("tuneDirect error");});							
    	document.getElementById('test').innerHTML += JSON.stringify(channelObject);
    }
  
    function onerror(error) {
        console.log('tizen.tvwindow.show Error : ' + JSON.stringify(error));
    }
  
    tizen.tvwindow.show(onsuccess, onerror, ["0px", "0px", "1920px", "1080px"], "MAIN", "BEHIND");
  

• Tuning in DVB satellite service

  Sample code:

    function onsuccess(windowRect, type) {
    	var tuneOptionSDTV = {};  //TRT 1
    	tuneOptionSDTV.broadcastStandard = "DVB";
    	tuneOptionSDTV.channelType = "SDTV";
    	tuneOptionSDTV.frequency = 11096000; 
    	tuneOptionSDTV.satelliteId = "TURKSAT_42E";
    	tuneOptionSDTV.programNumber = 1;
    	tuneOptionSDTV.polarization = "POL_HL";
    	
    	window.webapis.broadcast.tuneDirect(tuneOptionSDTV, function() {console.log("tuneDirect success");}, function() {console.log("tuneDirect error");});
    						
    	document.getElementById('test').innerHTML += JSON.stringify(tuneOptionSDTV);
    }
    function onerror(error) {
        console.log('tizen.tvwindow.show Error : ' + JSON.stringify(error));
    }
  
    tizen.tvwindow.show(onsuccess, onerror, ["0px", "0px", "1920px", "1080px"], "MAIN", "BEHIND");
  

• Tuning in cable and terrestrial ATSC or ISDB services

  Sample code:

  const tuneATSCOptions = [
    {
      broadcastStandard: "ATSC",
      channelType: "CDTV",
      major: 27,
      minor: 11,
      frequency:243000, 
      modulationType: "QAM256"
    },
    {
      broadcastStandard: "ATSC",
      channelType: "CDTV",
      ptc: 27, 
      programNumber: 1,						
      modulationType: "QAM256"
    },
    {
      broadcastStandard:"ISDB", 
      channelType:"DTV",    
      frequency:177000, 
      modulationType:"ISDB_T",
      major: 10,
      minor: 1,
      programNumber: 72  
    }
  ];
  
  function onsuccess(windowRect, type) {
    window.webapis.broadcast.tuneDirect(tuneATSCOptions[0], function() {console.log("tuneDirect success");}, function() {console.log("tuneDirect error");});							
    document.getElementById('test').innerHTML += JSON.stringify(tuneATSCOptions[0]);
  }
  
  function onerror(error) {
    console.log('tizen.tvwindow.show Error : ' + JSON.stringify(error));
  }
  
  tizen.tvwindow.show(onsuccess, onerror, ["0px", "0px", "1920px", "1080px"], "MAIN", "BEHIND");
  

webapis.broadcast.enableSubtitles

This API enables or disables subtitles on DVB broadcasted content. Closed captions are only shown in full-screen mode.

Sample code:

function enableSubtitles() {
	var key = webapis.tvinfo.TvInfoMenuKey.SUBTITLE_ONOFF_KEY;
	var value = webapis.tvinfo.TvInfoMenuValue.ON;

	var onsuccess = function() {
		console.log("onsuccess: subtitles enabled!");
	};

	var onerror = function() {
		console.log("onerror: subtitles not enabled!");
	};

	webapis.tvinfo.setMenuValue(key, value, onsuccess, onerror);
}

function disableSubtitles() {
	var key = webapis.tvinfo.TvInfoMenuKey.SUBTITLE_ONOFF_KEY;
	var value = webapis.tvinfo.TvInfoMenuValue.OFF;

	var onsuccess = function() {
		console.log("onsuccess: subtitles disabled!");
	};

	var onerror = function() {
		console.log("onerror: subtitles not disabled!");
	};

	webapis.tvinfo.setMenuValue(key, value, onsuccess, onerror);
}

webapis.broadcast.clearRatings

This API removes age restrictions for watching TV programs.

Sample code:

function clearRating() {
	console.log("[clearRating] function call");
	var onsuccess = function() {		
		console.log("[clearRating] success ");
	};
	var onerror = function(error) {		
		console.log("[clearRating] code: " + error.code + " error name: " + error.name + "  message " + error.message);
	};	
  
	log("[clearRating] window.webapis.broadcast object: " + window.webapis.broadcast);
	window.webapis.broadcast.clearRating(onsuccess, onerror);
}

webapis.broadcast.getCurrentSubtitle

This API returns the current subtitle index, starting from 0.

Sample code:

function getCurrentSubtitle() {	
	console.log("[getCurrentSubtitle] function call");
	var getCurrentSbt = null;
	try {
		console.log("[getCurrentSubtitle] window.webapis.broadcast object : " + window.webapis.broadcast);		
		getCurrentSbt = window.webapis.broadcast.getCurrentSubtitle();		
	} catch (e) {		
		console.log("[getCurrentSubtitle] call syncFunction exception [" + e.code + "] name: " + e.name + " message: " + e.message);
	}
	if(null !== getCurrentSbt){
		console.log("[getCurrentSubtitle] index:" + getCurrentSbt.index + " language:" + getCurrentSbt.language + " mode:" + getCurrentSbt.mode);
	}
}

webapis.broadcast.setCurrentsSubtitle

This API determines the current subtitle track. The "current" parameter is of the "long" type and ranges from 0 to the length of the subtitle track table - 1.

Sample code:

function setCurrentSubtitle(current) {
	console.log("[setCurrentSubtitleIndex] function call");
	var onsuccess = function() {
		console.log("[setCurrentSubtitleIndex] success ");
	};
	var onError = function(error) {		
		console.log("[setCurrentSubtitleIndex] error code: " + error.code + " error name: " + error.name + "  message: " + error.message);
	};	
	window.webapis.broadcast.setCurrentSubtitleIndex(current, onsuccess, onerror);
}

webapis.broadcast.getTotalSubtitle

This API returns information about the subtitle tracks available on currently tuned channel.

Sample code:

function getTotalSubtitle() {
	console.log("[getTotalSubtitle] function call");
	var i;
	try {		
		getTotalSbt = window.webapis.broadcast.getTotalSubtitleInfo();		
	} catch (e) {	
		console.log("[getTotalSubtitle] call syncFunction exception [" + e.code + "] name: " + e.name + " message: " + e.message);
		getTotalSbt = null;
	}
	if(null != getTotalSbt){
		totalSubtitlesLength = getTotalSbt.length;
		for(i =0; i < getTotalSbt.length; i++){
			console.log("index: "+ getTotalSbt[i].index + " language:" + getTotalSbt[i].language+ " mode:" + getTotalSbt[i].mode);
		}
	}
}

webapis.broadcast.getCurrentAudio

This API returns the current audio track index, starting from 0.

Sample code:

function getCurrentAudio() {	
	console.log("[getCurrentAudio] function call");
	var getCurrentAudio = null;
	try {		
		console.log("[getCurrentAudio] window.webapis.broadcast object : " + window.webapis.broadcast);		
		getCurrentAudio = window.webapis.broadcast.getCurrentAudioInfo();		
	} catch (e) {	
		console.log("[getCurrentAudio] call syncFunction exception [" + e.code + "] name: " + e.name + " message: " + e.message);
	}
	if(null !== getCurrentAudio){
		console.log("[getCurrentAudio] index:" + getCurrentAudio.index + ", type:" + getCurrentAudio.type + ", language:" + getCurrentAudio.language);
	}
}

webapis.broadcast.setCurrentAudio

This API determines the current audio track. The "current" parameter is of the "long" type and ranges from 0 to the length of the audio track array - 1.

Sample code:

function setCurrentAudio(current) {
	console.log("[setCurrentAudio] function call");
	var onsuccess = function() {
		console.log("[setCurrentAudio] success ");
	};
	var onerror = function(error) {	
		console.log("[setCurrentAudio] error code :" + error.code + " error name: " + error.name + "  message: " + error.message);
	};	
	console.log("[setCurrentAudio] window.webapis.broadcast object: " + window.webapis.broadcast);	
	window.webapis.broadcast.setCurrentAudio(current,"", onsuccess, onerror);  
}

webapis.broadcast.getTotalAudio

This API returns information about the audio tracks available on currently tuned channel.

Sample code:

function getTotalAudio() {
	console.log("[getTotalAudio] function call");
	try {	
		getTotalAud = window.webapis.broadcast.getTotalAudioInfo();		
	} catch (e) {
		console.log("[getTotalAudioInfo] call syncFunction exception [" + e.code + "] name: " + e.name + " message: " + e.message);
		getTotalAud = null;
	}
	if(null !== getTotalAud){
		totalAudiosLength = getTotalAud.length;
		console.log("size of audio = " + totalAudiosLength);
		var i;
		for(i =0; i < totalAudiosLength; i++){
			console.log("index : "+ getTotalAud[i].index + ", type:" + getTotalAud[i].type + ", language " + getTotalAud[i].language);
		}
	}
	else
	{
		console.log("[getTotalAudioInfo] result data = NULL");
	}
}

webapis.broadcast.setHotelDrmForensic Data

This API provides methods to set forensic data for security by watermark. No other DRM APIs are provided for here. Playing TV services with DRM is based on setting the appropriate value for DRM in the factory menu (hotel option).

Sample code:

function setHotelDrmForensicData() {
	console.log("[setHotelDrmForensicData] function call");
	var onsuccess = function(val) {	
		console.log("[setHotelDrmForensicData] success :"  + val.result);
	};
	var onerror = function(error) {		
		console.log("[setHotelDrmForensicData] code :" + error.code + " error name: " + error.name + "  message " + error.message);
	};	
	console.log("[setHotelDrmForensicData] window.webapis.broadcast object: " + window.webapis.broadcast);
	window.webapis.broadcast.setHotelDrmForensicData("abcdEFGH", onsuccess, onerror);
}

Closed Captions ATSC for Broadcast

You can enables or disables closed captions on ATSC broadcasted content using the Samsung Product TvInfo API. Closed captions are only shown in full-screen mode.

Sample code:

// Call sequence for enabling closed captions in ATSC broadcasted content
var key = webapis.tvinfo.TvInfoMenuKey.CAPTION_ONOFF_KEY;
console.log('key:'+ key);
var value = webapis.tvinfo.TvInfoMenuValue.CAPTION_ON;
console.log('value:'+ value);
var onsuccess = function() {
  console.log("Captions enabled");
};

var onerror = function() {
  console.log("Error has occurred");
};
webapis.tvinfo.setMenuValue(key, value, onsuccess, onerror);

// Call sequence for disabling closed captions in streaming 
var key = webapis.tvinfo.TvInfoMenuKey.CAPTION_ONOFF_KEY;
console.log('key:'+ key);
var value = webapis.tvinfo.TvInfoMenuValue.CAPTION_OFF;
console.log('value:'+ value);
var onsuccess = function() {
  console.log("Captions disabled");
};
var onerror = function() {
  console.log("Error has occurred");
};
webapis.tvinfo.setMenuValue(key, value, onsuccess, onerror);