Microsoft DirectX 8.0 |
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.
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>
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>
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.
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:
(Note that audio and subpicture streams are numbered from zero, whereas titles, angles, and parental levels are numbered from one.)
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.
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.
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>
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; }
//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; } }
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 | |||||||
---|---|---|---|---|---|---|---|
Afrikaans | 0x36 | Albanian | 0x1c | Arabic | 0x01 | Basque | 0x2d |
Belarusian | 0x23 | Bulgarian | 0x02 | Catalan | 0x03 | Chinese | 0x04 |
Croatian | 0x1a | Czech | 0x05 | Danish | 0x06 | Dutch | 0x13 |
English | 0x09 | Estonian | 0x25 | Faeroese | 0x38 | Farsi | 0x29 |
Finnish | 0x0b | French | 0x0c | German | 0x07 | Greek | 0x08 |
Hebrew | 0x0d | Hungarian | 0x0e | Icelandic | 0x0f | Indonesian | 0x21 |
Italian | 0x10 | Japanese | 0x11 | Korean | 0x12 | Latvian | 0x26 |
Lithuanian | 0x27 | Malay | 0x3e | Norwegian | 0x14 | Polish | 0x15 |
Portuguese | 0x16 | Romanian | 0x18 | Russian | 0x19 | Serbian | 0x1a |
Slovak | 0x1b | Slovenian | 0x24 | Spanish | 0x0a | Swahili | 0x41 |
Swedish | 0x1d | Thai | 0x1e | Turkish | 0x1f | Ukrainian | 0x22 |
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
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
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 | ||
---|---|---|
Volume | 0x01 | Indicates that the strings that follow pertain to the DVD volume. |
Title | 0x02 | Indicates that the strings that follow pertain to a title. |
ParentalID | 0x03 | Indicates that the strings that follow pertain to a particular parental ID. |
Chapter | 0x04 | Indicates that the strings that follow pertain to a chapter. |
Cell | 0x05 | Indicates that the strings that follow pertain to a cell (typically consisting of one scene from a movie). |
Stream Identifiers | ||
Audio | 0x10 | Indicates that the strings that follow pertain to an audio stream. |
Subpicture | 0x11 | Indicates that the strings that follow pertain to a subpicture stream. |
Angle | 0x12 | Indicates that the strings that follow pertain to an angle block. |
Audio Channel Identifiers | ||
Channel | 0x20 | Indicates that the strings that follow pertain to one channel in an audio stream. |
General Content Strings | ||
Name | 0x30 | The most common identifer for title names, chapter names, song names, etc. |
Comments | 0x31 | General comments about the title, chapter, song, etc. |
Title Content Strings | ||
Series | 0x38 | Additional information about the title, chapter, song, etc. |
Movie | 0x39 | Additional information about the title or chapter if this is a movie. |
Video | 0x3a | Additional information about the title or chapter if this is a video. |
Album | 0x3b | Additional information about the title or chapter if this is an album. |
Song | 0x3c | Additional information about the title or chapter if this is a song. |
Other | 0x3f | Additional information about the title or chapter if this belongs to some other genre or category. |
Secondary Title Content Strings | ||
Series | 0x40 | Additional information about the title, chapter, song, etc. |
Movie | 0x41 | Additional information about the title or chapter if this is a movie. |
Video | 0x42 | Additional information about the title or chapter if this is a video. |
Album | 0x43 | Additional information about the title or chapter if this is an album. |
Song | 0x44 | Additional information about the title or chapter if this is a song. |
Other | 0x45 | Additional information about the title or chapter if this is this belongs to some other genre or category. |
Original Content Strings | ||
Series | 0x48 | Additional information about the title, chapter, song, etc. |
Movie | 0x49 | Additional information about the title or chapter if this is a movie. |
Video | 0x4a | Additional information about the title or chapter if this is a video. |
Album | 0x4b | Additional information about the title or chapter if this is an album. |
Song | 0x4c | Additional information about the title or chapter if this is a song. |
Other | 0x4f | Additional information about the title or chapter if this is this belongs to some other genre or category. |
Other Info Content Strings | ||
Other Scene | 0x50 | Additional information about an alternate scene in a movie title or chapter. |
Other Cut | 0x51 | Additional information about an alternate cut in a movie title or chapter. |
Other Take | 0x52 | Additional information about an alternate take in a movie title or chapter. |