Media Control Interface (MCI) Driver Programmer's Reference Guide

Release 2.12a

Copyright 1995 Hauppauge Computer Works, Inc. ALL RIGHTS RESERVED.

This document is copyrighted by Hauppauge Computer Works, Inc.

Restricted Rights Legend

Use, duplication, or disclosure by the Government is subject to restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at 252.277-7013.

Introduction to the Media Control Interface

MCI (Media Control Interface) is high-level control software that provides a device-independent interface to multimedia devices and media files. MCI includes a command-message interface and a command-string interface. These interfaces are supported by both IBM and Microsoft.

MCI command-strings are sent to MCI device drivers with the mciSendString and mciExecute functions, which translate the command strings into command-messages.

Using the MCI is one of the easist ways to control the Win/TV board. Many popular commercial Multimedia presentation packages such as Macromedia Authorware and Aymmetrix Toolbook allow the user to control multimedia devices by sending MCI commands at the command-string level. Others communicate with the hardware directly using the command-message interface.

This document describes the Hauppauge Computer Works Win/TV MCI command-string interface. These MCI functions will allow the multimedia developer to easily add Win/TV capabilites to their application, such as putting a live video window on their screen, freezing the live video, saving a video image to disk, changing the TV channel, etc.

Here is an example of a MCI command sequence to turn on the Win/TV, set the channel, freeze the video and save an image. This example might be run as a script from Authorware: 

	open overlay alias wintv
        put wintv destination at 100 100 50 80
        set wintv channel to 7
	freeze wintv
        save wintv test.bmp type 1
        unfreeze wintv
	close wintv
The MCI command set described for the Win/TV is largely a subset of commands described in the "Digital Video Command Set for the Media Control Interface" (Microsoft Part No. 098-37538). For a more complete understanding of the MCI and its control of other devices besides the Win/TV video overlay device, you can download a file called "MCI.EXE" from the Microsoft FTP server in the directory: /softlib/mslfiles. This file contains an example of the MCI control of a CD player.

About MCI Device Command Strings

MCI command strings are sent to MCI device drivers with the mciSendString and mciExecute functions. The commands divide into the following categories:

System Commands - Interpreted directly by MCI rather than being relayed to a device.
Required Commands - Are supported by all MCI devices.
Basic Commands- Are optional commands.
Extended Commands - Are specific to a device type or device class. These extended commands contain both unique commands and extensions to the required and basic commands. The Win/TV supports several extended commands to control the TV tuner and TV audio.

This document will discuss only those Required, Basic and Extended commands that relate to the Win/TV boards, which are video overlay class devices. It is assumed that an understanding of Multimedia programming for Windows and of MCI System commands already exist.

Win/TV Video Overlay Device Command Overview

The Win/TV board is a video overlay device (from the MCI point of view) that also has a TV tuner and audio controls. Video overlay devices support the following set of commands which are a subset of those supported for digital video devices. Video overlay devices also support notify, test and wait as optional flags. You can add either or all of these flags to any digital-video command. 
Command	          Brief Description
==============================================================
capability        Obtains the capabilities of a device.
close             Closes the device.
freeze            Disables video acquisition to the frame buffer.
info              Obtains textual information from a device.
load              Recalls data from a disk file.
open              Initializes the device.
put               Defines the source, destination and frame windows.
save              Saves data to a disk file.
set               Sets the operating  state of a device.
status            Obtains status information from the device.
unfreeze          Enables the frame buffer to acquire video data.
where             Obtains the rectangle specifying the source, destination or frame area.
window            Sets the window for the display of overlay video.

Extended commands recognized by the Win/TV

Set               For setting audio volume and changing channels.	
Setaudio          This command sets he audio volume,bass, trebles,balance and source.
Setvideo          This command will set color, tint, contrast, brightness and video 	source.

Creating Command Strings

In order to put together a command string you need to be familiar with some basic rules of syntax. A command string is made up of three pieces of information: the command element, the device_id element, and the arguments element.

A command string takes the form:

command   device_id   arguments

