Microsoft DirectX 8.0

Writing a Script-Based DVD Application

This article describes the basic tasks involved in writing a script-based DVD application using the MSWebDVD ActiveX® Control. For background information on the DVD navigation concepts discussed here, see DVD Basics.

Embedding the MSWebDVD Object

The MSWebDVD object handles all the DVD navigation commands as well as the display of the video rectangle. It will appear on your Web page as the video display rectangle. Therefore, you must embed it within the HTML document's BODY element. Set the rectangle width and height, and the default values for any properties as required by your application.

<OBJECT CLASSID=clsid:38EE5CEE-4B62-11D3-854F-00A0C9C898E7 ID=DVD 
    STYLE="height:369px; width:740px">
<PARAM NAME="BackColor" VALUE="1048592">
<PARAM NAME="EnableResetOnStop" VALUE="-1">
<PARAM NAME="ColorKey" VALUE="1048592">
</OBJECT>

Enabling Users to Issue DVD Commands

To enable users to control the DVD player, you need to provide a UI with buttons for issuing DVD commands such as "Stop" and "Play." The following code example shows how to hook up basic HTML buttons to the MSWebDVD object methods.

<INPUT ID=button1 NAME="button1" TYPE=button VALUE="Play" onClick='Play();'>
<INPUT ID=button2 NAME="button2" TYPE=button VALUE="Pause" onClick='Pause();'>

<SCRIPT LANGUAGE="JScript">
function Play(){
	 DVD.Play();	
}

function Pause(){
  DVD.Pause();
}

</SCRIPT>

Working With DVD Menus

MSWebDVD automatically handles menu commands when the user clicks on the on-screen buttons with the mouse. An application does not need to do anything to implement basic mouse support. But an application can override this automatic mouse handling at any time in order to cause additional actions to take place when a user clicks on a menu button. For example, you could cause certain text or images to be displayed on the web page depending on which button the user clicks. To implement custom mouse handling, use the MSWebDVD menu-related methods such as SelectAndActivateButton, GetButtonAtPosition, and so on. To completely disable automatic mouse handling, set the DisableAutoMouseProcessing property to true.

MSWebDVD also offers a set of methods (for example, SelectUpperButton) which allow you to display an image map on your web page representing a DVD remote control, with buttons that move the current menu selection up, down, right and left. These buttons are referred to as "directional" or "relative" buttons in the documentation. Unlike the buttons that appear within the DVD menus, the directional buttons are supplied by an application.

Audio and Subpicture Streams

A DVD-Video disc can have up to eight audio streams, numbered zero through seven, each with up to six discrete channels. Only one of these streams can be active at any given time. For subpictures, up to 32 streams are available, numbered 0 through 31, although for audio only one stream can be active at any given time. Discs are generally authored with default audio and subpicture streams, but an application can enable the user to see all the streams that are available for a given title, and select the one in the language they prefer. The basic steps in this process are the same for both audio and subpicture streams:

  1. Determine the number of streams available for a specified title.
  2. Iterate through the streams and retrieve the stream attributes for each.
  3. Retrieve the language code from the returned locale identifier (LCID) and create a human-readable string.
  4. Populate a "Select" box or other user interface control to enable the user to select the preferred stream.

(Note that audio and subpicture streams are numbered from zero, whereas titles, angles, and parental levels are numbered from one.)

Enforcing Parental Management Levels

Any title or portion of a title on a DVD-Video disc can be assigned a generic parental management level (PML) from 1 through 8. Eight is the most restrictive level and one is the least restrictive. The idea is to provide a mechanism to prevent children from watching adult content without parental consent, but the specific meaning of each level varies from country to country. In the United States and Canada, the levels map to the rating system of the Motion Picture Association of America (G, PG, PG-13, NC-17), but this is not the case in other countries. A DVD application intended for an international market should not hard code any particular rating system into its parental management logic.

The MSWebDVD object by default ignores PMLs on the disc. For an application to be notified of PML markers on the disc, it must call NotifyParentalLevels(true). MSWebDVD will then inform your application when it encounters PML information on the disc. To enforce PMLs, your application must implement some form of password control logic that associates users with levels, and respond to EC_DVD_PARENTAL_LEVEL_CHANGE events to allow or disallow access as appropriate.

