Video Output Service

Initialization

The TOI interface provides an instance of a ToiVideoOutputConfiguration which represents the state and configuration for all the video outputs on the STB at any given moment. The portal obtains this instance during its initialization:

// get the STB video output configuration
this.videoOutputConfiguration = toi.videoOutputService.getConfiguration();
this.videoOutputConfiguration.addEventListener(
  toi.consts.ToiVideoOutputConfiguration.ON_CONFIGURATION_CHANGED,
  this.onVideoOutputConfigurationChanged);
// ID of HDMI output won't change during runtime
this.hdmiOutputId = this.getHdmiId();

In a similar way to previous examples, the portal registers a listener/callback function (onVideoOutputConfigurationChanged) with the event identifier ON_CONFIGURATION_CHANGED. This is used by the portal to update the UI of changes.

Loading AVM rule sets

Another important part of initializing the video output is loading in an appropriate AVM ruleset. Adaptive Video Mode, or AVM, is a system to automatically scale, translate, letterbox or pillarbox content automatically, based on information in the stream and a set of XML rules. See here for further details on how it works and how the rules are defined. The example portal loads the default rules:

initAdaptiveRuleSets: function() {
  try {
    toi.videoOutputService.loadAdaptiveRuleSets(["KreaTV HD boxing"]);
  }
  catch (e) {
    console.log("Exception when loading AVM RuleSets: " + e);
  }
},

Finding the HDMI output

The TOI API has support for STBs with multiple HDMI and Scart outputs, although no current STB model has more than one of each. To find the current HDMI output, a list of all output IDs is obtained, the outputInfo for each output ID is retrieved, and each outputInfo.connectionType is checked until a HDMI output is found.

getHdmiOutputInfo: function() {
  var outputs = this.videoOutputConfiguration.getOutputs();
  for (var i = 0; i < outputs.length; i++) {
    var outputInfo = this.videoOutputConfiguration.getOutputInfo(outputs[i]);
    if (outputInfo.connectionType ==
        toi.consts.ToiVideoOutputConfiguration.VIDEO_CONNECTION_TYPE_HDMI) {
      return outputInfo;
    }
  }
  return undefined;
},

Once the HDMI output has been found, the ToiHdmiOutputConfiguration.allowedModes property is inspected. This contains a list of those video modes which both the STB can currently output, and the TV reports as acceptable via its EDID. The portal uses this allowedModes list to populate its UI with choices.

A few TVs do not report their acceptable video modes correctly in their EDID. If this is the case, you can ignore the allowedModes and offer any modes from configurableModes or supportedModes.

getAllowedVideoModes: function() {
  var info = this.getHdmiOutputInfo();
  return info.hdmi.allowedModes;
},

Making changes

Changes to the video configuration are implemented using sessions. The intended changes to the output are made to the session using the ToiVideoOutputConfiguationSession::configure() call. The argument to configure() is a ToiConfiguration, an object containing the changes you wish to apply. Several calls to configure() can be made during the session, each specifying different changes. When it is time to apply the collected changes to the video output, call session::apply().

The application of the session is an asynchronous operation, so the portal provides an object containing functions to run when the operation completes:

configureVideoOutput: function(config) {
      var session = toi.videoOutputService.createSession();
  session.configure(this.hdmiOutputId, config);
  session.apply({
    onCompleted: function() {
      ...
      session.releaseInstance();
    },
    onError: function() {
      ...
      session.releaseInstance();
    },
    onProgress: function() {
      ...
    },
    onResult: function() {
      ...
      session.releaseInstance();
    }});
      },

While the async call is in progress, it is not permitted to call any other session methods other than releaseInstance() and cancel()

Once the application has completed, call releaseInstance()

Although this portal only deals with the HDMI output, if you are also handling a Scart output then it is OK to call session.configure() several times, for each output, and then apply() to apply changes to multiple outputs at once.

Once applied, the portals onVideoOutputConfiguration callback function will be triggered, since the configuration changes and a listener was created earlier.

Sometimes it is nice to display a dialog of the form "Press OK if everything looks OK, otherwise reverting in 10 seconds...". This is especially important if you are ignoring the EDID information from a TV, for example. This is easily achieved by popping up a dialog box in the onCompleted callback, before releasing the session instance. Should the timer expire, then call session.revert() and session.apply() to get back to the state when the session was first created (ie before any session.configure() calls were executed). If the user pressed OK, just remove the dialog and release the session instance.