Example 1: A sample MCI command string
In this example, the capability command instructs the overlay device to return information about its ability to freeze live video. The Win/TV would return the value "True" since it can freeze the video.
capability overlay can freeze
where:
capability is the command element
overlay is the device_id element
can freeze is the arguments element

The Command Component

Every MCI command string must begin with an MCI command. The command includes a command from the system, required, basic or extended command set. Examples of commands includes open, close, and play.

The Device ID Component

Every MCI device command string includes a device_id element that tells MCI where you want to direct the command. MCI accepts the names of MCI device types and names of device elements for the device_id. An example of a device type is overlay.

Depending on the device you are using, the device_id element must specify different information. Some devices (such as a CD audio player) are known as simple devices because they require only the name of the device as the device_id element. Other devices (such as animation players) are known as compound devices because they require the name of the device and the name of the filename used by the device.

The Arguments Component

Arguments are the flags and parameters used by the command that you specify. As mentioned previously, flags are keywords supported by an MCI command. Parameters consist of additional numeric or string data that you must supply to either the command or a flag that you are using.

Example 2: The save command
For example, one of the basic commands is the save command. You can use the save command with the at flag and the rectangle parameter to specify the block of data that is to be saved. The command would appear as follows:

	save overlay xxx.bmp at 0 0 50 50
where:
save is the command
overlay is the device
xxx.bmp is the filename parameter (24 bit DIB by default)
at is the optional flag
0 0 50 50 is the parameter (rectangle)

MCI commands that need parameters typically require you to provide the following kinds information::

Integers - Make sure to use a blank space before and after an integer. Unless otherwise specified, integers can be positive or negative. If you are using a negative integer do not leave a space between the negative sign and the first digit. As an example, you specify an integer when you use the samplespersec command to set the sample rate for playing and recording wave audio.

Rectangle - Some commands will require that you specify four integer values that describe a rectangular area. The first two integers are the coordinates of the top left corner of the rectangle and the second two integers are the width and height of the rectangle. For example, you specify a rectangle when you use the freeze command to freeze a video image via an overlay device.

About MCI Device Types

The following table gives a description of the MCI devices, the name of the device as it would appear in a command string, and an indication of whether the device is simple or compound: 
Device Description	Device Name	Simple or Compound
==================================================================
Animation player         animation             compound
CD audio player          cdaudio               simple
Overlay device           overlay               compound
MIDI sequencer           sequencer             compound
Videodisc player         videodisc             simple
Audio device that plays digitized waveform files
                         waveaudio             compound
The [mci] section of the SYSTEM.INI file lists the device types installed on your system. If you have a device type installed more than once, the device type names have numbers attached to them. For example, if you have two cdaudio type devices installed on your system they will be identified as cdaudio1 and cdaudio2. Here is an example of what the [mci] section might look like after the Win/TV video overlay driver is installed:
[mci]
mixer=mcimixer.drv
sequencer=mciseq.drv
WaveAudio=mciwave.drv 4
AVIvideo=mciavi.drv
cdaudio=mcicda.drv
GDAnim=mciawi.drv
overlay=MCIVideo.drv

Example 3: Simple Devices
CD audio devices and videodisc players are simple devices. As mentioned previously, when you are using a simple device, you need only specify the device name as the device_id element of the command string. For example, before you can use a device, you need to initialize it with the open command. You could specify the following command to initialize a CD audio player you plan to work with. 

   open  cdaudio
where:
open is the command element
cdaudio is the device_id element

Example 4: Compound Devices
MIDI sequencers, waveform audio devices, animation players, and overlay cards are compound devices. As mentioned previously, when you are using a compound device, such as a MIDI sequencer, you have to specify additional information as the device_id element of the command string. You need to specify the full path and filename for the MIDI file you are using and you have to specify the type flag, and then the the actual device name.
Note: Flags are keywords supported by an MCI command. For example, when you use the play command with a CD audio player, you can also use the from and to flags to play a particular portion of the CD.
When you initialize a MIDI sequencer, you might specify the command string: 

	open d:\music\sonata1.mid type sequencer
