Creating a Caption File

The Caption Creation Utility enables synchronization of the line-by-line display of a text file with the playing of an audio file. You can start this program from either an OS/2 command prompt by typing CAPTION (while in the \TOOLKIT\SAMPLES\MM\CAPTION subdirectory), or by selecting the Caption Creation Utility object from the Toolkit folder. You can open an audio file, open a text file to synchronize with it, play the audio file, and select (by clicking a mouse button) the moment in the audio when the current line of text should scroll to display the next line of text. This allows the user to synchronize an audio file with a text file.

           ┌─────────┐         ┌─────────┐
           │  Text   │         │  Audio  │
           │  File   │         │  File   │
           └─────────┘         └─────────┘
                └──────┐     ┌──────┘
                            
                    ┌───────────┐
                    │  Caption  │
                    │ Creation  │
                    │  Utility  │
                    └─────┬─────┘
                          
                     ┌─────────┐
                     │ Caption │
                     │  File   │
                     └─────────┘

In order to start the synchronization process, the user selects Start timing. The audio file begins playing and Advance line is enabled. When you want to scroll to the next line of text, you select Advance line. This scrolls the line of text in the text window and displays the next line. When Advance line is selected, the Caption Creation Utility issues an MCI_STATUS message with mciSendCommand as shown in the following figure. The device ID passed is obtained when the application opens the audio device. The MCI_STATUS_ITEM flag is set and the ulItem field in the MCI_STATUS_PARMS data structure contains MCI_STATUS_POSITION. Upon return, the ulReturn field in the MCI_STATUS_PARMS data structure contains the current position of the device in MMTIME units.

     case ID_NEXTLINE:
        if ( usNextline < usLineCount ) /* (1) Check usNextline.   */
        {
           msp.hwndCallback = (HWND) NULL; /* (2) Get audio
                                               position.           */

           msp.ulItem     = MCI_STATUS_POSITION;
           ulError = mciSendCommand ( mop.usDeviceID,
                                      MCI_STATUS,
                                      MCI_WAIT | MCI_STATUS_ITEM,
                                      (PVOID) &msp,
                                      (USHORT)  UP_STATUS );

When the Caption Creation Utility receives the position value, it writes the time value and the line of text to the caption file. A caption file contains a copy of the text file and (before each line of text) the multimedia time unit when that line of text should be displayed in conjunction with the audio file. The file name of the caption file is the same as the file name of the text file, with an extension of ._CC. The caption file can then be used by an application in conjunction with the Caption DLL to caption an application.