# Media Objects

The HTML5 spec defines Audio and Video browser objects, both derived from a common HTMLMediaElement base class. We implement, in Javascript, Audio and Video objects that correspond to the HTML5 spec. There are some additions and some omissions that are described later.

Note:

The HP webOS implementation corresponds to the following version of the HTML5 specification: http://www.w3.org/TR/2009/WD-html5-20090212/

The terms Audio and HTMLMediaElement tend to be used interchangeably as the features of the Audio object are all present in the base HTMLMediaElement. Features of HTMLMediaElement also apply to the Video object, however, several video specific attributes and functions exist that extend the base object. For example the video.poster attribute.

## Using HTMLMediaElements

### Include the Javascript implementation

webOS HTMLMediaElement attributes are not an integral part of our Webkit implementation, which means to use them a developer must include an additional JavaScript file with the application The functionality is defined in the file /usr/palm/frameworks/media/media.js. An application developer can include media.js in an application's index.html file, or list it in the application's sources.json file.

### Instantiate Audio or Video objects

As the Audio and Video objects are not part of the browser, audio or video HTML tags cannot be used in application scene HTML files. Audio and Video objects must be created through JavaScript and used to extend browser tags. To do that we provide the following special static methods, which are also defined in the media.js file:

>     // audioObj will be an instance of our Audio object
>     var audioObj = AudioTag.extendElement('divNameA');
>     // videoObj will be an instance of our Video object
>     var videoObj = VideoTag.extendElement('divNameV');
>     // this test will evaluate true
>     if (audioObj == document.getElementById('divNameA')){
>       //audioObj is now part of the DOM
>     }

Standard Audio and Video constructors do not associate their media objects with the correct scene and the objects do not go out of scope until the application is discarded. Their use is therefore not recommended.

### Useful defines

The three error values defined in the HTML5 spec are available via the following defines:

JavaScript define
MediaError.MEDIA_ERR_ABORTED
MediaError.MEDIA_ERR_NETWORK
MediaError.MEDIA_ERR_DECODE

The following values are defined and correspond to the HTMLMediaElement values for networkState.

Network state defines | Value
--- | ---
HTMLMediaElement.EMPTY | 0
HTMLMediaElement.LOADING | 1
HTMLMediaElement.LOADED_METADATA | 2
HTMLMediaElement.LOADED_FIRST_FRAME | 3
HTMLMediaElement.LOADED | 4

The following values are defined and correspond to the HTMLMediaElement values for readyState.

Ready state defines | Value
--- | ---
HTMLMediaElement.HAVE_NOTHING | 0
HTMLMediaElement.HAVE_METADATA | 1
HTMLMediaElement.HAVE_CURRENT_DATA | 2
HTMLMediaElement.HAVE_FUTURE_DATA | 3
HTMLMediaElement.HAVE_ENOUGH_DATA | 4
HTMLMediaElement.DATA_UNAVAILABLE | 0
HTMLMediaElement.CAN_SHOW_CURRENT_FRAME | 1
HTMLMediaElement.CAN_PLAY | 2
HTMLMediaElement.CAN_PLAY_THROUGH | 3

The last four values in the Ready State table are deprecated values as they have been replaced recently in the HTML5 spec by `HAVE_NOTHING`, `HAVE_METADATA`, `HAVE_CURRENT_DATA` and `HAVE_FUTURE_DATA`.

### Sample audio player

See Services Sample.

### Sample video player

This sample shows code for a scene assistant that creates a video object. A div is included in the scene's view file. Properties for the video object are defined as attributes of the div, so only minimal code to create the video object is required.

Video player scene HTML

>     <div
>       id="VideoDiv"
>       style="z-index:100; position:fixed; top:0px; left:0px; width:320px; height:480px;"
>       src="http://path/to/my/movie.mp4"
>       autoplay="true"
>       poster="thumbnail.png"></div>
>     <div
>       id="TitleBox"
>       style="z-index:110; position:fixed; width:200px; height:40px; top:50px; left:60px;
>       background-color: #a0a0a0;">Text ...</div>

Video player JavaScript fragment

>     VideoAssistant = Class.Create({
>       initialize: function(){
>           //...
>       },
>       setup: function(){
>           this.videoObj = VideoTag.extendElement('VideoDiv');
>           this.onKeyPressHandler = this.onKeyPress.bindAsEventListener(this);
>           Mojo.listen(this.controller.sceneElement, Mojo.Event.keypress, this.onKeyPressHandler);
>       },
>       onKeyPress: function(){
>           // Toggle play/pause state if a key is pressed.
>               if (this.videoObj.paused){
>                   this.videoObj.play();
>               } else {
>                   this.videoObj.pause();
>               }
>       }
>     });

## webOS audio/video extensions

webOS adds extensions to the HTML5 media objects, including mnemonics for several structures and a .palm sub-object to the Audio or Video objects for webOS-specific features.

See Media Extensions.