Professional Documents
Culture Documents
Widget Engine
TV Widget Media Player API Reference
Revision 0.812/18/2010 Yahoo! Confidential Copyright 2007, 2008, 2009, 2010, 2011. All Rights Reserved
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 meansincluding printed or duplicated materials, onscreen publication or Web documentationis 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
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
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
YAHOO! CONFIDENTIAL
YAHOO! CONFIDENTIAL
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, DVRs 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
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.
YAHOO! CONFIDENTIAL
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)
YAHOO! CONFIDENTIAL
o o
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 devices 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.
YAHOO! CONFIDENTIAL
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 devices buffer size, the devices 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
YAHOO! CONFIDENTIAL
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
10
YAHOO! CONFIDENTIAL
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 consumers network bandwidth.
KONtx.mediaplayer.initialize(); var overlay = new KONtx.control.MediaTransportOverlay({}).appendTo(this); function playerDispatcher(event) { if(event.type == "onPlaylistEnd") { KONtx.application.previousView();
YAHOO! CONFIDENTIAL
11
} } 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.
12
YAHOO! CONFIDENTIAL
_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.
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 overlays 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:
YAHOO! CONFIDENTIAL
13
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);
14
YAHOO! CONFIDENTIAL
var entries = []; entries.push(new KONtx.media.PlaylistEntry({ url: "http://my.video.com/" })); entries.push(new KONtx.media.PlaylistEntry({ url: "http://my.video2.com/" })); playlist.addEntries(entries);
Place the code that subscribes to the onStateChange event in the JavaScript file init.jsfor example:
YAHOO! CONFIDENTIAL
15
See the JavaScript file now_playing_snippet.js in the MediaPlayerSample widget as a template for this dynamic snippet view.
16
YAHOO! CONFIDENTIAL
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 planes background image.
YAHOO! CONFIDENTIAL
17
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.
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();
18
YAHOO! CONFIDENTIAL
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 viewfor 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.
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:
YAHOO! CONFIDENTIAL
19
Call _registerHandlers()in your player views updateView() method and call _unregisterHandlers()in your player views 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.
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.
20
YAHOO! CONFIDENTIAL
See the Aspect Ratio Example above to configure the aspect ratio of video playback for 4:3 content without stretching.
This completes the simple migration from KONtx.videoplayer to KONtx.mediaplayer. To support additional features see the Media Player Examples section above.
YAHOO! CONFIDENTIAL
21
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 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. 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. 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.
backwardseekButton Boolean
fadeTimeout
int
fastforwardButton
Boolean
22
YAHOO! CONFIDENTIAL
Property
forwardseekButton
Type
Boolean
Description 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. 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. Indicates if a play button should be included in the transport keys. Default value is true. 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. 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. Indicates if a stop button should be included in the transport keys. Default value is true.
infoButton
Boolean
playButton
Boolean
resizeButton
Boolean
rewindButton
Boolean
stopButton
Boolean
Method
Boolean focus();
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.
YAHOO! CONFIDENTIAL
23
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
Property
autostart forcePlay
Type
Boolean Boolean
Description Deprecated property. The default value is false. Set this to true to force playback of the lowest bitrate stream, even if the consumers 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 consumers bandwidth tests lower than the lowest bitrate stream provided. The default value is true. 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.
repeatAll
Boolean
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();
Removes the specified playlist entry with the index you provide.
24
YAHOO! CONFIDENTIAL
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 consumers current connection speed.
Example
KONtx.mediaplayer.initialize(); var playlist = new KONtx.media.Playlist(); var var var var url2 = "http://my.video.com/content3.mp4"; url3 = "http://my.video.com/content4.mp4"; bitrate2 = 600; 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();
YAHOO! CONFIDENTIAL
25
Properties
Property
url bitrate startIndex streams
Type
string int int Array
Description The media URL. Default value is null. The bitrate of the video. Default value is null. The time index to start playback of the video. Default value is null. 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();
26
YAHOO! CONFIDENTIAL
Properties
Property
debugInternals
Type
Object
Description 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.
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
isPlaylistEntryActive
Boolean
playlist.currentIndex
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). The active TVControl object. Not for general use. Read-only. The active TVNetworkInput object. Not for general use. Read-only. The active TVOutput object. Not for general use. Read-only. The active TVPath object. Not for general use. Read-only. The HTTP error code as returned by the tvapi.activeInput or -1 if no error. Read-only. The length of the currently playing content in milliseconds. Read-only. The current player state to be compared against the constants.states enumeration. Read-only. The current time index of the playing content in milliseconds. Read-only.
tvapi.activeControl
TVControl
tvapi.activeInput
TVNetworkInput
tvapi.activeOutput
TVOutput
tvapi.activePath
TVPath
tvapi.currentHTTPErrorCode int
tvapi.currentMediaDuration int
tvapi.currentPlayerState
int
tvapi.currentTimeIndex
int
Methods
void control.fastforward(int increment);
YAHOO! CONFIDENTIAL
27
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();
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();
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 consumers connection as tested through KONtx.speedtest. The config.margin property is the margin factor to apply to the consumers 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();
28
YAHOO! CONFIDENTIAL
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);
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.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
FASTFORWARD PAUSE PLAY REWIND STOP
Description Fast forward remote control key. Pause remote control key. Play remote control key. Rewind remote control key. Stop remote control key
YAHOO! CONFIDENTIAL
29
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. Constant
BUFFEREMPTY
Description The buffer is completely empty. The media may pause because there is no data in the buffer. Rebuffering should begin. 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. The OEM-specific media player has reached the end of the media file. An error was received from the OEM-specific media player. The video is moving fast forward. The property
KONtx.mediaplayer.isPlaylistEntryActive returns true when the
BUFFERING
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. The OEM-specific media player is initializing. The video is paused. The property
KONtx.mediaplayer.isPlaylistEntryActive returns true when the
INIT PAUSE
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.
30
YAHOO! CONFIDENTIAL
Constant
BANDWIDTH
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.stre amswitch.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.
YAHOO! CONFIDENTIAL
31
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. Fired when KONtx.mediaplayer.control.pause() is called. Calling the method event.preventDefault() will prevent the pause from occurring. Fired when KONtx.mediaplayer.control.play() is called. Calling the method event.preventDefault() will prevent the play action from occurring. 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. 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).
onControlPause
onControlPlay
onControlRewind
onControlSeek
32
YAHOO! CONFIDENTIAL
Event
onControlStop
Description Fired when KONtx.mediaplayer.control.stop() is called. Calling the method event.preventDefault() will prevent the stop action from occurring. 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. 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. 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. 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.
onControlStreamSwitch
onConvertToSpeed
onFastForwardRemoteKeyPress
onFindBestStream
YAHOO! CONFIDENTIAL
33
Event
onLoadNextPlaylistEntry
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. Fired when the playlist method
KONtx.mediaplayer.playlist.previousEntry() is called. Calling the method event.preventDefault() will prevent the
onLoadPreviousPlaylistEntry
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. 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. Fired when the media player starts buffering or rebuffering the current stream. Calling the method event.preventDefault() prevents the wait indicator display. 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. Fired when the end of the playlist is reached. 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. 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.
onPauseRemoteKeyPress
onPlaybackBuffering
onPlaylistChange
onPlaylistEnd onPlaylistRepeat
onPlayPlaylistEntry
34
YAHOO! CONFIDENTIAL
Event
onPlayRemoteKeyPress
Description 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. 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. 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. 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. 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. 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. 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.
onProcessPlaylistEntry
onRemoteKeyPress
onResetBufferingCount
onRewindRemoteKeyPress
onSetPlaybackSpeed
onSetScreensaverMode
YAHOO! CONFIDENTIAL
35
Event
onStartPlaylist
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. Fired when the TVs 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. 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. 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. 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.
onStateChange
onStopRemoteKeyPress
onStreamLoadError
onTimeIndexChanged
36
YAHOO! CONFIDENTIAL
Event
onViewportBoundsChanged
Description 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.
Type
Description
event- A Boolean of whether the seek offset specific 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. event- The current bitrate. Set by the specific onConnectionBandwidthChanged event. event- The current margin. Set by the specific onConnectionBandwidthChanged event. event- The previous bitrate. Set by the specific onConnectionBandwidthChanged event. event- The previous margin. Set by the specific onConnectionBandwidthChanged event.
bandwidth.current.bitrate
bandwidth.current.margin
bandwidth.previous.bitrate
bandwidth.previous.margin
YAHOO! CONFIDENTIAL
37
Property
bufferingCount
Type
Description
event- The number of buffering attempts since the last specific reset was performed. The bufferingCount property is reset following the onResetBufferingCount event being fired and is incremented each time a buffering event occurs. event- The callback to start playback in your code. This specific provides an alternative method to change the contents 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- The length of the currently playing content in specific seconds. Set by onTimeIndexChanged event. event- The playlist entry picked to start playback. Set by specific the onProcessPlaylistEntry event. event- The speed increment as passed to the specific KONtx.mediaplayer.control.fastforward() method. Set by the onControlFastForward and onControlRewind events. event- The zero-based index of the playlist entry to be specific loaded. Set by the onLoadPlaylistEntry event. event- The code for the key that triggered the event which specific can be matched against the
KONtx.mediaplayer.constants.keys
entry
increment
index
keyCode
event- The event property has a value of on if the specific screensaver is allowed to activate and off if the screensaver is not allowed to activate. Set by the onSetScreensaverMode event. event- The new state into which the OEM-specific media specific player has transitioned. This state can be matched against the
KONtx.mediaplayer.constants.states
newState
38
YAHOO! CONFIDENTIAL
Property
offset
Type
Description
event- The seek offset in seconds as provided to the specific 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. event- The state in which the OEM-specific media player specific was in before transitioning on an event. This state can be matched against the
KONtx.mediaplayer.constants.states
previousState
default default
KONtx Media Player event payload. Hash which contains the following properties: bitrate and margin. The bitrate of the consumers connection as provided to the KONtx.mediaplayer interface. The margin to apply to the bitrate as provided to the
KONtx.mediaplayer interface.
player.bandwidth.bitrate
default
player.bandwidth.margin
default
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. Hash containing the following properties:
playlist, playlist_index, currentEntry, stream_index, stream_count, and buffering_count.
player.media
default
player.media.buffering_count
default
Numerical count of the number of times this entry has had a buffering event. A reference to the current playlist entry which is loaded or playing. A reference to the current playlist. Zero based index of the current playlist item. Count of the number of streams in the current playlist entry. Zero based index of the stream selected in the current playlist entry.
player.media.currentEntry
default
player.media.stream_index
default
YAHOO! CONFIDENTIAL
39
Property
player.states
Type default
Description 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. Hash containing the following properties: control, path, input, output, state, timeIndex, and mediaDuration. Reference to the TVControl object. Not for general use. Reference to the TVNetworkInput object. Not for general use. Length of the currently playing stream in milliseconds. Read-only. Reference to the TVOutput object. Not for general use. Reference to the TVPath object. Not for general use. Integer from the
KONtx.mediaplayer.constants.states
player.tvapi
default
player.tvapi.control
default
player.tvapi.input
default
player.tvapi.mediaDuration
default
player.tvapi.output
default
player.tvapi.path
default
player.tvapi.state
default
default
event- The playlist being set. Set by the specific onPlaylistChange event. event- The length of the currently playing content in specific milliseconds. Set by the onTimeIndexChanged event. event- Current position in the content playback in specific milliseconds. Set by the onTimeIndexChanged event. event- The URL about to start playback. The specific event.payload.startIndex is the time index to start playback of the selected URL. Set by the onStartStreamPlayback event. event- The integer value for the current speed. A negative specific value indicates the rewinding speed and a value greater than one indicates the fast forwarding speed. Set by the onSetPlaybackSpeed event.
rawDuration
rawTimeIndex
selectedURL
speed.current
40
YAHOO! CONFIDENTIAL
Property
speed.previous
Type
Description
event- The integer value for the previous speed. A specific negative value indicates the rewinding speed and a value greater than one indicates the fast forwarding speed. Set by the onSetPlaybackSpeed event. event- The time index to start playback of the specific event.payload.selectedURL. Set by the onStartStreamPlayback event. event- The specified bitrate when the specific KONtx.mediaplayer.constants.streamswitch.BANDW IDTH algorithm is used to switch streams. Set by the onControlStreamSwitch event. event- The direction to change (String values up or down, specific the default is down) when the stream switch algorithm is
KONtx.mediaplayer.constants.streamswitch.INDEX _CHANGE. The
startIndex
streamswitch.config.bitrate
streamswitch.config.direction
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- The specified margin when the specific KONtx.mediaplayer.constants.streamswitch.BANDW IDTH algorithm is used to switch streams. Set by the onControlStreamSwitch event. The bitrate increment to increase or decrease specific when the stream switch algorithm is
KONtx.mediaplayer.constants.streamswitch.INDEX _CHANGE. This offset amount can be more than the
streamswitch.config.offset_amount event-
available stream bitrate. The 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.
event.payload.streamswitch.config.direction
YAHOO! CONFIDENTIAL
41
Property
streamswitch.method
Type
Description
event- The stream switch algorithm being used by the specific KONtx.mediaplayer.control.streamswitch() method. The possible enumeration values are:
KONtx.mediaplayer.constants.streamswitch.INDEX _CHANGE to shift bitrate up and down by a
allow the media player to choose the best stream. Set by the onControlStreamSwitch event.
timeIndex
event- The current position in the content playback in specific seconds. Set by the onTimeIndexChanged event. event- The current height of the viewport. Set by the specific onViewportBoundsChanged event. event- The current width of the viewport. Set by the specific onViewportBoundsChanged event. event- The current horizontal coordinate of the top left specific corner of the viewport. Set by the onViewportBoundsChanged event. event- The current vertical coordinate of the top left corner specific of the viewport. Set by the onViewportBoundsChanged event. event- The previous height of the viewport. Set by the specific onViewportBoundsChanged event. event- The previous width of the viewport. Set by the specific onViewportBoundsChanged event. event- The previous horizontal coordinate of the top left specific corner of the viewport. Set by the onViewportBoundsChanged event. event- The previous vertical coordinate of the top left specific corner of the viewport. Set by the onViewportBoundsChanged event.
viewport.current.height
viewport.current.width
viewport.current.x
viewport.current.y
viewport.previous.height
viewport.previous.width
viewport.previous.x
viewport.previous.y
42
YAHOO! CONFIDENTIAL