where:
open is the command element
the remaining part of the command string is the device_id element:
d:\music\sonata1.mid is the full path and filename of the MIDI file
type is the flag that precedes the name of the device type
sequencer is the device type
Note: If you use the open command with a compound device type and specify only the device type, for example, open animation, only limited commands for that device type are available. As an example, once you issue the open animation command you can use the capability command to find out the capabilities of that device, but you cannot use a play command to play that device.

Opening and Closing MCI Devices

Before using a device, you must initialize it with the open command. The number of devices you can have open depends on the amount of available memory. The close command releases access to a device (or a file used by a device). To help MCI manage the devices, your application must explicitly close each device (or file) when it is finished with it.

Obtaining Information from MCI Devices

Every device responds to the capability, status, and info commands. These commands obtain information about the device. Example:
capability  overlay  freeze
This command returns true to indicate that the device is capable of freezing video in the frame buffer.

Using Flags

Using the Alias Flag

The preceding section described how a compound device requires that you specify a full path and filename, the type flag, and the device type. Typically, you will issue a number of command strings in an MCI aware application that all have to include this information as the device_id element.
Because it would be tedious to keep repeating that same lengthy portion of the command string, MCI lets you take all of the information in the device_id element and use the alias flag to assign it an alias (an alternative, shorter name). If your application creates an alias it must use the alias as the device_id for all subsequent references.The following series of commands strings show how you might set and use an alias:
	open overlay alias wintv
	window wintv	.
	.
	.
	close wintv
In this example, the first command string uses the alias flag to assign the alias wintv to the video overlay device, path, and filename. From that point on, the expression wintv is used as the device_id element in command strings.

Using the Type Flag

See "Creating Command Strings."

Using the Shareable Flag

The shareable flag lets multiple applications access the same device concurrently. That is, different applications can use the same device (such as a CD audio player). If your application opens a device without the shareable flag, no other application can access it simultaneously. If your application opens a device as shareable other applications can access it by also opening it as shareable.
The shared device gives each application the ability to change the parameters governing the operating state of the device. If you make a device shareable your application should not make any assumptions about the state of that device. When you work with shared devices your application might need to compensate for changes made by other applications using the same services.

Using the Alias Flag

See "Creating Command Strings."

Using the All Flag

You can specify all as a device name for any command that does not return information. When you specify the all flag, MCI sequentially sends the command to all devices opened by the current application. Example: 
	close  all
closes all open devices. Because MCI sequentially sends the commands to the MCI devices, there is a delay between when the first device receives the command and when the last device receives the command.

Using the New Flag

MCI lets you use command strings to create new files, but you don't have to name the file until you use a save command to actually save it. To create a new file without specifying a filename, you can specify the new flag. If you use the new flag, you must also use an alias flag.

Using the Wait Flag

Normally, MCI commands return to the application immediately, even if it takes several minutes to complete the action initiated by the command. One way to modify the default behavior is to use the wait flag that is supported by MCI.

Using the Notify Flag

The notify flag directs the device to post an MM_MCINOTIFY message to a specified window when the requested action is complete.
Normally, MCI commands return to the user immediately, even if it takes several minutes to complete the action initiated by the command. Either the wait flag or the notify flag can be used to modifiy this default behavior.

Using the Test Flag

This flag will be supported in a later revision.

Supported Win/TV Video Overlay Commands

The following tables describe the MCI commands supported by this release of the Win/TV Media Control Interface Driver. Note that the response of certain commands, such as capability, are particular to the Win/TV. Other types of devices might return different values. To construct a command, follow the basic syntax: 
 command  device_id  arguments
The device_id for all video overlay device commands is overlay. If multiple drivers of the same type are installed, a numeral will be added to the device_id argument. For example, if three Win/TV boards were installed in your system, the first would have device_id overlay, the second would have device_id overlay1 and the third would have device_id overlay2.
If a command takes any arguments, the command description states whether the arguments are optional or required. Arguments are made up of flags (keywords) and/or parameters (variable information). Flags appear in bold type, for example, can eject. Parameters appear in italicized type, for example, rectangle, where you are expected to substitute a value for the parameter rectangle.
For detailed information on how to construct command strings, see "Creating Command Strings" earlier in this document. 
capability

