YWE TV Widget Media Player

Yahoo! Widget Engine TV Widget Media Player API Reference

Revision 0.8—12/18/2010

Yahoo! Confidential Copyright ©2007, 2008, 2009, 2010, 2011.

All Rights Reserved

2 YWE TV WIDGET MEDIA PLAYER API REFERENCE—V0.8 YAHOO! CONFIDENTIAL

Legal Notices Copyright © 2007, 2008, 2009, 2010 Yahoo! All rights reserved.

This document contains confidential, proprietary information of Yahoo! Inc. Unauthorized copying, reproduction or disclosure of any portion of the contents of these materials by any means—including printed or duplicated materials, onscreen publication or Web documentation—is expressly forbidden.

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH YAHOO! INC. PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. YAHOO! INC. ASSUMES NO LIABILITY WHATSOEVER, AND YAHOO! INC. DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF YAHOO! INC. PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. UNLESS OTHERWISE AGREED IN WRITING BY YAHOO! INC. THE PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY APPLICATION IN WHICH THE FAILURE OF THE PRODUCT COULD CREATE A SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR.

Yahoo! may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked “reserved” or “undefined.” Yahoo! reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice.

Yahoo! and the Yahoo! logo are trademarks of Yahoo! Inc.

Third party trademarks and images shown are the property of their respective owners. The Media Player API is neither affiliated with nor endorsed by the owners of the third party images, names and logos displayed herein.

Use of this API is subject to the Yahoo! TV Widget Developer Terms of Use license.

YAHOO! CONFIDENTIAL YWE TV WIDGET MEDIA PLAYER API REFERENCE—V0.8 3

Contents

Legal Notices ......................................................................................... 2

Contents................................................................................................. 3

Introduction ........................................................................................... 5

Benefits of Using the KONtx Media Player Interface ......................... 6

Video Encoding Specifications ............................................................ 7 Recommended Video Encoding Parameters ............................................................................ 7 Playing Video in the Widget Development Simulator ................................................................ 9

Media Player Examples....................................................................... 11 Basic Example......................................................................................................................... 11 Extended Example .................................................................................................................. 11 Fast Expiring Content Example............................................................................................... 12 Button Handler Example.......................................................................................................... 13 Playlist Entry Creation Example .............................................................................................. 14 Dynamic Snippet Example ...................................................................................................... 15 View Re-entry Example ........................................................................................................... 16 Aspect Ratio Example ............................................................................................................. 17

Migrating to KONtx.mediaplayer........................................................ 18 Change the Constructor Instantiation to an Object Initialization ............................................. 18 Transform the Events Object to Event Listeners..................................................................... 18 Subscribe the Dispatcher Function to the Media Player Object.............................................. 19 Replace the Video Transport Overlay with the Media Transport Overlay............................... 20 Transform Playlist Arrays to Playlist Objects........................................................................... 20 Set the Viewport Bounds ......................................................................................................... 21 Start the Media Playlist............................................................................................................ 21

KONtx Framework Media Player API ................................................. 22 KONtx.control.MediaTransportOverlay ................................................................................... 22 KONtx.media.Playlist............................................................................................................... 23 KONtx.media.PlaylistEntry ...................................................................................................... 25 KONtx.mediaplayer ................................................................................................................. 26 KONtx.mediaplayer.constants.keys ........................................................................................ 29 KONtx.mediaplayer.constants.states ...................................................................................... 30 KONtx.mediaplayer.constants.streamswitch........................................................................... 30


Media Player Event Handling ............................................................. 32 Media Player Events................................................................................................................ 32 Media Player Event Payload Properties.................................................................................. 37

Introduction Thank you for your interest in using this Media Player API Reference to develop TV Widgets for the Yahoo!® Connected TV platform. Widgets are rich Internet applications that traditionally have been run on the desktop, inside a browser, or inside a mobile device. Through the Yahoo! Connected TV platform, TV Widgets can take advantage of the connectivity, resolution, and computing speed of connected television devices.

TV Widgets enable consumers to engage in a variety of experiences, such as watching videos, tracking their favorite stocks or sports teams, interacting with friends, and staying current on news and information. Viewers are able to use TV Widgets to deepen their enjoyment of the programming they are watching, discover new content and services, and share their favorites with friends and family. TV Widgets can be personalized because they are based upon popular Internet services such as Yahoo! Finance, Yahoo! Flickr, and Yahoo! Sports that viewers have customized for use in their daily lives.

This Media Player API Reference will allow you to develop TV Widgets that can play media on connected consumer electronic devices. These connected consumer electronic devices could include: Digital TVs, set top boxes, DVD players, BlueRay players, DVR’s and other media devices in the home.

The Yahoo! Connected TV platform based on the Yahoo! Widget Engine allows developers to write widgets using JavaScript and XML. Yahoo! also provides consumers with Yahoo!-branded TV Widgets that are customized based on its category-leading Internet services.

TV Widgets rely on the media player implemented on each consumer electronic device for playing audio and video. You will need to work with OEM-specific devices to understand their media player capabilities for audio and video playback.

Regards,

Yahoo!® Connected TV team


Benefits of Using the KONtx Media Player Interface Developers creating media widgets for a connected TV device using the KONtx.mediaplayer interface will be able to deliver the best possible media experience for widescreen televisions and support a design that is independent of a particular brand or manufacturer.

In KONtx Framework version 1.3 and above, the KONtx.mediaplayer interface replaces the KONtx.videoplayer interface, which has been deprecated (see the section on Migrating to KONtx.mediaplayer). The KONtx.mediaplayer interface improves the KONtx Framework media player API based on lessons learned from a number of Yahoo! and third-party implementations of video content widgets.

This media player API is designed to:

• Provide the ability to play video when the widget is not in focus and/or not in fullscreen mode. The widget dock can overlay on top of video playback. The sidebar can be visible while the widget is playing video content. These features are available when supported by the OEM.

• Open up the media player API to handle alternative forms of content, not just video content. Currently audio and video are supported.

• Remove requirements on bandwidth detection and content bitrate and make the best assumptions possible based on the data provided.

• Provide the ability to have late creation of playlist URLs. For content that expires quickly, this allows a TV Widget developer to delay fetching the content URLs from the backend APIs until the very last moment before playback begins.

• Provide a singleton interface to the media player API. • Provide a rich event model to allow a TV Widget developer to attach hooks throughout the

playback life cycle customizing how video is presented to the user. • Remove assumptions on data usage and provide as much detail as possible. For example, the

KONtx.mediaplayer interface provides the time index value in milliseconds as well as seconds, even though it is only updated once per second.

• Refine the media player API based on the most common use cases. This allows easy implementation of basic functionality while retaining flexibility for advanced customization.

• Provide accessor methods to access content and player status at any time. • Replace the KONtx.videoplayer class. All existing widgets that support media playback

should migrate to the KONtx.mediaplayer interface.


Video Encoding Specifications Televisions and devices supporting TV Widgets are highly tuned to decode and display video using optimized hardware. For this reason, the Yahoo! Widget Engine uses the TV/device to fetch, decode, and display video. Performance and media format support differ for each device based on the product decisions made by the manufacturer. Each device provides its own hardware acceleration and proprietary media player.

This section provides the TV Widget video encoding specifications and tips for testing video playback.

Recommended Video Encoding Parameters

To ensure that your TV Widget’s video works on all supported TVs/devices the following encoding specifications have been verified on all Connected TV devices. Deviating from these recommended video encoding parameters may render the video incompatible with deployed or legacy systems.

Streaming Transport

Progressive download over HTTP is supported. Many encoders have an option to enable Internet streaming where the stream is buffered so that playback starts before the whole clip is fully downloaded.

Some device-specific media players support seeking to particular times inside a piece of media by jumping to a relative or absolute offset. Video-seeking and time index changes require a special version of GStreamer (0.10.23) to test on the Simulator, so typically time index testing occurs on the TV/device. To support stopping at a particular point in a video, the event onTimeIndexChanged fires at one second intervals. Currently none of the devices in production support fast forward and rewind over HTTP streams.

Other supported streaming protocols vary by device. Currently one device partner supports MMS and other device partners will be supporting M3U8 and RTSP late in 2010 and early 2011. Existing devices can support a video playlist of URLs, but do not support a continuous open stream. The Yahoo! Widget Engine also supports redirection for the video playlist URLs.

Currently play-listed progressive download is being used for radio widgets. HTTP streaming audio is supported through a fullscreen view where you have exclusive access to the audio pipeline. In fullscreen mode, there is no mixing with any other audio signals. You cannot playback audio (or video) from the sidebar view, as it will be mixed with the audio from the TV Channel. Play-listed progressive download is supported by the current Connected TV devices, but a continuous open stream is not supported. The playlist can be a series of audio files, which play one after the other over an HTTP stream. The majority of our platform partners have all specified they are supporting HTTP live streaming protocols in their 2011 devices. Some partners will come out with updated firmware for existing devices as well. Currently our WDK Development Simulator supports live streaming for your development needs.