Saving and Restoring Bookmarks

Bookmarks are an internal data structure that the MSWebDVD object uses to create a snapshot of the current user session, including information such as the current location on the disc, the parental level of the person who was viewing at the time, the selected audio and subpicture streams, and so on. This means that users can save their place on a DVD-Video disc and come back to watch it at a later time.

The SaveBookmark method enables a user to save their place on a disc and the RestoreBookmark method enables the same user to begin viewing again from the stored location.

Only one bookmark can be stored at a time. Calling SaveBookmark twice will cause the first bookmark to be overwritten. Bookmarks are specific to a computer. Running the same HTML page on a different computer and calling RestoreBookmark will restore the last-saved bookmark on that computer or will return an error if no bookmark was previously saved.

Handling DVD Event Notifications

The MSWebDVD object sends notifications to an application-specified method when certain events take place, such as when the DVD domain changes, when a new parental management level is encountered, when it is about to enter an angle block, and so on. The event parameters can contain additional information related to the event. Error messages and warnings are also sent in this way. To capture the various DVD event notifications, enter the following HTML SCRIPT tag below the OBJECT tag for the MSWebDVD object.

<SCRIPT LANGUAGE="JScript" FOR=DVD EVENT="DVDNotify(EventCode, Param1, Param2)">
    ProcessDVDEvent(EventCode, Param1, Param2)
</SCRIPT>