Requests information about the capabilities of a video overlay device. This 
command requires one of the following argument elements.
can eject       Returns false.
can freeze      Returns true, since the device can freeze data in 
                the frame buffer.
can play        Returns false.
can record      Returns false.
can save        Returns true, since the device can save the current contents 
                of the frame buffer to disk.
can stretch     Returns false.
compound device Returns false, since multiple windows are not supported, 
                and the device does not support and element name.
device type     Returns overlay device type.
has audio       Returns false, since the device does not support audio playback.
has video       Returns true.
uses files      Returns false.
windows         Returns the number of simultaneous display windows the device can
	        support, 1.

close

Closes a video overlay element and any resources associated with it.  This
command does not use an arguments element.

freeze

Disables video acquisition to the frame buffer.  This is supported only if
capability can freeze returns true.

info

Fills a user-supplied buffer with information.  This command requires an
arguments element.
file            Returns the name of the file used by the video overlay device. 
                This argument is valid only if capability uses files returns true.
product         Returns the product name and model of the current device, 
                Hauppauge Computer Works Win/TV Video Overlay Device.
window text     Returns the caption of the window used by the device, 
                Hauppauge Computer Works Win/TV.

load

Loads the contents of the video buffer in a device specific format.  This
command requires an arguments element.
filename        Specifies the file and pathname used to load the data.
at rectangle    Specifies the rectangle relative to the video buffer origin.
                The rectangle is specified as X1 Y1 X2 Y2.  The coordinates 
                X1 Y1 describe the top, left corner of the rectangle and 
                X2 Y2 describe the width and height.

open
	
Initializes the video overlay device.  This command requires an arguments 
element.
alias device_alias   Specifies an alternate name for the video overlay device.  
                If specified, it must also be used for subsequent references.
                (See "Using Flags" earlier in this manual)
parent hwnd     Specifies the window handle of the parent window.
shareable	Initializes a device element as shareable.  Subsequent 
                attempts to open it fail unless you specify shareable in both 
                the original and subsequent open commands.  MCI returns an 
                invalid device error if it is already open and not shareable.
                (See "Hints for Using Flags" earlier in this manual.)
style style_type  Indicates a window style.
style child     Opens a window with a child window style.
style overlapped  Opens a window with an overlapped window style.
style popup     Opens a window with a popup window style.
type device_type   Specifies the device type of the device element.  MCI reserves overlay 
                for the video overlay device type.  As an alternative to type, 
                MCI can use the [mci extension] entries in the SYSTEM.INI file to 
                select the controlling device based on the extension used by the 
                device element.

put
	
Defines the source, destination, and frame windows.  This command requires 
an arguments element.
destination     Sets the whole window as the destination window. This 
                completed command defines the VGA window.
destination at rectangle   Specify a rectangle for the area of the 
                window used to display the image. The rectangle coordinates 
                are relative to the window origin and are specified as 
                X1 Y1 X2 Y2.  The coordinates X1 Y1 describe the top left 	
	        corner of the rectangle and the coordinates X2 Y2 describe the 
                width and height of the rectangle.  When an area of the 
                display window is specified and the device supports stretching, 
                the source image is stretched to fill the destination 
                rectangle.
frame	        Specifies that the whole video buffer is used to capture the 
                video image. This completed command defines the capture 
                rectangle in the video buffer.
frame at rectangle	
                Specify a rectangle for the area of the video buffer used to 
                capture the video image.  The rectangle coordinates are 
                relative to the video buffer origin and are specified as 
                X1 Y1 X2 Y2.  The coordinates X1 Y1 describe the top left 
                corner of the rectangle and the coordinates X2 Y2 describe 
                the width and height of the rectangle.  If the device supports 
                stretching, the video image is stretched to fill the rectangle.
source          Selects the whole video buffer for display in the destination window. This
	        completed command defines the source rectangle in the frame buffer.