Encoding Formats

The following encoding formats have been tested and work across all Connected TV devices:

• MP4/H.264/AAC — Recommended o Container: MP4 (mpeg4)


o Codec: H.264 o Audio: AAC

• WMV9/VC-1/WMA

o Container: WMV9 o Codec: VC-1 o Audio: WMA

Constant/Variable Bit Rate

Optional. Both Constant Bit Rate (CBR) and Variable Bit Rate (VBR) are supported.

Multiple Video Bitrates

Yahoo! recommends choosing one resolution based on your source video’s size, and then encoding your videos in multiple bitrates to support varying connection bandwidth. The KONtx.mediaplayer chooses the best stream given the current connection speed returned from KONtx.speedtest. Support for the following video bitrates is recommended:

• 300 kbps • 700 kbps • 1000 kbps • 2000 kbps

Audio Bitrate

The recommended audio bitrate is 128 kbps for standard bitrate quality.

Resolution

All devices are HD compatible and have a 16:9 aspect ratio. However, the device’s available network bandwidth limits HD resolution to 1280 x 720. PAL resolutions are supported. Depending on your content source, the following pixel resolutions are recommended:

• 640 x 360 — (medium quality 16:9) • 640 x 480 — (medium quality 4:3) • 720 x 480 — (high quality) • 1280 x 720 — (for HD content only)

B-frames

Optional.

Encoding Passes

Optional.

Frame Rate

Optional. Typical frame rates of 29.97 fps for video-based source material and 23.97 fps for film-based source material are supported.


Metadata Formatting

Typically devices cannot buffer more than 100 MB of video. If the video metadata moov atom is at the end of the video, and the video size is larger than the device’s buffer size, the device’s media player will not play the video. Some media players can fetch the video metadata from the end of the file but not all devices support this behavior.

Some encoders, for example Quicktime, have options for Internet streaming which put the video metadata at the front of the file. For Quicktime, the qt-faststart utility rearranges the top-level atoms by shifting the moov atom from the back of the file to the front, and patches the chunk offsets along the way. This utility only operates on uncompressed moov atoms. To move the metadata to the front of the file run: qt-faststart original.mov new_file.mov

Playing Video in the Widget Development Simulator

Video playback behavior and performance in the Widget Development Simulator are not representative of video playback behavior and performance on a TV/device.

The Simulator uses the video playback software library GStreamer to decode and render video. Typically, the software rendering provided by GStreamer is much slower than hardware optimized rasterization. You may find that for certain videos, the audio and video playback is not in sync. This is not representative of the media player behavior on Connected TV devices, but is an artifact of the Simulator’s use of GStreamer. Detailed specifications for each device’s media player implementation do not yet exist. You can go to http://connectedtv.yahoo.com to find out more about Connected TV devices.

If you have trouble testing video in your TV Widget please follow these recommended steps: 1. Use small test files that are less than 20 MB. This is for testing purposes only. 2. Check to see that all the GStreamer packages are installed. Try setting the following

environment variable: export KF_GSTREAMER_USE_ALTERNATIVE_PIPELINE=1

3. Test using the Simulator with the latest KONtx Framework and Yahoo! Widget Engine (via the Latest Production Simulator menu item from the Applications TV Widgets Latest Production menu).

4. Update the Simulator and sample widgets software when updates are available (via the Latest Production Simulator Update Widgets menu item from the Applications→TV Widgets→Latest Production menu).

5. Use the MediaPlayerSample widget (located in $HOME/TVWidgets/Konfabulator-Latest/TV/Widgets/) as a template for using the KONtx.mediaplayer API.

6. Test all video-related code on an actual TV/device. Playback behavior and performance on the Simulator are not representative.

7. Update the firmware of your TV/device. New features may be supported on new device models, for example US and European models vary in format and feature support.

8. Test the media player using the Simulator Console. Launch the Simulator. Let the dock load. Do not interact with any widgets. On the Simulator Console command line, execute the following: tv.mediaPlayer.load("http://mycompany.com/test/test.mp4"); tv.mediaPlayer.play();


You must run the commands above from a fresh start of the Simulator to avoid an inconsistent state. If these commands fail there may be a problem with the media player installation.

9. Test the device's sound server using the Simulator Console. An error message of "Invalid argument" from the gstreamer pipeline may be caused by the sound server. Try setting the sound server to ALSA or PulseAudio instead of auto-detect. Try to playback the stream by entering the following command in the Simulator Console: gst-launch playbin uri=http://mycompany.com/test/test.mp4

