MMAPG - High-Level Service API

Multimedia Application Programming Guide

Introduction What's New... Multimedia Application Programming Environment Media Control Interface Multimedia Logical Devices Amplifier-Mixer Device Waveform Audio Device Sequencer Device CD Audio Device CD-XA Device Videodisc Device Digital Video Device Direct Interface Video Extensions (DIVE) Captioning OS/2 Multimedia Controls Multimedia I/O File Services Resource Interchange File Format (RIFF) Services Sample Application Programs Installing a Program Using MINSTALL Caption DLL High-Level Service API Notices Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

This section describes audio-enabling macros and the high-level service routines designed to simplify writing macros. The service routines are valuable for many applications and are needed for information presentation facility (IPF) support.

The five functions (high-level service API) are: mciPlayFile, mciRecordAudioFile, mciPlayResource, mmioFindElement, and mmioRemoveElement. These functions are located in MCIAPI.DLL. Define INCL_MACHDR and include OS2ME.H in any source that needs access to the high-level service API. The OS/2 Multimedia Programming Reference provides a detailed description of these functions.

Note: These functions are also provided as 16-bit functions. The 16-bit functions include "16" in the function name as follows:

• mci16PlayFile
• mci16PlayResource
• mci16RecordAudioFile
• mmio16FindElement
• mmio16RemoveElement

The mciPlayFile function plays a multimedia file or waveaudio bundle element without displaying a device control panel. The mciPlayResource function operates much the same as mciPlayFile, except that it plays the multimedia object that is stored in a program resource and is intended for IPF support, not audio macros. The function loads the resource using DosGetResource, creates a MMIO memory file, and opens the default device to play the memory file.

The mciRecordAudioFile function provides a very simple recorder window allowing the recording of audio annotations. The mciRecordAudioFile function does not return until the recording is complete and the window is closed. This function creates the file if it does not exist. The mciRecordAudioFile records digital audio data from the microphone input of the default waveaudio device. When the file is initially created the settings are PCM, 11 kHz, mono, and the default sample size of the audio adapter in use. All play and record operations are performed from beginning to end.

The mmioRemoveElement function removes an element from a compound file and the mmioFindElement function enumerates elements in a compound file. For more information on the compound file structure, see RIFF Compound File Overview.

Creating an Audio-Enabled Macro for an Application

Many applications provide macro languages for extending the application's functionality. This is a possible way to integrate multimedia (usually audio) into existing applications. The basic function of an audio macro would be to record audio clips (annotations) and play them. For example, an audio clip can be associated with a location or object in a document such as a spreadsheet or worksheet.

Macros can use compound files to reduce the number of files in the system. Compound files provide a convenient way of grouping multimedia objects that are used together. The compound file structure provides for direct access to multimedia data elements.

If you were to annotate the cells of a spreadsheet and store the audio clips in a single compound file, the cell labels can be used as element names for the elements in the compound file. Then the macro can call mciRecordAudioFile and mciPlayFile to record and play back the elements of the compound file. The compound file can have the same base name as the worksheet and a file extension of .BND. This naming convention identifies which worksheet the audio files belong to. The macro does not need to keep track of cells that are moved on a worksheet, only the cell name is necessary to access the corresponding audio element of a compound file.

The audio file is created when you record or save the audio file. If you exit from a worksheet and choose not to save changes, the audio file will still exist. There is no way to recover an audio file after it is deleted (using mmioRemoveElement).

If a macro uses compound files and elements are deleted with mmioRemoveElement, the size of the compound file does not change. By specifying the MMIO_RE_COMPACT flag, a macro requests that the compound file be compacted after the element is removed. This allows audio recording into an existing wave element that can exceed the current size of the element. The resulting compound file can be compacted to save disk space.

Creating a REXX Command File Using MCI String Commands

Audio functions can be called with REXX command files. The audio functions available are mciRxSendString(), mciRxInit(), mciRxExit(), mciRxGetError(), and mciRxGetDeviceID(). OS/2 multimedia provides examples of REXX command files; PLAY.CMD and RECORD.CMD demonstrate how to play and record audio files. Multimedia with REXX, an online reference provided with OS/2 multimedia, contains more detailed information on the REXX string interface.

Duet Player IPF Sample

The Streaming Device Duet Sample (DUET1) uses mciPlayFile to play audio help. When the application receives an HM_INFORM message, mciPlayFile is issued as shown in the following code fragment.

    case HM_INFORM:
 /*
  * The user has selected the "Play Audio Help" selection in the
  * IPF help panel.
  *
  * To initiate the playing of audio help, we need to issue
  * mciPlayFile.
  *
  * Note that we assume the HM_INFORM message came from the "Play
  * Audio Help" selection since it is the only :link. with an inform
  * reftype in the .ipf file.  If there were more, we would have to
  * check the resource identifier to determine for which selection
  * this message was generated.
  */

 /*
  * Load the name of the audio help file from the resource.
  */
 WinLoadString( hab,
                (HMODULE) NULL,
                IDS_HELP_WAVEFILE,
                (SHORT) sizeof( achAudioHelpFile),
                achAudioHelpFile);

 ulError = mciPlayFile( (HWND)NULL,            /* Ignore owner
                                                  window            */
                        (PSZ)achAudioHelpFile, /* Audio file
                                                  to play           */
                        MCI_ASYNC,             /* Command processed
                                                  asynchronously    */
                        (PSZ)NULL,             /* Ignore title      */
                        (HWND)NULL );          /* Ignore viewport
                                                  window            */
 if (ulError)
 {
    ShowMCIErrorMessage( ulError);
 }
 return( (MRESULT) 0);