source at rectangle	
	        Specifies a rectangle for the video buffer area used to obtain the image for
	        display.  The rectangle coordinates are relative to the video buffer origin
	        and are specified as X1 Y1 X2 Y2.  The coordinates X1 Y1 describe the
                top left corner of the rectangle and the coordinates X2 Y2 describe the width
	        and height of the rectangle.  When an area of the source image is specified
	        and the device supports stretching, the source image is stretched to fill the
	        destination rectangle.
video	        Selects the whole video source for display in the destination window. This
	        completed command defines the acquisition window.
video at rectangle
                Specifies a rectangle for the input video source area used to 
                obtain the image for display.  The rectangle coordinates are 
                relative to the video buffer origin and are specified as 
                X1 Y1 X2 Y2.  The coordinates X1 Y1 describe the top left 
                corner of the rectangle and the coordinates X2 Y2 describe 
                the width and height of the rectangle.  When an area of the 
                source image is specified and the device supports stretching, 
                the source image is stretched to fill the destination rectangle.

save

Saves the contents of the video buffer in a device specific format.  This 
command requires an arguments element.
filename        Specifies the file and pathname used to save the data.
at rectangle  Describes a rectangle relative to the video buffer 
        origin, specified as X1 Y1 X2 Y2. The coordinates X1 Y1 describe the 
        top left corner of the rectangle and the coordinates X2 Y2 describe 
        the width and height of the rectangle.
type x   type x values 0-18. The type setting is an extended 
                command. It allows you to choose one of nineteen different 
                file formats for saving frames. The following are:
        NOTE: If type is not used, the default is 256 color dib.
        x       file type  
 	==================
	0	/* Windows DIB 24 bit true color */
	1	/* Windows DIB 8 bit palettized */	Default
	2	/* Windows DIB 8 bit gray-scale */
	3	/* Windows DIB 4 bit dithered */
	4	/* Targa 32 bit true color */
	5	/* Targa 24 bit true color */
	6	/* Targa 16 bit true color */
	7	/* IBM MMotion format 4:1:1 YUV */
	8	/* TIFF 24 bit true color */
	9	/* TIFF 8 bit palettized */
	10	/* TIFF 8 bit gray-scale */
	11	/* PCX 8 bit palettized */
	12	/* PCX 8 bit gray-scale */
	13	/* PCX 4 bit dithered */
	14      /* GIF 8 bit palettized
	15      /* GIF 8 bit gray-scale
	16     	/* JPEG compressed 4:2:2 YUV
	17     	/* BMP monochrome
	18      /* BMP 16 colors palettized

status
	
Obtains status information for the device.  This command requires an 
argument element.
media present   Returns true.
mode            Returns stopped.
ready           Returns true, indicating that the device is ready.
window handle   Returns the handle of the window whose client area is used for the
                destination video in the low-order word of the return value.
stretch         Returns false.
Contrast        Returns contrast value.
Brightness      Returns brightness value.
Color           Returns color value.
Tint            Returns tint value.

unfreeze

Enables the acquisition of video data into the frame buffer. This command
is usually preceeded by a freeze command.

where

Obtains the rectangle specifing the source, destination, or frame area. This
command requires an arguments element.
destination     Requests the offset and extent of the destination rectangle.
frame           Requests the offset and extent of the frame rectangle.
source          Requests the offset and extent of the source rectangle.
video           Requests the offset and extent of the video rectangle.

window

The window command can be used to tell the video overlay device to use
a given window for display instead of the default window created by the 	
driver.  By default, these devices should create a window when opened but
should not display it until they receive the play command.  Applications
providing window handles should manage the display issues that result
when the window is sized or when the window handle is switched during
play.  Several flags manipulate the window.  Since the status command can
obtain the handle to the current display window, you can use the standard
window management functions to manipulate the window. This command
requires an arguments element.
handle window_handle
	        Specifies the handle of the destination window used as an 
                alternate to the default window.
handle default  Specifies that the video overlay device should create 
                and manage its own destination window.  This flag can be 
                used to set the display back to the driver's default window.
state hide      Hides the current display destination window.
state iconic    Displays the destination window as an icon.
state maximized Maximizes the current destination  window.
state minimize  Minimizes the specified window and activates the 
                top-level window in the window-manager's list.
state minimized Minimizes the current destination  window.
state no action Displays the destination window in its recent size 
                and state.  The window that is currently active remains active.
state normal    Activates and displays the current display window in 
                its original size and position, as it was created.
state show      Shows the current destination window, in response to a hide.
text caption    Specifies the caption for the display window.

Extended Win/TV MCI Commands


set
 			
on              Turns Video Overlay On.
off             Turns Video Overlay OFF.
Audio           This command sets the volume level from 0 to 100.
                In some cases not audible until a setting of 50 or higher.
Time format     This function changes channels from 1-125, it is a 
                temporary solution and currently hard coded for US catv 
                (this can be changed- call 516-434-1600 x350 for modified 
                driver).
Source to xx    This function selects the video format. Don't confuse 
                this call with the setvideo source call.
                The ordinal values values 0-6 are as follows:
	0	PAL_BGHI	
	1	NTSC_M		
	2	SECAM		
	3	PAL_M		
	4	PAL_N		
	5	NTSC_443	
	6	EXTERNAL_SRC
channel to xxx  This function set the channel number.  This call is 
                functional only if the WinTV board has a tuner.
                Values are from 1-125 (channels 1 to 125).
tuner region to x This function sets the tuner for the proper RF Region.  
                The ordinal values are 0 to 7 as follows: 
	0	USA
	1	US_CATV		
	2	CCIR            /* Western Europe	*/	
	3	CCIR_CATV       /* Western Europe	*/
	4	AUSTRALIA       /* Austrilia		*/
	5	JAPAN		/* Japan                */
	6	JAPAN_CATV	/* Japan                */
	7	US_HRC	 	/* US CATV HRC          */