10. Test local files. If the stream stalls while buffering it usually indicates an issue with the stream server. In these test cases, store the file locally and use a local uri (for example, file:///noise.mp4).

11. Test playback through the entire video stream so you can test end-of-stream behavior. 12. Research existing video playback sample solutions in the TV Widget Developer Forums

http://developer.yahoo.net/forum/index.php?showforum=91


Media Player Examples The following sections provided guided examples of how to use the KONtx media player API. The following examples are provided:

• Basic Example — initialize, add entry to playlist, and play, no onscreen controls, no handlers • Extended Example — add onscreen controls, add playlist end handler, support multi-bitrates • Fast Expiring Content Example — create a playlist entry subclass for re-fetching expired

content • Button Handler Example — customize transport control buttons and provide a button handler • Playlist Entry Creation Example — review various methods to add a playlist entry to a playlist • Dynamic Snippet Example —create a dynamic snippet for the currently playing video • View Re-entry Example — support re-entering view after dock and sidebar navigation overlaid

on streaming video • Aspect Ratio Example — configure the aspect ratio of video playback for 4:3 content without

stretching

Basic Example

The first step in this basic example is to initialize the media player. Initialization only needs to happen once, but must be performed before any media playback is started or instantiation of any onscreen controls. Initialization sets up the internal KONtx media player state and binds the handlers to the KONtx Framework low level APIs used to perform video playback.

Next, this example creates an instance of the playlist class. This example uses one of the helper methods to add an entry to the playlist by its URL. Each entry in the playlist is a separate video. If you have multiple streams of the same video with different bitrates, use one of the other examples provided to create your playlist entry.

Following the setup of the playlist, the playlist starts playing. Please note, in this basic example, there are no onscreen controls nor any handlers, so the user interaction is simplified.

KONtx.mediaplayer.initialize(); var playlist = new KONtx.media.Playlist(); playlist.addEntryByURL("http://my.video.com/content.mp4"); KONtx.mediaplayer.playlist.set(playlist); KONtx.mediaplayer.playlist.start();

Extended Example

This example shows a more complete basic interaction. It adds an onscreen overlay which shows playback buttons and a progress indicator. It also adds a playlist end handler which returns to the previous view. This example has a playlist with two entries, each playlist entry has multiple URLs for the same video with different bitrates. The KONtx media player will choose which bitrate is appropriate given the consumer’s network bandwidth. KONtx.mediaplayer.initialize(); var overlay = new KONtx.control.MediaTransportOverlay({}).appendTo(this); function playerDispatcher(event) { if(event.type == "onPlaylistEnd") { KONtx.application.previousView();


} } playerDispatcher.subscribeTo(KONtx.mediaplayer, ‘onPlaylistEnd’); var playlist = new KONtx.media.Playlist(); playlist.addEntry(new KONtx.media.PlaylistEntry({ streams: [ { url: "http://my.video.com/content1-300.mp4", bitrate: 300 }, { url: "http://my.video.com/content1-600.mp4", bitrate: 600 }, { url: "http://my.video.com/content1-900.mp4", bitrate: 900 }, ] })); playlist.addEntry(new KONtx.media.PlaylistEntry({ streams: [ { url: "http://my.video.com/content2-300.mp4", bitrate: 300 }, { url: "http://my.video.com/content2-1000.mp4", bitrate: 1000 }, ] })); KONtx.mediaplayer.playlist.set(playlist); KONtx.mediaplayer.setConnectionBandwidth(3000); // use KONtx.speedtest to determine KONtx.mediaplayer.playlist.start();

For those of you used to the KONtx.videoplayer class, you will notice a couple differences. The first thing is that you no longer have to bind to the transport overlay to the video player. Since the KONtx Media Player API is a singleton, there will always be only just one instance, so it can automatically bind itself. You should also notice that instead of making an abstract data structure there are now typed entities with clear definition. As the KONtx.media.Playlist and KONtx.media.PlaylistEntry classes are normal extendable KONtx classes, you can also extend them for more powerful behavior, as shown in the next example.

Fast Expiring Content Example

This media player example handles content URLs which expire quickly. Usually this is not an issue with playlists of only a single entry, but this can potentially be a problem with multiple entry playlists. The KONtx media player API handles expiring content and supports many use cases. This example focuses solely on the custom playlist class and the creation of a playlist. var MyPlaylistEntryClass = new KONtx.Class({ Extends: KONtx.media.PlaylistEntry, config: { videoId: null, }, initialize: function() { this.parent(); this._urlsFetched = false; } streamsReady: function(callback) { if(!this.urlsFetched) { this._callback = callback; this._fetchContentURLs(); return false; } else { return true; } }, _fetchContentURLs: function() { var u = new URL(); u.location = "http://my.website.com/fetchURLs?videoId=" +

this.config.videoId; u.fetchAsync(this._handleResponse); }


_handleResponse: function(u) { var data = JSON.parse(u.response); for each(var content in data) { this.addURL(content.url, content.bitrate); } this._urlsFetched = true; this._callback(); } }); var playlistEntry = new MyPlaylistEntryClass({ videoId: 33 });

The example above overrides the streamsReady() function to handle the custom behavior. First it checks if the URLs have been fetched. As soon as you call the provided callback handler, the KONtx media player checks if the streams are ready again. For even more protection, if you know how long your content lasts before expiring you can store the time they were last fetched. If the content is expired, refetch the URLs when the method streamsReady() is called. If you allow looping or give the consumer the ability to repeat this stream, you need to keep track of the expiration of your content URLs.

Be careful to avoid an endless loop. The KONtx Framework will call streamsReady()again after the callback handler is called and keep doing so until streamsReady() returns true or until you stop calling the callback handler. Please also note, the KONtx media player API will silently fail if your code never calls the callback handler. If you get a permanent failure, the suggested approach is to call the callback and not add any content streams. The KONtx media player API will correctly detect that there are no streams available and fire the appropriate error events.

Button Handler Example

By default, the KONtx.control.MediaTransportOverlay shows a play/pause button, a stop button, and a visual indication of the playback progress. By toggling flags in the configuration, you can enable additional buttons for more advanced functionality. The additional buttons that can be enabled are:

• rewindButton — This button mimics the rewind button on the remote by default. If you override its behavior, you can provide custom handling — for example, increasing the speed increment each time the button is pushed.

• fastforwardButton — This button mimics the fast forward button on the remote by default. If you override its behavior, you can provide custom handling — for example, increasing the speed increment each time the button is pushed.

• forwardseekButton — By default, this button does nothing and requires an implementation. • backwardseekButton — By default, this button does nothing and requires an implementation. • infoButton — By default, this button does nothing and requires an implementation. Typically

this is used to show an overlay with meta information for the currently playing entry. • resizeButton — By default, this button does nothing and requires an implementation.

Typically this is used to toggle the viewport size. To see an example of this being used, see the YouTube widget on Samsung 2009 TVs.

To override any button behavior, you subscribe to the overlay’s onTransportButtonPress event. This event is fired with two event.payload properties: button and action. The button property corresponds to a string of the name of the button pressed. The action property indicates the name of the method to be called on KONtx.mediaplayer.control by default if you choose not to call the method event.preventDefault(). The following table shows a mapping between button names, action values, and KONtx media player control methods invoked by default:


event.payload.button

event.payload.action Default Action Invoked

playpause play KONtx.mediaplayer.control.play()

playpause pause KONtx.mediaplayer.control.pause()

stop stop KONtx.mediaplayer.control.stop()

rewind rewind KONtx.mediaplayer.control.rewind()

fastforward fastforward KONtx.mediaplayer.control.fastforward()

forwardseek null None

backwardseek null None

info null None

resize null None

For the buttons forwardseek, backwardseek, info, and resize, the action property is null. You must provide an event handler with your own implementation as no default action will be taken.

The following example shows the fowardseekButton and provides a handler for it. This example also disables the ability to pause playback via the onscreen control but does not disable pause via the remote control keys: var this.controls.overlay = new KONtx.control.MediaTransportOverlay({ forwardseekButton: true, events: { onTransportButtonPress: function(event) { if(event.payload.button = "forwardseek") { KONtx.mediaplayer.control.seek(30); } else if(event.payload.button = "pause") { event.preventDefault(); } } } }).appendTo(this);

Playlist Entry Creation Example

The following example shows several ways to add a KONtx.media.PlaylistEntry to a KONtx.media.Playlist: var playlist = new KONtx.media.Playlist(); playlist.addEntryByURL(url, bitrate, startIndex); playlist.addEntry(new KONtx.media.PlaylistEntry({ url: "http://my.video.com/content.mp4", bitrate: 300 })); var entry = new KONtx.media.PlaylistEntry(); entry.addURL(url, bitrate); entry.addURL(url2, bitrate2); playlist.addEntry(entry);


EventHandlers.handlerPlayerEvent.subscribeTo(KONtx.mediaplayer, ['onStateChange'], EventHandlers);

See the JavaScript file now_playing_snippet.js in the MediaPlayerSample widget as a template for this dynamic snippet view.

View Re-entry Example

On OEM platforms that allow dock overlay, special considerations must be made to handle the new widget view lifecycle. There are three new interaction cases that need to be considered:

1. Consumer presses the WIDGETS key on the remote control and brings up the dock while playing your content. The user then dismisses the dock via either the RED key or by pressing the WIDGETS key again.

2. Consumer presses the WIDGETS key on the remote control and selects your “now playing” snippet to return to the currently playing video.

3. Consumer presses the WIDGETS key on the remote control and loads up the sidebar of your widget again. They then drill down to a specific content item and play it, or they pick the same content they are currently playing.

To handle these cases, you must use code similar to the MediaPlayerSample widget code. As you can see in that code (duplicated below), inside the updateView() method there is a call to this._handlePlaylistUpdate() which is a custom method on the view class used to determine if the consumer selected content that is already playing. The first thing you do in that method is to check if any video is already playing. If not, then you know you need to start playing and call the this._startPlaylist() custom view method.

If video is already playing, you need to do checks to cover all use cases above. The first thing you check in this code is to see if you were provided a playlistID in loading the view. In this example, the parameter this.persist.playlistID is set in the MediaPlayer sample widget’s sidebar view. Buttons in the sidebar view call KONtx.application.loadView() with the playlistID as a persistent parameter accessible when the next view loads. In your implementation you need to handle setting the playlistID for this case.

If no playlistID exists, then that means you are in interaction case 1 or case 2 above. Since you now know you are already playing the right content, then you simply return immediately as nothing else needs to be done. If you do actually have a playlistID provided, then you check that against the currently playing playlist and see if they match. If they do, again, return immediately. If neither of those matches were met, you then know you have a new playlist to start and you call this.startPlaylist()with the given playlistID.

The following example shows the updateView() method from the MediaPlayer sample widget handling re-entry into the fullscreen player view: updateView: function() { this._handlePlaylistUpdate(this.persist.PlaylistID); }, _handlePlaylistUpdate: function(playlistID) { if(KONtx.mediaplayer.isPlaylistEntryActive) { if(!playlistID) { // no new playlist to play, so keep playing what we already are playing return; } if(playlistID == KONtx.mediaplayer.playlist.get().PlaylistID) { // asked to play the same playlist already playing, so keep playing it


return; } } // Otherwise, we need to start this new playlist this._startPlaylist(playlistID); },

Aspect Ratio Example

The default viewport configuration for the media player has the (x,y) position at (0,0) and sets the width and height of the viewport to 1920 x 1080. To use the default viewport configuration for the media player use the following methods:

KONtx.mediaplayer.setViewportBounds(KONtx.mediaplayer.getDefaultViewportBounds());

The default viewport will stretch 4:3 content during playback on some devices. The video playback on the Simulator is not intended to be an indicator of video playback on the Connected TV device. If you want to configure the aspect ratio of video playback for 4:3 content without stretching you can set the viewport properties as follows:

var bounds = { x: 333, y: 333, width: 640, height: 480 }; KONtx.mediaplayer.setViewportBounds(bounds);

To have video playback within a graphical boundary, for example letterboxing the video, you should create a background image with a transparent area. The graphical plane sits on top of the video plane, so the video will show through the transparent area in your graphical plane’s background image.


Migrating to KONtx.mediaplayer This section outlines the steps to migrate a widget from using the older KONtx.videoplayer interface to using the newer KONtx.mediaplayer interface. Migrating to the new interface is not mandatory, but highly encouraged. Your widgets using the older interface will continue to work. The new KONtx Framework (1.3 and above) with the new KONtx.mediaplayer interface is backward compatible and includes the older KONtx.videoplayer interface.

The benefits of using the new KONtx.mediaplayer interface are numerous and outlined above, in the section: Benefits of Using the KONtx Media Player Interface.

Which interface you choose should be dependent on the stability and complexity of your video player, and how far you have deviated from the standard video player interface. In Yahoo!’s experience, it has been much faster to migrate to, and to fix bugs against, the new KONtx.mediaplayer interface. If you are already far down the path with the older interface, go ahead and finish up the widget and submit it to Yahoo! for QA review.

The examples included below are simplified to help you migrate quickly to the new media player. If you have implemented a lot of customization on top of the older interface, additional work may be required.

If you are implementing the media player for the first time, or you are willing to start over, see the section on Media Player Examples above and use the MediaPlayerSample widget (located in the WDK in the directory $HOME/TVWidgets/Konfabulator-Latest/TV/Widgets/) as a template. In order to use the KONtx.mediaplayer interface, your widget must use the KONtx Framework version 1.3 and above.

Change the Constructor Instantiation to an Object Initialization

In your fullscreen view that implements the deprecated video player, find the JavaScript where KONtx.videoplayer is instantiated. It should be similar to the following: this.player = new KONtx.videoplayer({ events: { // … Your event handlers } });

In the old interface, you created the player object by instantiating the KONtx.videoplayer class. In the new interface, the media player is a global object that you initialize by calling its initialize() method. Change your player object instantiation to the following call: KONtx.mediaplayer.initialize();

Transform the Events Object to Event Listeners

In the old interface, events are subscribed to in the KONtx.videoplayer constructor within the events object. In the new interface, a listener is created for each event, and a dispatcher function subscribes to the media player object. These event listeners exist outside of the media player object.

The following example will show how to transform a video player events object into media player event listeners. Here is a simple video player constructor: this.controls.overlay = new KONtx.control.VideoTransportOverlay().appendTo(this); this.player = new KONtx.videoplayer( { events: {


onPlaylistEnd: function(event) { KONtx.application.previousView(); }, onStateChange: function(event) { if (event.payload.newState == event.payload.videoplayer.states.STOP) { KONtx.application.previousView(); } if (event.payload.newState == event.payload.videoplayer.states.ERROR || event.payload.newState == event.payload.videoplayer.states.UNKNOWN) { errorDialog.show() } } } }).attachAccessory(this.controls.overlay);

The first step is to transform each event handler function into a switch case in a dispatcher function. Note this dispatcher function name starts with an underscore (_) to indicate that it is a private method in the fullscreen media player view—for example: _playerDispatcher: function (event) { switch (event.type) { case 'onPlaylistEnd': KONtx.application.previousView(); break; case 'onStateChange': if (event.payload.newState == KONtx.mediaplayer.constants.states.STOP) { KONtx.application.previousView(); } if (event.payload.newState == KONtx.mediaplayer.constants.states.ERROR || event.payload.newState == KONtx.mediaplayer.constants.states.UNKNOWN) { errorDialog.show() } break; case 'onStreamLoadError': errorDialog.show(); break; default: break; } },

Most of the older video player event handlers map directly to the new media player handlers. See the section on Media Player Events below for more details.

Subscribe the Dispatcher Function to the Media Player Object

Now that the event listeners are encapsulated in a single dispatcher function, the next step is to subscribe this dispatcher function to the media player object so it can listen for events—for example: _registerHandlers: function () { if (this._boundPlayerHandler) { this._unregisterHandlers(); } this._boundPlayerHandler = this._playerDispatcher.subscribeTo(KONtx.mediaplayer, ['onStateChange', 'onPlaylistEnd', 'onStreamLoadError'], this); },

When your fullscreen view is no longer displayed you should avoid catching media player events. It is important to make sure the handlers are unsubscribed when the view is unloaded. Unsubscribe from the media player object as follows:


_unregisterHandlers: function () { if (this._boundPlayerHandler) { this._boundPlayerHandler.unsubscribeFrom(KONtx.mediaplayer, ['onStateChange', 'onPlaylistEnd', 'onStreamLoadError']); this._boundPlayerHandler = null; } },

Call _registerHandlers()in your player view’s updateView() method and call _unregisterHandlers()in your player view’s hideView() method.

Replace the Video Transport Overlay with the Media Transport Overlay

The transport overlay user interface control provides optional media playback buttons and a visual indication of the playback progress. In the deprecated video player interface, this control is implemented through the KONtx.control.VideoTransportOverlay class, which is an accessory to the KONtx.videoplayer class, and must be attached to an instantiation of the video player.

In the new interface, the KONtx.control.MediaTransportOverlay class is not attached to the KONtx.mediaplayer object but accesses the global KONtx.mediaplayer object directly. If you have not performed any customization on this control, simply replace the video transport overlay instantiation with the following: this.controls.overlay = new KONtx.control.MediaTransportOverlay().appendTo(this);

Since the KONtx.mediaplayer is a singleton, there will always be just one instance, so it can automatically bind itself. Attaching the accessory to the media player object is no longer necessary.

Transform Playlist Arrays to Playlist Objects

With the new media player interface, playlists are full objects instead of just arrays. Playlist objects can be instantiated and populated with multiple streams of media, supporting varying connection speeds—for example. var playlist = new KONtx.media.Playlist(); playlist.addEntry(new KONtx.media.PlaylistEntry({ streams: [ { url: "http://my.video.com/content1-300.mp4", bitrate: 300 }, { url: "http://my.video.com/content1-600.mp4", bitrate: 600 }, { url: "http://my.video.com/content1-900.mp4", bitrate: 900 }, ] })); playlist.addEntry(new KONtx.media.PlaylistEntry({ streams: [ { url: "http://my.video.com/content2-300.mp4", bitrate: 300 }, { url: "http://my.video.com/content2-1000.mp4", bitrate: 1000 }, ] }));

The KONtx.media.Playlist and KONtx.media.PlaylistEntry classes are normal extendable KONtx classes that you can extend for more powerful behavior, as shown in the Fast Expiring Content Example above.


Set the Viewport Bounds

The default viewport configuration for the media player has the (x,y) position at (0,0) and sets the width and height of the viewport to 1920 x 1080. To use the default viewport configuration for the media player use the following methods in your views updateView() method:

KONtx.mediaplayer.setViewportBounds(KONtx.mediaplayer.getDefaultViewportBounds());

See the Aspect Ratio Example above to configure the aspect ratio of video playback for 4:3 content without stretching.

Start the Media Playlist

At this point you can set the playlist and play the media—for example: KONtx.mediaplayer.playlist.set(playlist); KONtx.mediaplayer.setConnectionBandwidth(3000); // use KONtx.speedtest to determine KONtx.mediaplayer.playlist.start(); This completes the simple migration from KONtx.videoplayer to KONtx.mediaplayer. To support additional features see the Media Player Examples section above.


KONtx Framework Media Player API This section describes the KONtx.mediaplayer API reference for TV Widgets.

KONtx.control.MediaTransportOverlay Toolbox media player transport keys user interface

The KONtx.control.MediaTransportOverlay class is an accessory to the KONtx.mediaplayer class used to create the fullscreen transport keys user interface. This control is used to provide an onscreen transport overlay with a progress indicator and a number of optional buttons to control media playback. Its visual appearance is most relevant to a video fullscreen player, but could also be used with audio playback when combined with other visual playback elements. This control pairs up with the KONtx.mediaplayer and not the KONtx.videoplayer (use KONtx.control.VideoTransportOverlay instead).

By default, the KONtx.control.MediaTransportOverlay shows a play/pause button, a stop button, and a visual indication of the playback progress. By toggling flags in the configuration, you can enable additional buttons for more advanced functionality.

Extends KONtx.element.Container

Example var this.controls.overlay = new KONtx.control.MediaTransportOverlay({ forwardseekButton: true, events: { onTransportButtonPress: function(event) { if(event.payload.button = "forwardseek") { KONtx.mediaplayer.control.seek(30); } else if(event.payload.button = "pause") { event.preventDefault(); } } } }).appendTo(this);

Properties

Property Type Description

backwardseekButton Boolean Indicates if a backward seek button should be included in the transport keys. Default value is false. By default, this button does nothing and requires an implementation.

fadeTimeout int Number of seconds the user interface remains on the screen before fading out. Default value is 10. Any keypress on the remote control causes the onscreen controls to be shown.

fastforwardButton Boolean Indicates if a fast forward button should be included in the transport keys. Default value is false. This button mimics the fast forward button on the remote by default. If you override its behavior, you can provide custom handling — for example, increasing the speed increment each time the button is pushed.



forwardseekButton Boolean Indicates if a forward seek button should be included in the transport keys. Default value is false. By default, this button does nothing and requires an implementation.

infoButton Boolean Indicates if an information button should be included in the transport keys. Default value is false. By default, this button does nothing and requires an implementation. Typically this is used to show an overlay with meta information for the currently playing entry.

playButton Boolean Indicates if a play button should be included in the transport keys. Default value is true.

resizeButton Boolean Indicates if resize button should be included in the transport keys. Default value is false. By default, this button does nothing and requires an implementation. Typically this is used to toggle the viewport size. To see an example of this being used, see the YouTube widget on Samsung 2009 TVs. The resize button appears on the right side of the progress indicator unlike other buttons.

rewindButton Boolean Indicates if a rewind button should be included in the transport keys. Default value is false. This button mimics the rewind button on the remote by default. If you override its behavior, you can provide custom handling — for example, increasing the speed increment each time the button is pushed.

stopButton Boolean Indicates if a stop button should be included in the transport keys. Default value is true.

Method Boolean focus();

Tells the control to focus itself. void hide();

Prevents the media transport overlay from being shown even if the consumer presses a key on the remote control.

void resetState();

Resets the overlay for the transport keys. The state is set to pause. Time index and duration are set to 0. The progress bar is reset to the start and the interval text is set to 00:00:00.

void show();

Re-enables the media transport overlay to be shown when the consumer presses a key on the remote control.

KONtx.media.Playlist Toolbox media player playlist

The KONtx.media.Playlist class provides a list of media entries for the KONtx Framework media player.


Example KONtx.mediaplayer.initialize(); var playlist = new KONtx.media.Playlist(); playlist.addEntryByURL("http://my.video.com/content.mp4"); var url = "http://my.video.com/content2.mp4"; var bitrate = 300; var startIndex = 25; playlist.addEntryByURL(url, bitrate, startIndex); playlist.addEntry(new KONtx.media.PlaylistEntry({ url: "http://my.video.com/content3.mp4", bitrate: 300 })); var entries = []; entries.push(new KONtx.media.PlaylistEntry({ url: "http://my.video.com/cnt5.mp4" })); entries.push(new KONtx.media.PlaylistEntry({ url: "http://my.video.com/cnt6.mp4" })); playlist.addEntries(entries); KONtx.mediaplayer.playlist.set(playlist); KONtx.mediaplayer.setConnectionBandwidth(3000); // use KONtx.speedtest to determine KONtx.mediaplayer.playlist.start();

Properties


autostart Boolean Deprecated property. The default value is false.

forcePlay Boolean Set this to true to force playback of the lowest bitrate stream, even if the consumer’s bandwidth is detected as being lower than the lowest bitrate stream provided. An error event is returned from the KONtx media player if forcePlay is set to false and the consumer’s bandwidth tests lower than the lowest bitrate stream provided. The default value is true.

repeatAll Boolean Enables looping of the playlist when the playback finishes for the last entry in the playlist. If set to true the looping occurs, if set to false, playback will stop at the last entry of the playlist. The default value is false.

Methods KONtx.media.Playlist addEntries(Array entries);

Adds multiple playlist entries to the playlist. The entries parameter is an Array of KONtx.media.PlaylistEntry objects. Returns the updated playlist.

KONtx.media.Playlist addEntry(KONtx.media.PlaylistEntry entry);

Adds the single given entry to the playlist. Calls the addEntries([entry]) method and returns the updated playlist.

KONtx.media.Playlist addEntryByURL(string url, int bitrate, int startIndex);

Allows you to add an entry using the url when all you have is a single bitrate to playback for each playlist entry. Returns the updated playlist.

void clearEntries();

Empties the playlist entries array. void removeEntry(int index);

Removes the specified playlist entry with the index you provide.


KONtx.media.PlaylistEntry Toolbox media player playlist entry

The KONtx.media.PlaylistEntry class provides a playlist entry for the KONtx Framework media player. The playlist entry configuration allows for providing the following instantiation options:

• A url and bitrate. • Just a url. • An array of streams. Each element in the array is an object with a url property and a bitrate

property. If the bitrate is not provided for a stream but is provided in the main config, then all streams without a provided bitrate inherit this value.

• A url and an array of streams. Both will be appended together. • Nothing on instantiation, then calling addURL() to add an array of streams before adding the

entry to the playlist.

If you provide multiple streams and do not provide multiple bitrates, then the stream that is selected will be non-deterministic. If you do provide multiple bitrates, but do not provide a connection bandwidth to the media player, then the highest bitrate stream will be selected. If you do provide a bitrate and a connection bandwidth to the media player, then the stream selected will be the fastest one supported by the consumer’s current connection speed.

Example KONtx.mediaplayer.initialize(); var playlist = new KONtx.media.Playlist(); var url2 = "http://my.video.com/content3.mp4"; var url3 = "http://my.video.com/content4.mp4"; var bitrate2 = 600; var bitrate3 = 900; var entry = new KONtx.media.PlaylistEntry(); entry.addURL(url2, bitrate2); entry.addURL(url3, bitrate3); playlist.addEntry(entry); var entries = []; entries.push(new KONtx.media.PlaylistEntry({ url: "http://my.video.com/cnt5.mp4" })); entries.push(new KONtx.media.PlaylistEntry({ url: "http://my.video.com/cnt6.mp4" })); playlist.addEntries(entries); playlist.addEntry(new KONtx.media.PlaylistEntry({ streams: [ { url: "http://my.video.com/content1-300.mp4", bitrate: 300 }, { url: "http://my.video.com/content1-600.mp4", bitrate: 600 }, { url: "http://my.video.com/content1-900.mp4", bitrate: 900 }, ] })); playlist.addEntry(new KONtx.media.PlaylistEntry({ streams: [ { url: "http://my.video.com/content2-300.mp4", bitrate: 300 }, { url: "http://my.video.com/content2-1000.mp4", bitrate: 1000 }, ] })); KONtx.mediaplayer.playlist.set(playlist); KONtx.mediaplayer.setConnectionBandwidth(3000); // use KONtx.speedtest to determine KONtx.mediaplayer.playlist.start();


Properties


url string The media URL. Default value is null.

bitrate int The bitrate of the video. Default value is null.

startIndex int The time index to start playback of the video. Default value is null.

streams Array An array of objects with a string url property and an integer bitrate property. If the bitrate is not provided for a stream item in the array but is provided in the main configuration KONtx.media.PlaylistEntry.bitrate, then all stream items in the streams array without a bitrate inherit this value. If a stream item in the array does not have a url, the error "Invalid stream: must at minimum provide a URL" is thrown.

Methods KONtx.media.PlaylistEntry addURL(string url, int bitrate);

Creates a stream from the given url and bitrate and adds it to the streams array for this entry. If the url is null, the error "Invalid stream: must at minimum provide a URL" is thrown. Returns the updated entry.

Boolean streamsReady(function callback);

This method is called by the KONtx media player to see if the streams are ready before fetching them. If you have streams which expire quickly and need to be refetched immediately before playback, override this method, save the callback passed in as the parameter and return false. Once your streams are ready, call the callback handler and the media player will resume. Please note, this method will be called again after you call the callback handler, so you need to return true the second time through the method or you will create an endless loop of fetching fresh URLs.

KONtx.mediaplayer Toolbox media player

The KONtx.mediaplayer interface defines the KONtx Framework media player API.

Example KONtx.mediaplayer.initialize(); var playlist = new KONtx.media.Playlist(); playlist.addEntryByURL("http://my.video.com/content.mp4"); KONtx.mediaplayer.playlist.set(playlist); KONtx.mediaplayer.playlist.start();


Properties


debugInternals Object Normally all of the inner workings of the API are enclosed behind a public/private API separation. The debugInternals property can be used via the console to gain access to the complete “private” scope. Do not access this method in your TV Widget code.

isPlaylistEntryActive Boolean Boolean indicating if the current playlist entry is in one of the active states. These states are currently defined as PLAY, PAUSE, FASTFORWARD, REWIND, BUFFERING, or INFOLOADED. This state list is subject to change.

playlist.currentEntry KONtx.media.Playlist

The currently selected playlist entry if one is set.

playlist.currentIndex Object Object with entry and stream properties. The entry property is the zero-based index of the currently selected playlist entry (if one is selected). The stream property is the zero-based index of the currently selected stream in the playlist entry (if one is selected).

tvapi.activeControl TVControl The active TVControl object. Not for general use. Read-only.

tvapi.activeInput TVNetworkInput The active TVNetworkInput object. Not for general use. Read-only.

tvapi.activeOutput TVOutput The active TVOutput object. Not for general use. Read-only.

tvapi.activePath TVPath The active TVPath object. Not for general use. Read-only.

tvapi.currentHTTPErrorCode int The HTTP error code as returned by the tvapi.activeInput or -1 if no error. Read-only.

tvapi.currentMediaDuration int The length of the currently playing content in milliseconds. Read-only.

tvapi.currentPlayerState int The current player state to be compared against the constants.states enumeration. Read-only.

tvapi.currentTimeIndex int The current time index of the playing content in milliseconds. Read-only.

Methods void control.fastforward(int increment);


Tells the media player to fast forward the current content at the specified increment if supported by the media player. Supported increments are 2, 4, 8, and 16. Anything else will be rounded up or limited to the nearest supported value. Not all OEMs support this operation.

void control.pause();

Pauses the currently playing content. void control.play();

Causes play to be called on the OEM-specific player. Only call this method if you called pause, use playlist.start() instead to start initial playback.

void control.rewind(int increment);

Tells the player to rewind the current content at the specified increment if supported by the media player. Supported increments are 2, 4, 8, and 16. Anything else will be rounded up or limited to the nearest supported value. Not all OEMs support this operation.

void control.seek(float offset, Boolean absolute);

Tells the media player to seek to the specified offset in seconds. If true is passed as the absolute parameter, then the offset is considered to be an absolute offset rather than a relative offset from the current playback position.

void control.stop();

Stops playback of the currently playing content. void control.streamswitch(KONtx.mediaplayer.constants.streamswitch method, Object config);

Tells the media player to perform a stream switch to an alternate stream for the same entry using the specified algorithm identified by the method parameter. The config parameter changes based on the method used. The KONtx.mediaplayer.constants.streamswitch.BANDWIDTH algorithm is used to provided an updated connection bitrate and margin. If you choose this option, the config parameter is an object with bitrate and margin properties. The config.bitrate property is the bitrate of the consumer’s connection as tested through KONtx.speedtest. The config.margin property is the margin factor to apply to the consumer’s bandwidth. Valid values are between 0 and 1. The config.margin property defaults to 1 or what was previously set if not provided. See the method setConnectionBandwidth() for more details.

The KONtx.mediaplayer.constants.streamswitch.INDEX_CHANGE algorithm is used to increase or decrease the selected stream by a specified amount. If you choose this option, the config parameter is an object with direction and offset_amount properties. The possible values for config.direction are String values up or down. The default value is down. The config.offset_amount property is the amount to shift up or down. If you provide a config.direction but not a config.offset_amount, then the config.offset_amount is defaulted to 1.

Object getDefaultViewportBounds();

Returns a bounds object with properties the same as setViewportBounds(). Currently all OEMs return {x:0, y:0, width:1920, height:1080}. The values for the returned object are subject to change as new OEM platforms are added. Always check for the proper values.

void initialize();

Initializes the KONtx Media Player. Initialization only needs to happen once, but must be performed before any media playback is started.

KONtx.media.Playlist playlist.get();

Returns the playlist which is currently set on the media player.


void playlist.loadEntry(int entry);

Tells the media player to load and play the specified zero-based entry in the playlist. void playlist.nextEntry();

Tells the media player to load and play the next entry in the playlist. void playlist.previousEntry();

Tells the media player to load and play the previous entry in the playlist. void playlist.set(KONtx.media.Playlist playlist);

Takes a playlist and saves it in the media player for usage. void playlist.start();

Starts the playlist which is currently set on the media player. void setConnectionBandwidth(int bitrate, float margin);

Sets the connection bitrate to the specified value. If margin is also provided (defaults to 1), then it is applied to the bitrate before using the bitrate to select a stream. If bitrate = 2000 and margin = 0.8, then that means the KONtx media player will not select any stream greater than 1600. Use this to provide “head room” to help eliminate buffering attempts caused by the consumer using their internet connection temporarily for other things.

void setViewportBounds(int x, int y, int width, int height);

Sets the viewport bounds to the specified values. The parameter x is the horizontal offset of the top left corner of the viewport. The parameter y is the vertical offset of the top left corner of the viewport. The parameter width is the width of the viewport. The parameter height is the height of the viewport. This method also accepts a single parameter in the format of the returned Object from the method getDefaultViewportBounds(), for example: KONtx.mediaplayer.setViewportBounds(KONtx.mediaplayer.getDefaultViewportBounds());

KONtx Media Player Enumeration Constants The following section describes the KONtx Media Player enumeration constants.

KONtx.mediaplayer.constants.keys Toolbox media player remote control key enumeration constants

When using enumeration constants always use the keys and do not depend on the value not changing. The table below describes the enumeration constants for the possible remote control keys controlling the OEM-specific media player.

Constant Description

FASTFORWARD Fast forward remote control key.

PAUSE Pause remote control key.

PLAY Play remote control key.

REWIND Rewind remote control key.

STOP Stop remote control key


KONtx.mediaplayer.constants.states Toolbox media player states enumeration constants

When using enumeration constants always use the keys and do not depend on the value not changing. This list may change as new OEM partners are added. The table below describes the enumeration constants for the possible OEM-specific media player states. Not all media player states are used on all platforms.


BUFFEREMPTY The buffer is completely empty. The media may pause because there is no data in the buffer. Rebuffering should begin.

BUFFERING The video file is currently being buffered. The OEM-specific player should buffer data as soon as a stream is created or if an existing stream is switched. The property KONtx.mediaplayer.isPlaylistEntryActive returns true when the OEM-specific media player is in this state.

EOF The OEM-specific media player has reached the end of the media file.

ERROR An error was received from the OEM-specific media player.

FASTFORWARD The video is moving fast forward. The property KONtx.mediaplayer.isPlaylistEntryActive returns true when the OEM-specific media player is in this state.

INFOLOADED Information has been loaded, including header file information and media data. The property KONtx.mediaplayer.isPlaylistEntryActive returns true when the OEM-specific media player is in this state.

INIT The OEM-specific media player is initializing.

PAUSE The video is paused. The property KONtx.mediaplayer.isPlaylistEntryActive returns true when the OEM-specific media player is in this state.

PLAY The media is playing. The property KONtx.mediaplayer.isPlaylistEntryActive returns true when the OEM-specific media player is in this state.

REWIND The video is rewinding. The property KONtx.mediaplayer.isPlaylistEntryActive returns true when the OEM-specific media player is in this state.

STOP The video is stopped.

UNKNOWN The OEM-specific media player state is unknown.

KONtx.mediaplayer.constants.streamswitch Toolbox media player enumeration constants

When using enumeration constants always use the keys and do not depend on the value not changing. The table below describes the enumeration constants for the possible stream switch algorithms.



BANDWIDTH The BANDWIDTH stream switching algorithm is used when the KONtx.mediaplayer.control.streamswitch(KONtx.mediaplayer.constants.streamswitch.BANDWIDTH, config) method is called. This algorithm allows you to provide an updated connection bitrate config.bitrate and an updated connection margin config.margin and then allows the media player to choose the best stream. If you choose this option, the config parameter is an object with bitrate and margin properties. The bitrate property is the bitrate of the consumer’s connection as tested through KONtx.speedtest. The margin property is the margin factor to apply to the consumer’s bandwidth. Valid values are between 0 and 1. The margin property defaults to 1 or what was previously set if not provided. See the method setConnectionBandwidth() for more details.

INDEX_CHANGE The INDEX_CHANGE stream switching algorithm is used when the KONtx.mediaplayer.control.streamswitch(KONtx.mediaplayer.constants.streamswitch.INDEX_CHANGE, config) method is called. This algorithm allows you to increase or decrease the selected stream by a specified amount. The config.direction property is the direction to change. Possible valid values for direction are String values up and down, the default value is down. The config.offset_amount property is the bitrate increment to increase or decrease. This offset value can be more than the available stream bitrate. If you provide a config.direction but not an config.offset_amount, then the config.offset_amount is defaulted to 1.


Media Player Event Handling The KONtx.mediaplayer interface fires the following events to communicate the KONtx media player status with your widget.

Media Player Events

The following events are sent by the KONtx.mediaplayer interface. Event-specific properties included in the event payload object are described below:

Event Description

onConnectionBandwidthChanged Fired when the connection bandwidth is changed for the KONtx media player, for example, it is fired when you call the method KONtx.mediaplayer.setConnectionBandwidth(). The event.payload.bandwidth.previous.bitrate property is the previous bitrate. The event.payload.bandwidth.previous.margin property is the previous margin. The event.payload.bandwidth.current.bitrate property is the current bitrate. The event.payload.bandwidth.current.margin property is the current margin.

onControlFastForward Fired when KONtx.mediaplayer.control.fastforward() is called. Calling the method event.preventDefault() will prevent the fast forward action from occurring. The event.payload.increment property is the speed increment as passed in to the fast forward method.

onControlPause Fired when KONtx.mediaplayer.control.pause() is called. Calling the method event.preventDefault() will prevent the pause from occurring.

onControlPlay Fired when KONtx.mediaplayer.control.play() is called. Calling the method event.preventDefault() will prevent the play action from occurring.

onControlRewind Fired when KONtx.mediaplayer.control.rewind() is called. Calling the method event.preventDefault() will prevent the rewind action from occurring. The event.payload.increment property is the speed increment as passed in to the rewind method.

onControlSeek Fired when KONtx.mediaplayer.control.seek() is called. Calling the method event.preventDefault() will prevent the seek action from occurring. The event.payload.offset property is the offset in seconds as provided to the KONtx.mediaplayer.control.seek() method as a float. The event.payload.absolute property is a Boolean of whether the offset is an absolute position (true) or is relative to the current playback position (false).


Event Description

onControlStop Fired when KONtx.mediaplayer.control.stop() is called. Calling the method event.preventDefault() will prevent the stop action from occurring.

onControlStreamSwitch Fired when KONtx.mediaplayer.control.streamswitch() method is called. Calling the method event.preventDefault() will prevent the stream switch action from occurring. The event.payload.streamswitch.method property is the stream switch algorithm being used. The possible enumeration values are: KONtx.mediaplayer.constants.streamswitch.INDEX_CHANGE to shift bitrate up and down by a predetermined amount and KONtx.mediaplayer.constants.streamswitch.BANDWIDTH to specify a new bitrate and margin and to allow the media player to choose the best stream. The event.payload.streamswitch.config.direction property is the direction to change when the INDEX_CHANGE method is used. Possible valid values for direction are up and down, the default value is down. The event.payload.streamswitch.config.offset_amount property is the bitrate increment to increase or decrease when the INDEX_CHANGE method is used. This offset value can be more than the available stream bitrate. If you provide a direction but not an offset amount, then the offset amount is defaulted to 1. The event.payload.streamswitch.config.bitrate property is the specified bitrate when the BANDWIDTH method is used. The event.payload.streamswitch.config.margin property is the specified margin when the BANDWIDTH method is used.

onConvertToSpeed Fired when an increment provided to rewind or fast forward is converted into a playback speed. If the increment is identical to 0, then the speed is set to 1. If the increment is not a valid number or is less than or equal to 2, then the speed is set to 2. If the increment is greater than 2 and less than or equal to 4, then the speed is set to 4. If the increment is greater than 4 and less than or equal to 8, then the speed is set to 8. If the increment is greater than 8, then the speed is set to 16.

onFastForwardRemoteKeyPress Fired when the fast forward key is pressed on the remote control. No action is performed with this method. You must subscribe to this event and act on it for the key to respond. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onFindBestStream Fired when the best stream from the list of available streams is being selected for this playlist entry. Calling the method event.preventDefault() will prevent the KONtx media player from attempting to find a stream.


Event Description

onLoadNextPlaylistEntry Fired when the playlist method KONtx.mediaplayer.playlist.nextEntry() is called. Calling the method event.preventDefault() will prevent the next entry from loading.

onLoadPlaylistEntry Fired when a new playlist entry is loaded. Calling the method event.preventDefault() will prevent loading and playback from starting on this new entry. The event.payload.index property is the zero-based index of the playlist entry to be loaded.

onLoadPreviousPlaylistEntry Fired when the playlist method KONtx.mediaplayer.playlist.previousEntry() is called. Calling the method event.preventDefault() will prevent the previous entry from loading.

onNewStreamSelected Fired when a new stream of a playlist entry is selected. This could be fired on initial playback or after a stream switch has occurred.

onPauseRemoteKeyPress Fired when the pause key is pressed on the remote control. To prevent the pause operation from being performed, subscribe to this event and call the method event.preventDefault() when it is fired. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onPlaybackBuffering Fired when the media player starts buffering or rebuffering the current stream. Calling the method event.preventDefault() prevents the wait indicator display.

onPlaylistChange Fired when the playlist is changed. Calling the method event.preventDefault() will prevent the playlist from being changed to the newly provided playlist. The event.payload.playlist is the playlist being set.

onPlaylistEnd Fired when the end of the playlist is reached.

onPlaylistRepeat Fired when the media player is repeating playback of the playlist if it has the KONtx.media.Playlist.repeatAll flag set. Calling the method event.preventDefault() will prevent restarting the playlist at the beginning. This does not fire an onPlaylistEnd event if the default is prevented.

onPlayPlaylistEntry Fired when beginning playback of a new playlist entry. This is one of the first events fired when playback is started on a new entry. Calling the method event.preventDefault() will prevent playback from starting.


Event Description

onPlayRemoteKeyPress Fired when the play key is pressed on the remote control. To prevent the play operation from being performed, subscribe to this event and call the method event.preventDefault() when it is fired. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onProcessPlaylistEntry Fired when a new playlist entry is picked to play. Calling the method event.preventDefault() will prevent playback from starting. The event.payload.entry is the playlist entry picked to start playback.

onRemoteKeyPress Fired when any play control key is pressed on the remote control. If you call the method event.preventDefault() on this event, the specialized events for specific play control keys below will not be fired. This is a good way to handle all keys with a single handler. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onResetBufferingCount Fired when the buffering count is reset. This is typically done when a new playlist entry is started. Calling the method event.preventDefault() will prevent the buffering count from being reset. The event.payload.bufferingCount property is the number of buffering attempts before the reset is performed.

onRewindRemoteKeyPress Fired when the rewind key is pressed on the remote control. No action is performed with this method. You must subscribe to this event and act on it for the key to respond. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onSetPlaybackSpeed Fired when the playback speed is changed, for example for the rewind or fast forward operation. Calling the method event.preventDefault() will prevent the playback speed from being changed. The event.payload.speed.previous property is the integer value for the previous speed. The event.payload.speed.current property is the integer value for the current speed. A negative value indicates the rewinding speed and a value greater than one indicates the fast forwarding speed.

onSetScreensaverMode Fired when the state of the screensaver is changed. After a pause or stop event, the screensaver is set to activate after a time period of inactivity. In all other media player states the screensaver does not activate and cannot interrupt content playback. Calling the method event.preventDefault() will prevent the state of the screensaver from changing. The event.payload.mode property has the value on if the screensaver is allowed to activate and off if the screensaver is not allowed to activate.


Event Description

onStartPlaylist Fired when you call the method KONtx.mediaplayer.playlist.start() on a playlist. Calling the method event.preventDefault() will prevent playback from starting.

onStartStreamPlayback Fired when the media player is about to start playback. Calling the method event.preventDefault() will prevent the KONtx media player from starting playback. The event.payload.selectedURL is the URL about to start playback. The event.payload.startIndex is the time index to start playback of the selected URL. The event.payload.callbackHandler is a callback to start playback yourself. This provides an alternative method to change the URL just before playback. By calling the method event.preventDefault() on the event and then calling event.payload.callbackHandler(url, timeIndex) you can provide an alternative url to play along with a new timeIndex. This is not a general use case. Instead you should use custom playlist entry objects to change the URL.

onStateChange Fired when the TV’s media player changes state. Match the states against the KONtx.mediaplayer.constants.states enumeration. Do not call the method event.preventDefault() on this event. The event.payload.newState property is the new state into which the player just transitioned. The event.payload.previousState property is the state the player was in before this event happened.

onStopRemoteKeyPress Fired when the stop key is pressed on the remote control. To prevent the stop operation from being performed, subscribe to this event and call the method event.preventDefault() when it is fired. The event.payload.keyCode property is the code for the key which can be matched against the KONtx.mediaplayer.constants.keys enumeration.

onStreamLoadError Fired when a stream is not available. Usually this event is fired because the playlist is empty or the current playlist entry does not contain any streams.

onTimeIndexChanged Fired approximately once per second during content playback and provides the current time index. The event.payload.timeIndex property is the current position in the content playback in seconds. The event.payload.duration property is the length of the currently playing content in seconds. The event.payload.rawTimeIndex property is the current position in the content playback in milliseconds. The event.payload.rawDuration property is the length of the currently playing content in milliseconds.


Event Description

onViewportBoundsChanged Fired when the video playback viewport bounds are changed by calling the method setViewportBounds(). The event.payload.viewport.previous.x property is the previous horizontal coordinate of the top left corner of the viewport. The event.payload.viewport.previous.y property is the previous vertical coordinate of the top left corner of the viewport. The event.payload.viewport.previous.width property is the previous width of the viewport. The event.payload.viewport.previous.height property is the previous height of the viewport. The event.payload.viewport.current.x property is the current horizontal coordinate of the top left corner of the viewport. The event.payload.viewport.current.y property is the current vertical coordinate of the top left corner of the viewport. The event.payload.viewport.current.width property is the current width of the viewport. The event.payload.viewport.current.height property is the current height of the viewport.

Media Player Event Payload Properties

The KONtx media player events rely on the event payload object, event.payload, for both default properties and event-specific properties. The default properties are available on all KONtx media player events while the event-specific properties are only available when a specific event has fired. The default properties and event-specific properties are described in the table below. The event-specific properties are also listed with each event description above.


absolute event- specific

A Boolean of whether the seek offset event.payload.offset is an absolute position (true) or is relative to the current playback position (false) as provided to the KONtx.mediaplayer.control.seek() method. Set by the onControlSeek event.

bandwidth.current.bitrate event- specific

The current bitrate. Set by the onConnectionBandwidthChanged event.

bandwidth.current.margin event- specific

The current margin. Set by the onConnectionBandwidthChanged event.

bandwidth.previous.bitrate event- specific

The previous bitrate. Set by the onConnectionBandwidthChanged event.

bandwidth.previous.margin event- specific

The previous margin. Set by the onConnectionBandwidthChanged event.



bufferingCount event- specific

The number of buffering attempts since the last reset was performed. The bufferingCount property is reset following the onResetBufferingCount event being fired and is incremented each time a buffering event occurs.

callbackHandler( String url, int timeIndex)

event- specific

The callback to start playback in your code. This provides an alternative method to change the content’s URL just before playback. By calling event.preventDefault() and then event.payload.callbackHandler(String url, int timeIndex) you can provide an alternative url to play along with a new timeIndex. This is not a general use case. Instead you should use custom playlist entry objects to change the URL. Set by the onStartStreamPlayback event.

duration event- specific

The length of the currently playing content in seconds. Set by onTimeIndexChanged event.

entry event- specific

The playlist entry picked to start playback. Set by the onProcessPlaylistEntry event.

increment event- specific

The speed increment as passed to the KONtx.mediaplayer.control.fastforward() method. Set by the onControlFastForward and onControlRewind events.

index event- specific

The zero-based index of the playlist entry to be loaded. Set by the onLoadPlaylistEntry event.

keyCode event- specific

The code for the key that triggered the event which can be matched against the KONtx.mediaplayer.constants.keys enumeration. Set by the following events: onRemoteKeyPress, onPauseRemoteKeyPress, onStopRemoteKeyPress, onPlayRemoteKeyPress, onRewindRemoteKeyPress, and onFastForwardRemoteKeyPress.

mode event- specific

The event property has a value of on if the screensaver is allowed to activate and off if the screensaver is not allowed to activate. Set by the onSetScreensaverMode event.

newState event- specific

The new state into which the OEM-specific media player has transitioned. This state can be matched against the KONtx.mediaplayer.constants.states enumeration. Set by the onStateChange event.



offset event- specific

The seek offset in seconds as provided to the KONtx.mediaplayer.control.seek() method as a float. The event.payload.absolute property is a Boolean of whether the seek offset is an absolute position (true) or is relative to the current playback position (false) . Set by the onControlSeek event.

previousState event- specific

The state in which the OEM-specific media player was in before transitioning on an event. This state can be matched against the KONtx.mediaplayer.constants.states enumeration. Set by the onStateChange event.

player default KONtx Media Player event payload.

player.bandwidth default Hash which contains the following properties: bitrate and margin.

player.bandwidth.bitrate default The bitrate of the consumer’s connection as provided to the KONtx.mediaplayer interface.

player.bandwidth.margin default The margin to apply to the bitrate as provided to the KONtx.mediaplayer interface.

player.keys default Enumeration of the remote keys which can be pressed by the user. Use only these keys: PAUSE, STOP, REWIND, PLAY, and FASTFORWARD.

player.media default Hash containing the following properties: playlist, playlist_index, currentEntry, stream_index, stream_count, and buffering_count.

player.media.buffering_count default Numerical count of the number of times this entry has had a buffering event.

player.media.currentEntry default A reference to the current playlist entry which is loaded or playing.

player.media.playlist default A reference to the current playlist.

player.media.playlist_index default Zero based index of the current playlist item.

player.media.stream_count default Count of the number of streams in the current playlist entry.

player.media.stream_index default Zero based index of the stream selected in the current playlist entry.



player.states default Enumeration of all possible states of the player. Use only these keys: INIT, PLAY, PAUSE, FASTFORWARD, REWIND, STOP, BUFFERING, BUFFEREMPTY, INFOLOADED, EOF, UNKNOWN, and ERROR.

player.tvapi default Hash containing the following properties: control, path, input, output, state, timeIndex, and mediaDuration.

player.tvapi.control default Reference to the TVControl object. Not for general use.

player.tvapi.input default Reference to the TVNetworkInput object. Not for general use.

player.tvapi.mediaDuration default Length of the currently playing stream in milliseconds. Read-only.

player.tvapi.output default Reference to the TVOutput object. Not for general use.

player.tvapi.path default Reference to the TVPath object. Not for general use.

player.tvapi.state default Integer from the KONtx.mediaplayer.constants.states enumeration of the current playback state. Read-only.

player.tvapi.timeIndex default Current time index in milliseconds. Read-only.

playlist event- specific

The playlist being set. Set by the onPlaylistChange event.

rawDuration event- specific

The length of the currently playing content in milliseconds. Set by the onTimeIndexChanged event.

rawTimeIndex event- specific

Current position in the content playback in milliseconds. Set by the onTimeIndexChanged event.

selectedURL event- specific

The URL about to start playback. The event.payload.startIndex is the time index to start playback of the selected URL. Set by the onStartStreamPlayback event.

speed.current event- specific

The integer value for the current speed. A negative value indicates the rewinding speed and a value greater than one indicates the fast forwarding speed. Set by the onSetPlaybackSpeed event.



speed.previous event- specific

The integer value for the previous speed. A negative value indicates the rewinding speed and a value greater than one indicates the fast forwarding speed. Set by the onSetPlaybackSpeed event.

startIndex event- specific

The time index to start playback of the event.payload.selectedURL. Set by the onStartStreamPlayback event.

streamswitch.config.bitrate event- specific

The specified bitrate when the KONtx.mediaplayer.constants.streamswitch.BANDW

IDTH algorithm is used to switch streams. Set by the onControlStreamSwitch event.

streamswitch.config.direction event- specific

The direction to change (String values up or down, the default is down) when the stream switch algorithm is KONtx.mediaplayer.constants.streamswitch.INDEX

_CHANGE. The event.payload.streamswitch.config.offset_amount property is the bitrate increment to increase or decrease. If you provide a direction but not an offset amount, then the offset amount is defaulted to 1. Set by the onControlStreamSwitch event.

streamswitch.config.margin event- specific

The specified margin when the KONtx.mediaplayer.constants.streamswitch.BANDW

IDTH algorithm is used to switch streams. Set by the onControlStreamSwitch event.

streamswitch.config.offset_amount event- specific

The bitrate increment to increase or decrease when the stream switch algorithm is KONtx.mediaplayer.constants.streamswitch.INDEX

_CHANGE. This offset amount can be more than the available stream bitrate. The event.payload.streamswitch.config.direction is the direction to change (String values up or down, the default is down). If you provide a direction but not an offset amount, then the offset amount is defaulted to 1. Set by the onControlStreamSwitch event.



streamswitch.method event- specific

The stream switch algorithm being used by the KONtx.mediaplayer.control.streamswitch() method. The possible enumeration values are: KONtx.mediaplayer.constants.streamswitch.INDEX

_CHANGE to shift bitrate up and down by a predetermined amount and KONtx.mediaplayer.constants.streamswitch.BANDW

IDTH to specify a new bitrate and margin and to allow the media player to choose the best stream. Set by the onControlStreamSwitch event.

timeIndex event- specific

The current position in the content playback in seconds. Set by the onTimeIndexChanged event.

viewport.current.height event- specific

The current height of the viewport. Set by the onViewportBoundsChanged event.

viewport.current.width event- specific

The current width of the viewport. Set by the onViewportBoundsChanged event.

viewport.current.x event- specific

The current horizontal coordinate of the top left corner of the viewport. Set by the onViewportBoundsChanged event.

viewport.current.y event- specific

The current vertical coordinate of the top left corner of the viewport. Set by the onViewportBoundsChanged event.

viewport.previous.height event- specific

The previous height of the viewport. Set by the onViewportBoundsChanged event.

viewport.previous.width event- specific

The previous width of the viewport. Set by the onViewportBoundsChanged event.

viewport.previous.x event- specific

The previous horizontal coordinate of the top left corner of the viewport. Set by the onViewportBoundsChanged event.

viewport.previous.y event- specific

The previous vertical coordinate of the top left corner of the viewport. Set by the onViewportBoundsChanged event.

YWE TV Widget Media Player

Documents

Transcript of YWE TV Widget Media Player