Then, in script, define the event codes and the ProcessDVDEvent function, as shown in the next code example. (You may give your event handling function any name; it isn't required to be "ProcessEvents." For more information about the event codes, see DVD Event Notification Codes.

<SCRIPT LANGUAGE="JScript">

// DVD event codes are valued 257 through 283
var EC_DVDBASE = 256;

var EC_DVD_DOMAIN_CHANGE = (EC_DVDBASE + 1);
var EC_DVD_TITLE_CHANGE = (EC_DVDBASE + 2);
var EC_DVD_CHAPTER_START = (EC_DVDBASE + 3);
var EC_DVD_AUDIO_STREAM_CHANGE = (EC_DVDBASE + 4);
var EC_DVD_SUBPICTURE_STREAM_CHANGE = (EC_DVDBASE + 5);
var EC_DVD_ANGLE_CHANGE  = (EC_DVDBASE + 6);
var EC_DVD_BUTTON_CHANGE = (EC_DVDBASE + 7);
var EC_DVD_VALID_UOPS_CHANGE = (EC_DVDBASE + 8);
var EC_DVD_STILL_ON  = (EC_DVDBASE + 9);
var EC_DVD_STILL_OFF  = (EC_DVDBASE + 10);
var EC_DVD_CURRENT_TIME  = (EC_DVDBASE + 11); // not used by MSWebDVD
var EC_DVD_ERROR  = (EC_DVDBASE + 12);
var EC_DVD_WARNING  = (EC_DVDBASE + 13);
var EC_DVD_CHAPTER_AUTOSTOP  = (EC_DVDBASE + 14);
var EC_DVD_NO_FP_PGC  = (EC_DVDBASE + 15);
var EC_DVD_PLAYBACK_RATE_CHANGE  = (EC_DVDBASE + 16);
var EC_DVD_PARENTAL_LEVEL_CHANGE  = (EC_DVDBASE + 17);
var EC_DVD_PLAYBACK_STOPPED  = (EC_DVDBASE + 18);
var EC_DVD_ANGLES_AVAILABLE  = (EC_DVDBASE + 19);
var EC_DVD_PLAYPERIOD_AUTOSTOP  = (EC_DVDBASE + 20);
var EC_DVD_BUTTON_AUTO_ACTIVATED  = (EC_DVDBASE + 21);
var EC_DVD_CMD_START  = (EC_DVDBASE + 22);            // not used by MSWebDVD
var EC_DVD_CMD_END = (EC_DVDBASE + 23);               // not used by MSWebDVD
var EC_DVD_DISC_EJECTED  = (EC_DVDBASE + 24);
var EC_DVD_DISC_INSERTED  = (EC_DVDBASE + 25);
var EC_DVD_CURRENT_HMSF_TIME  = (EC_DVDBASE + 26);
var EC_DVD_KARAOKE_MODE  = (EC_DVDBASE + 27);

var nCurDomain;
var nCurParentalLevel;
  
function ProcessDVDEvent(EventCode, Param1, Param2)
{
    switch (EventCode)
    {
    case EC_DVD_DOMAIN_CHANGE:
        nCurDomain = Param1;
        // do something
        break;
    case EC_DVD_PARENTAL_LEVEL_CHANGE:
        nCurParentalLevel = Param1;
        // do something
        break;
    
    // handle any other events you are interested in
    
    default:
        break;
    }
}
</SCRIPT>

Handling UOP Event Notifications

The MSWebDVD object sends UOP event notifications to inform an application when a specific user operation (UOP) has been enabled or disabled by the disc. Each user operation has its own event, with a single Boolean parameter indicating whether that operation is now enabled or disabled. See MSWebDVD Events for more information on specific events.

For each event that you wish to handle, specify an event handler as shown in the following example. (You can call your handler method anything you like.)

<SCRIPT LANGUAGE="JScript" FOR=DVD EVENT="PlayForwards(bEnabled)">
    PlayForwardsEventHandler(bEnabled)
</SCRIPT>
Now define your handler method to respond appropriately to the event. Assume that the "button_Play" variable here is the id attribute of the "Play" button in your application.
function PlayForwardsEventHander(bEnabled)
{
  if(bEnabled == true)
    button_Play.disabled = false;
  else
    button_Play.disabled = true;
}

Synchronizing HTML Content with the Video

By handling timecode events from the disc, a web application can synchronize HTML content to the video. For example, you can cause images or text on the page to change at specified points in the video. The following code snippet shows one way to synchronize JScript function calls to timecode events:
//DVDTriggerPoints array holds frame count for each trigger. Must be in ascending order.
//Use timecode2frames() to convert timecodes (hh:mm:ss:ff) to total number of frames.

var DVDTriggerPoints = new Array(
  timecode2frames("01:15:24:00"), 
  timecode2frames("01:23:02:00"));

//DVDTriggerProcs array holds functions to be called at each trigger point defined in DVDTimePoints.
var DVDTriggerProcs = new Array(
  "showDogPic();",
  "showCatPic();");

//DVDTriggerIndex keeps track of current trigger (it indexes DVDTriggerPoints and DVDTriggerProcs).
var DVDTriggerIndex = 0;

//Handle DVD Events
function ProcessDVDEvent(EventCode, Param1, Param2) {
  switch (EventCode) {
     case EC_DVD_CURRENT_HMSF_TIME:
          if(MSWebDVD.CurrentDomain == 4) {  //Don’t bother checking unless disc is playing.
             if (DVDTriggerIndex < DVDTimePoints.length) {  //Are there trigger points left to check?
                currentDVDTime = (MSWebDVD.DVDTimeCode2bstr(Param1));
                 if (timecode2frames(currentDVDTime)>= DVDTriggerPoints[DVDTimeIndex]) {
                     // if trigger point has passed, execute the associated function
                    eval(DVDTriggerProcs[DVDTimeIndex++]);
                 }
             }
          }
       break;
 
       // handle other events 
   }
}

function timecode2frames(timeCode) {

   if (timeCode != "undefined") {
       return timeCode.substring(0,2)*108000
       + timeCode.substring(3,5)*1800
       + timeCode.substring(6,8)*30
       + timeCode.substring(9,11);
   } else {
       return 0;
   }
}

Working with LCIDs

The LCID, or "locale identifer," is a 32-bit data type into which are packed several different values that help to identify a particular geographical region. One of these internal values is the "primary language ID" which identifies the basic language of the region or locale, such as English, Spanish, or Russian.

MSWebDVD requires a complete valid LCID as an input parameter for two methods: SelectDefaultAudioLanguage and SelectDefaultSubpictureLanguage. This can be any valid LCID recognized by Windows®, and even some that are not recognized by Windows. (It is not necessary that the host system actually support the locale with fonts, keyboard mappings, and so on.) The following table lists some common LCIDs as well as well as some less common ones that are valid for MSWebDVD even through Windows does not recognize them by default. This is not a complete list of all possible LCIDs. For more information on LCIDs, including a complete list of LCIDs recognized by Windows, consult the MSDN online documentation at http://msdn.microsoft.com.
Some Valid LCIDs
Afrikaans 0x0436 Albanian 0x041c Arabic (Algeria) 0x1401
Arabic (Bahrain) 0x3c01 Arabic (Egypt) 0x0c01 Arabic (Iraq) 0x0801
Arabic (Jordan) 0x2c01 Arabic (Kuwait) 0x3401 Arabic (Lebanon) 0x3001
Arabic (Libya) 0x1001 Arabic (Morocco) 0x1801 Arabic (Oman) 0x2001
Arabic (Qatar) 0x4001 Arabic (Saudi Arabia) 0x0401 Arabic (Syria) 0x2801
Arabic (Tunisia) 0x1c01 Arabic (U.A.E.) 0x3801 Arabic (Yemen) 0x2401
Basque 0x042d Belarusian 0x0423 Bulgarian 0x0402
Catalan 0x0403 Chinese (Hong Kong) 0x0c04 Chinese (PRC) 0x0804
Chinese (Singapore) 0x1004 Chinese (Taiwan) 0x0404 Croatian 0x041a
Czech 0x0405 Danish 0x0406 Dutch (Belgian) 0x0813
Dutch (Standard) 0x0413 English (Australian) 0x0c09 English (Belize) 0x2809
English (Canadian) 0x1009 English (Caribbean) 0x2409 English (Ireland) 0x1809
English (Jamaica) 0x2009 English (New Zealand) 0x1409 English (South Africa) 0x1c09
English (Trinidad) 0x2c09 English (United Kingdom) 0x0809 English (United States) 0x0409
Estonian 0x0425 Faeroese 0x0438 Farsi 0x0429
Finnish 0x040b French (Belgian) 0x080c French (Canadian) 0x0c0c
French (Luxembourg) 0x140c French (Standard) 0x040c French (Swiss) 0x100c
German (Austrian) 0x0c07 German (Liechtenstein) 0x1407 German (Luxembourg) 0x1007
German (Standard) 0x0407 German (Swiss) 0x0807 Greek 0x0408
Hebrew 0x040d Hungarian 0x040e Icelandic 0x040f
Indonesian 0x0421 Italian (Standard) 0x0410 Italian (Swiss) 0x0810
Japanese 0x0411 Korean 0x0412 Korean (Johab) 0x0812
Latvian 0x0426 Lithuanian 0x0427 Malay (Malaysian) 0x043e
Malay (Brunei) 0x083e Norwegian (Bokmal) 0x0414 Norwegian (Nynorsk) 0x0814
Polish 0x0415 Portuguese (Brazilian) 0x0416 Portuguese (Standard) 0x0816
Romanian 0x0418 Russian 0x0419 Serbian (Cyrillic) 0x0c1a
Serbian (Latin) 0x081a Slovak 0x041b Slovenian 0x0424
Spanish (Argentina) 0x2c0a Spanish (Bolivia) 0x400a Spanish (Chile) 0x340a
Spanish (Colombia) 0x240a Spanish (Costa Rica) 0x140a Spanish (Dominican Republic) 0x1c0a
Spanish (Ecuador) 0x300a Spanish (El Salvador) 0x440a Spanish (Guatemala) 0x100a
Spanish (Honduras) 0x480a Spanish (Mexican) 0x080a Spanish (Modern Sort) 0x0c0a
Spanish (Nicaragua) 0x4c0a Spanish (Panama) 0x180a Spanish (Paraguay) 0x3c0a
Spanish (Peru) 0x280a Spanish (Puerto Rico) 0x500a Spanish (Traditional Sort) 0x040a
Spanish (Uruguay) 0x380a Spanish (Venezuela) 0x200a Swahili 0x0441
Swedish 0x041d Swedish (Finland) 0x081d Thai 0x041e
Turkish 0x041f Ukrainian 0x0422    

Several MSWebDVD methods and properties return locale identifier (LCID) values that identify which languages are available on the soundtracks or subtitles. To make use of this information, your application will need to extract the primary language ID from the returned LCID. To do this, perform a bitwise AND operation on the value of iLCID and 0x3FF. (The primary language ID is contained in the least significant 10 bits of the LCID.) The following code snippet shows how to do this.

iPrimaryLang = iLCID & 0x3FF;

To obtain a human-readable string from the primary language ID, call GetLangFromLangID as shown in this example:

sLanguage = DVD.GetLangFromLangID(iPrimaryLang);

See the Microsoft® Platform SDK for more information on LCIDs and language identifiers.

The following table lists the primary language IDs for the LCIDs in the table above.

Some Valid Primary Language IDs
Afrikaans0x36Albanian0x1cArabic0x01Basque0x2d
Belarusian0x23Bulgarian0x02Catalan0x03Chinese0x04
Croatian0x1aCzech0x05Danish0x06Dutch0x13
English0x09Estonian0x25Faeroese0x38Farsi0x29
Finnish0x0bFrench0x0cGerman0x07Greek0x08
Hebrew0x0dHungarian0x0eIcelandic0x0fIndonesian0x21
Italian0x10Japanese0x11Korean0x12Latvian0x26
Lithuanian0x27Malay0x3eNorwegian0x14Polish0x15
Portuguese0x16Romanian0x18Russian0x19Serbian0x1a
Slovak0x1bSlovenian0x24Spanish0x0aSwahili0x41
Swedish0x1dThai0x1eTurkish0x1fUkrainian0x22

Playing Karaoke Discs

Karaoke discs are a type of DVD-Video disc and have the same navigation structure. Songs are generally formatted as titles, and titles can be grouped together into title sets based on performer, musical style, or other criteria. The main difference between karaoke and other types of DVD-Videos is the audio stream. Karaoke discs all contain multichannel audio, usually Dolby AC-3. Channels 0 and 1 always contain the background instrumental music, while channels 2 through 5 contain guide vocals or guide melodies or sound effects. A karaoke application can control the volume and destination speaker for each auxiliary channel.

Karaoke playback also requires an audio decoder that supports the multichannel karaoke mixing information sent by the DVD Navigator. Specifically, the decoder must support the DVD Karaoke Property Set (AM_PROPERTY_DVDKARAOKE).

When the DVD Navigator detects karaoke content on a disc and goes into karaoke mode, it informs the decoder, which then should mute the upper three channels (the auxiliary channels) until any or all of them are explicitly turned on by an application. The basic tasks of a karaoke application will therefore be to

  1. determine the number of auxiliary channels and their contents
  2. provide a user interface that displays the channel contents and allows users to turn any auxiliary channel on or off at any time.

Working with DVD Text Strings

DVD discs, especially karaoke discs, might contain a database of text information to supplement the video or audio content. Such text on karaoke discs might include song titles, artist names, record labels, and so on. Versions of this text can be present in more than one language. These strings are optional; discs are not required to have them. If present they are organized in a way that closely mirrors the logical hierarchy of the DVD volume. Each string is preceded by a number that identifies what part of the disc structure it belongs to or gives some clue as to the content of the string.

There are two basic types of text strings: structure identifiers and content strings. Types with a value of 0x01 through 0x20 are structure identifiers. They are empty strings; the numerical code is used to identify the logical structure to which any following content strings belong. This structure corresponds very closely to the logical structure of a DVD disc contents: volume, title, chapter, and so on. The remaining types identify content strings that hold information that may be displayed to the viewer in a user interface. The exact way in which content strings are used is not closely defined, so DVD authors might use them in various ways.

Historically, DVD text strings have been used almost exclusively on karaoke discs, and these discs mostly use the 0x01 and 0x02 structure identifiers and the 0x30 type content string. But it is reasonable to assume that as time goes by, (1) more types of DVD-Video discs will contain text strings and (2) these strings will be organized in more complex ways in order to provide fuller descriptions of disc contents.

The following code shows how to determine the number of text string language blocks on the disc, and retrieve the human-readable string(s) that could be shown to the user to allow them to choose the language they are interested in. In this code the strings are added to an HTML SELECT element called "TextLanguageList." For more information on LCIDs and primary language IDs, see GetLangFromLangID

  function GetTextLanguages()
  {
    //get the number of text blocks
    var numLangs = DVD.GetDVDTextNumberOfLanguages(); 
	  var iLCID;
	  var iPrimaryLang;
	  var sLanguage;
  	var oOption;

	for (j = 0; j < numLangs; j++)
	{
    //get the locale identifier for the language block
		iLCID = DVD.GetDVDTextLanguageLCID(j);
    
    //get the primary language ID from the LCID
		iPrimaryLang = iLCID & 0x3FF;
    
    //get the human-readable string from the primary language ID
		sLanguage = DVD.GetLangFromLangID(iPrimaryLang);
    
    //add it to the SELECT element on the HTML page
		oOption = document.createElement("OPTION");
		oOption.text = sLanguage;
		document.all.TextLanguageList.add(oOption);
	} 
	
  } //end function GetTextStrings

The following test code demonstrates how to enumerate the strings and examine the text string type. It just dumps the results into an HTML TEXTAREA element called "myTextArea" so you can see how the numeric string types are used to organize the content strings. A real application would probably create its own data structure to hold the strings, or else would display them in a more useful way for the viewer.

  // iLanguage is the 0-based index for the language block
   function GetTextStrings(iLanguage)
   {
	
      var numStrings, stringType, j; 

      numStrings = DVD.GetDVDTextNumberOfStrings(iLanguage);
	
      for( j = 0; j < numStrings; j++)
      {
        stringType = DVD.GetDVDTextStringType(iLanguage, j);

        if(stringType > 0x20) //there is actually some text to read here
        {
          myTextArea.value += (stringType + ": " + DVD.GetDVDTextString(iLanguage, j) + "\n");
        }
        else // It's a node indicating what level of the volume structure
			// the following strings will apply to
        {
          myTextArea.value += (stringType + "\n");
        }
			
      }
    } //end function GetTextStrings

DVD Text String Types

This table lists a subset of the DVD text string types. All types with a value 0x20 and below are empty strings that merely indicate the node level in the disc's content data structure. The other strings are content strings. Most title and song names are type 0x30. The types in the Title, SubTitle and Original categories help to further identify the particular genre. The exact meaning and intended use of these categories is defined in a public document that can be downloaded from the DVD Forum's web site at www.dvdforum.org.

Structure Identifiers
Volume0x01Indicates that the strings that follow pertain to the DVD volume.
Title0x02Indicates that the strings that follow pertain to a title.
ParentalID0x03Indicates that the strings that follow pertain to a particular parental ID.
Chapter0x04Indicates that the strings that follow pertain to a chapter.
Cell 0x05Indicates that the strings that follow pertain to a cell (typically consisting of one scene from a movie).
Stream Identifiers
Audio0x10Indicates that the strings that follow pertain to an audio stream.
Subpicture0x11Indicates that the strings that follow pertain to a subpicture stream.
Angle0x12Indicates that the strings that follow pertain to an angle block.
Audio Channel Identifiers
Channel0x20Indicates that the strings that follow pertain to one channel in an audio stream.
General Content Strings
Name0x30The most common identifer for title names, chapter names, song names, etc.
Comments0x31General comments about the title, chapter, song, etc.
Title Content Strings
Series0x38Additional information about the title, chapter, song, etc.
Movie0x39Additional information about the title or chapter if this is a movie.
Video 0x3aAdditional information about the title or chapter if this is a video.
Album0x3bAdditional information about the title or chapter if this is an album.
Song0x3cAdditional information about the title or chapter if this is a song.
Other0x3fAdditional information about the title or chapter if this belongs to some other genre or category.
Secondary Title Content Strings
Series0x40Additional information about the title, chapter, song, etc.
Movie0x41Additional information about the title or chapter if this is a movie.
Video 0x42Additional information about the title or chapter if this is a video.
Album0x43Additional information about the title or chapter if this is an album.
Song0x44Additional information about the title or chapter if this is a song.
Other0x45Additional information about the title or chapter if this is this belongs to some other genre or category.
Original Content Strings
Series0x48Additional information about the title, chapter, song, etc.
Movie0x49Additional information about the title or chapter if this is a movie.
Video 0x4aAdditional information about the title or chapter if this is a video.
Album0x4bAdditional information about the title or chapter if this is an album.
Song0x4cAdditional information about the title or chapter if this is a song.
Other0x4fAdditional information about the title or chapter if this is this belongs to some other genre or category.
Other Info Content Strings
Other Scene0x50Additional information about an alternate scene in a movie title or chapter.
Other Cut0x51Additional information about an alternate cut in a movie title or chapter.
Other Take0x52Additional information about an alternate take in a movie title or chapter.