setaudio

volume to xx    This command sets the volume level from 0 to 100.
                If using the Celebrity Board the audio level may not be 
                audible until a setting of 50 or higher.
source to xx    This Function selects the audio source. Setting 
                the audio source to 2 selects the tuner, if set to 0 video 
                input 1 is selected and if set to 1 video input 2 is selected.
bass to xx      This Function sets the BASS levels - values 0-100.
treble to xx    This function sets treble levels.- values 0-100
off             Selecting OFF will MUTE the audio .
on              Selecting ON will UNMUTE the audio.
stream to xx    Sets the Balance between left and right. 
                Where 0 = full left and 100 = full right.

setvideo

on          Turns Video Overlay On.
off         Turns Video Overlay OFF.
source to xx    If set to 0 video input 1 is selected, if set to 
                1 video input 2 selected, if set to 2 the tuner will be 
                selected.
brightness to xx sets brightness level.- values 1-255.
contrast to xx	sets contrast level- values 1-255.
color to xx 	sets hue value - values 1-255.
tint to xx	sets saturation level - values 1-255.

Win/TV MCI Driver Installation

To install the driver software you must have Multimedia Windows already installed on your system. Start up Windows and make sure that the driver diskette is in a floppy drive.

Go to the Windows Control Panel and double click on the Drivers icon. Select Add and Add Unknown. Select the driver to be installed and click on OK. The MCI driver is then installed. If multiple boards are installed in your system, you may want to install the corresponding MCI drivers by repeating the above process once for each driver.

The installation under Windows 3.0 will not use the new files on the floppy but will (quietly) use the (old) files on the hard disk if available.

The installation program under Windows 3.1 will ask if you would prefer to use the older version of the driver, etc. on your system.

To avoid these problems, if you have installed a previous version of the MCI driver, please remove the driver first, using the Control Panel, exit to DOS, and run the MCICLEAN.BAT provided on the install floppy.

[Back to Tips] Back to Tips Page

Questions, comments, or problems regarding this service?

Copyright © 1995 Hauppauge Computer Works, Inc. All rights reserved.
The Hauppauge logo and Win/TV are registered trademarks of Hauppauge Computer Works, Inc. Windows, Windows 95 and Windows NT are trademarks of Microsoft Corp.