ELSAmotion Command Strings

The MPEG Player device driver uses the following subset of the Media Control Interface (MCI) Digital Video command set. Additional commands from the MCI command set may be added at a later date.

For details of the full Digital Video command set, see "Multimedia Standards Update - Digital Video Command Set for the Media Control Interface, September 29, 1994 Revision: 1.0, Part # 098-37538" published by Microsoft.

The MPEG Player device driver supports notify, test, and wait as optional flags. You can add any or all of these flags to any digital command.

Please remember to use the alias, as defined in the open command, as the first parameter for every MCI-command.

Copyright ELSA GmbH. 1995

•	capability	•	open	•	setvideo
•	capture	•	pause	•	signal
•	close	•	play	•	status
•	configure	•	put	•	step
•	copy	•	realize	•	stop
•	cue	•	resume	•	unfreeze
•	freeze	•	seek	•	update
•	info	•	set	•	where
•	load	•	setaudio	•	window


ELSAmotion Command Strings
ELSAmotion Command Summary

- A -

- B -

- C -

capability

capture

close

configure

cue

- D -

- E -

- F -

freeze

- G -

- H -

- I -

info

- J -

- K -

- L -

load

- M -

- N -

- O -

open

- P -

pause

play

put

- Q -

- R -

realize

resume

- S -

seek

set

setaudio

setvideo

signal

status

step

stop

- T -

- U -

unfreeze

update

- V -

- W -

where

window

- X -

- Y -

- Z -


capbility description
capability	Description

capability items	Fills an application-supplied buffer with a string containing information about the capabilities of the digitalvideo device. The item is one of the following:

can eject	Returns false, device can´t eject media

can freeze	Returns true, device can freeze data in the frame buffer

can lock	Returns false, the device doesn´t support a lock mask to lock portions of the image with the freeze and unfreeze commands.

can play	ELSAmotion returns true.

can record	Returns false. Device can´t digitize audio or video data.

can reverse	Returns false. Device can´t play files in reverse.

can save	Returns false, device can´t store digitized video to disk.

can stretch	Returns true, device can  resize an image or motion video in the process of writing it from the frame buffer to the display.

can stretch input	Returns true, device can resize an image or motion video in the process of digitizing it into the frame buffer.

can test	Returns true, device recognizes the test keyword.

compound device	ELSA MPEG returns true, ELSA VideoCD / CD-i returns false. Device takes filename / doesn´t take filename.

device type	Returns digitalvideo / videocd depending on how the device was opened

has audio	Returns true, device supports audio playback.

has still	Returns false, no special still frame support.

has video	Returns true, device supports video playback.

maximum play rate	Returns the maximum play rate in frames per second (30).

minimum play rate	Returns the minimum play rate in frames per second (24).

uses files	MPEG returns true (it uses files), VideoCD returns false.

uses palettes	Returns true if images and video use a palette for display (in 8 bit primary mode only). It returns false otherwise.

windows	Returns the maximum number of simultaneous display windows the device can support. ELSAmotion can support just one window.


capture	Description

capture items	Copies the contents of the frame buffer and stores it in the specified file. The updating momentarily pauses so that a complete image is captured. If the device pauses the updating, there might be a visual or audible effect. The following items modify this command:

as pathname	Specifies the destination path and filename for the captured image. This item is required.

at rectangle	Parameter has no effect by now. Specifies the rectangular region within the frame buffer the device crops and saves to disk. If omitted, the cropped region defaults to the rectangle specified or defaulted on a previous put source command for this device instance.


close	Description

close	Closes an instance of the digitalvideo device and releases all resources associated with it. If the window is a default window, it is destroyed; otherwise the contents of the window are not defined


configure
configure	Description

configure	Displays a dialog box used to change device features.


copy	Description

copy items	Copies video data onto the Clipboard without modifying the workspace. The following items modify this command.

at rectangle	Parameter has no effect by now. Specifies the portion of each frame that will be copied. If omitted, it defaults to the entire frame.


cue	Description

cue items	Prepares ELSAmotion for playback. When a device is cued, the device performs whatever time consuming operations it can do in advance so that the play command will start quickly. This command switches a device instance in a stopped state to a paused state. This command is modified by the following optional items:

to position	Specifies the position in the workspace. Unlike seek to position, cue to position always finishes in paused mode. The default is the current position.

noshow	Positions the workspace without changing the displayed image or the contents of the frame buffer. However, it changes the current position to that specified in the to parameter and gets ready to display that frame. For example, the cue to 5 noshow  command positions the device at frame 5 without displaying the image of frame 5. Subsequently, sending cue without noshow displays the image.


freeze	Description

freeze	Stops the updating of the frame buffer from the presentation source. It has no effect on the presentation source itself, which can continue to generate images that are discarded.


info	Description

info items	Fills a user-supplied buffer with a string containing information about the device or driver instance. The following optional items modify info:

file	Returns the full path of the file specified with the last open or load. If the device is opened without a file and the load command has not been used, then a null string is returned

product	Returns the product name.

version	Returns the release level of the device driver and hardware

window text	Returns the text string in the title bar of the window associated with the device instance.


load	Description

load items	Loads a file into the workspace for the device instance. Files loaded using this command cannot be shared. Loading a file cancels any signals set for the device instance. After loading a file, the return value of status mode is stopped. This command is modified by the following item:

filename	Specifies the path and filename for the file loaded into the workspace. This item is required.


open	Description

open items	Initializes an instance of the device driver. Each open creates an independent instance of the device, which can be referenced by its device name. The following items modify open:

alias alias	Specifies an alias used to reference this instance of the device. The open is rejected if the alias is already in use by this application. If this item is omitted, the default device name is the specified filename.

element 	Additional parameter, can be placed in front of the filename.

filename	Depicts the file to be opened.

parent hwnd	Specifies the parent of the default window. This item is only used with a window style that requires the specification of a parent or owner. hwnd is the ASCII decimal equivalent of the parent windows handle.

shareable	Specifies that a single instance of the associated file can be accessed by two or more device instances. That is, file positioning commands directed towards one of these instances will affect the position in all the instances. Each instance can, however, have an independent window as well as other characteristics not directly related to file positioning. If the device uses only a single instance of digitizer hardware, then this flag also lets a single digitizer frame buffer be shared by multiple device instances.

style StyleValue	Specifies the style used for the default window. The StyleValue is the ASCII decimal WS_OVERLAPPED. In addition, the following constants are defined for StyleValue: overlapped, popup, and child.

type device_type	Specifies the device type of the device element. If omitted, MCI selects the device based on the filename extensions listed in the [mci extensions] section of the WIN.INI file.


pause	Description

pause	Pauses the playing of motion video or audio. The last displayed image remains visible and the device instance remains cued. The play and resume commands continue the operation of a paused device. If pause follows a play notify, the notification is not aborted


play	Description

play items	Starts the generation of audio and/or video signals from the data in the workspace. Play causes an implied selection of the workspace as the presentation source. If setvideo is on, play displays a default hidden window. When a device finishes playing, its mode is the same as defined for seek. The following optional items modify play:

from position	Specifies the position to seek to before beginning playback. The position value is specified in the current time format. The position the device uses is affected by whether seek exactly is on or off.
If this flag is omitted and playing is currently paused or the device is cued, playing starts at the current position. If it is omitted and playing is stopped, the resulting seek might require changing the position to a previous key frame image.

repeat	Specifies that the playback should repeat until it is paused or stopped. Each iteration uses all the flags specified for the play command. If a from position is not specified using this command, the second and subsequent iterations start at the beginning of the media.
Pausing play does not cancel the repeat flag.

to position	Specifies the position to stop playing. When the current time format is frames, the position value is the number of the frame displayed when the motion video stops. Audio associated with the frame specified for to is not played by most devices. The to position is not affected by the seek exactly state. If to is not specified, playing continues until the last valid position is reached. In either case, when playing is done, the workspace has an image displayed in the window.


put	Description

put items	Specifies a rectangular region that describes a cropping or scaling option. A flag indicating the video source or destination (for example, destination, frame, source, or window) must be specified with this command. The following items modify put:

at rectangle	Specifies the rectangle used for one of the modifier items for this command.
If a rectangle is not specified for a video source or destination, it defaults to the full image. A rectangle consists of four integer values denoting the coordinates of the upper-left pixel and the width and height of the rectangle. Each integer is delimited by one or more spaces. The pixel origin is defined such that pixel (0,0) is in the upper-left corner of the client rectangle, frame buffer or input depending on the specified region.

destination	Specifies the portion of the client window used to show the image or video. The destination rectangle is specified relative to the upper-left corner of the client window in pixel coordinates. The default rectangle is the full client area.
The device instance will, to the best of its ability, linearly scale the rectangle specified by put source to the specified portion of the display. Devices that do not support a capability of can stretch, or cannot perform the specific stretch indicated, might display a different sized image starting at the designated upper-left pixel. If the specified rectangle is outside the client region, then no pixels are drawn. Devices that cannot shrink the image to the requested size crop the right and bottom of the image or video to avoid drawing outside the destination rectangle.

frame	Specifies which portion of the frame buffer, in frame buffer coordinates, the video rectangle should be scaled to fit within. The default rectangle is the full frame buffer. Specifying this rectangle lets the hardware scale the data as it is digitized.

source	Specifies which portion of the frame buffer, in frame buffer coordinates, is scaled to fit in the destination rectangle.

window	Changes the size and location of the display window. The rectangle specified with the at flag is relative to the parent window of the display window (usually the desktop). If the rectangle is not specified, it defaults to the initial window size and position. (This is usually set to an optimum size and aspect ratio.)

window client	Changes the size and location of the client window. This is the same as put window except that the specified rectangle is the position of the client rectangle rather than the position of the display window. See the Windows AdjustWindowRect function for more information about client rectangles.


realize	Description

realize items	Tells the device to select and realize its palette into a display context of the displayed window. This command applies only to devices that use palettes. For more information, see the description of SelectPalette in the Windows 3.1 Programmers Reference. This command will only have an effect if used in 8 bit primary mode. One of the following items modifies realize:

background	Realizes the background palette.

normal	Realizes the palette normally. This is the default.


resume	Description

resume 	Specifies playing should continue from where it was interrupted by a pause or stop command. The to position specified using the original play command is remembered, as well as any other flags that were specified. Resume is always allowed, even if play has not been previously used. In this case, it is the same as a play with no parameters.
If any commands used notify between the pause and the resume commands, it supersedes any pending notify from the original play command. When the notify flag is used with resume, MCI notifies the application when the resumed play or record completes.


seek	Description

seek items	Positions the workspace. At the end of the seek, the device shows the specified frame. Depending on the device, the mode after a seek is paused.
(Devices might make a tradeoff between the need to begin play quickly and the need to conserve resources used while paused.) If a device is stopped after seek then an image must be shown in stopped mode. The following items modify seek:

to position	Specifies the desired new position in units of the current time format. If seek exactly is set off, seek positions the workspace at approximately the requested frame. In general, if the requested frame is interframe encoded, seek positions the workspace at a nearby, previous key frame image. There are two exceptions to this positioning rule.
The first exception is if the to position follows the current position but is before the next key frame image. In this case, the device maintains the current position.

to end	Positions the workspace to the last frame. If seek exactly is off, this might seek to the last key frame image.

to start	Positions the workspace to the first frame.

offset bytes	Positions to the given position in bytes from start of file.

frameref frame	Declares the current position as referenced by the given framenumber.


set	Description

set items	Sets the state of various control items. One of the following items must be included:

audio all on /off	Enables or disables audio. This command affects the left and right audio channel simultaneously. The default is set audio on.

audio left on/off	Enables or disables the left audio channel.

audio right on/off	Enables or disables the right audio channel.

door closed	Returns MCIERR_UNSUPPORTED_FUNCTION.

door open	Returns MCIERR_UNSUPPORTED_FUNCTION.

seek exactly on	Parameter returns MCI_UNKNOWN_PARAMETER by now. Selects one of two seek modes.

seek exactly off	If seek exactly is on, then the seek, play from, and record from commands will precisely access the requested frame. This might cause an extra delay if the requested frame is not a key frame. (In this case, the device must decode previous frames to decode the requested frame.)
If seek exactly is off, the device will seek to a key frame image that precedes the requested frame. For some devices, and some files, this might be the first frame of the file.
The default for seek exactly is off.

speed factor	Sets the relative speed of video and audio playback from the workspace. Factor is the ratio between the nominal frame rate and the desired frame rate where the nominal frame rate is designated as 1000. By now, only 1000 (normal speed) and 2000 (double speed) take effect.

time format format	Sets the time format to format. All position information is specified in this format following this command. The driver supports a time format of frames, track, tmsf (Track, Minute, Second, Frame) and milliseconds. The default time format is milliseconds. Milliseconds can be abbreviated ms.

video on/off	Enables or disables display of video.Disabling video sets the pixels in the put destination rectangle (or its default, the client region of the current window) to a solid color. It has no effect on the frame buffer. The video source continues to store new images in the frame buffer. They are not displayed until video is enabled. If desired, you can use the window state command to hide the window. The default is video on.


setaudio	Description

setaudio items	Sets various values associated with audio playback. Some parameters used in the items list are specified as a factor. For these items, 0 represents a minimal amount of the specified characteristic, and 1000 represents the maximum value. To determine the value that indicates no change from the presentation source use the nominal flag with the status command. The linearity of these values is device-specific. If a device cannot set the requested factor, it uses the closest value it supports. You can use the status command to determine the actual values set by the device. The setaudio command is modified by the following items (only one of these items can be present in a single command unless otherwise noted):

left on /off	Enables or disables audio output on the left channel.
The default is left on. If there is only one channel is set on or off.

left volume to factor	Sets the audio volume of the left audio channel. If there is only one channel it sets its volume.

on /off	Enables or disables audio. This command affects the left and right audio channel simultaneously. The default is setaudio on.

right on / off	Enables or disables audio output on the right channel.
The default is right on. If there is only one channel, this flag has no effect

right volume to factor	Sets the audio volume to the right audio channel. If there is only one channel, it has no effect

stream to number	Specifies the audio stream played back from the workspace. If the stream is not specified and the file format does not define a default, then the physically first interleaved audio stream will be played.
Only streams 0 for off or 1 for default channel are supported.

volume to factor	Sets the average audio volume for both audio channels.


setvideo	Description

setvideo items	Sets various values associated with video and still playback and capture. You can use the status command to determine the actual values set by the device. The setvideo command is modified by the following items (only one of these items can be present in a single command unless otherwise noted):

key color to r:g:b	Parameter has no effect by now. Sets the key color. The r:g:b parameter is a Windows RGB value. Colons (:) separate the individual red, green, and blue values.

key index to index	Parameter has no effect by now. Sets the key index. The index parameter is a physical palette index.

off / on	Enables or disables display of video.

Disabling video sets the pixels in the put destination rectangle (or its default, the client region of the current window) to a solid color. It has no effect on the frame buffer.
The video source continues to store new images in the frame buffer. They are not displayed until video is enabled. If desired, you can use the window state command to hide the window. The default is setvideo on.

stream to number	Specifies the video stream played back from the workspace. If the stream is not specified and a default stream is not defined by the file format, the physically first interleaved video stream is played.
Only streams 0 for off or 1 for default channel are supported.


signal	Description

signal items	Marks positions in the workspace. The signals are valid until another signal command moves or disables them, or the contents of the workspace change. Whenever data at a signal is presented (the device plays or steps to it), the device sends a Windows message to the application. The message identifies the device and a user value; optionally, it identifies the position. Although the window used for notify will receive the signal messages, the signal mechanism is entirely independent of the behavior of the notify and wait flags.

at position	Specifies the location of the signal. The position value is in the current time format.

cancel	Removes signals from the workspace. An individual signal is specified using the uservalue flag. If the uservalue flag is not specified using cancel, the device cancels all signals. The cancel flag is incompatible with the at, every, position, and return position flags.

every interval	Specifies the period of the signals. The interval value is specified in the current time format.
If used with at position, signals are placed throughout the workspace with one signal mark placed at position.
Without the at flag, signals are places throughout the workspace with one signal at the current position.
If this flag is omitted, only the position indicated by the at flag is marked.
If the interval value is less than the minimum frequency supported by a device, it will use its minimum value.

return position	Indicates the device should send the position value instead of the uservalue ID in the signalling message. The uservalue ID can still be used to cancel or to redefine the signal marks.

uservalue id	Specifies an ID that is reported back with the signaling message. This ID acts as an identifier that can be used with other signal commands to reference this signal setting. If omitted, the default value is zero.


status	Description

status items	Returns status information about a device instance. One of the following items modifies status:

audio	Returns on or off depending on the most recent setaudio on or off command. It returns on if either or both speakers are enabled, and off otherwise.

audio bitrate	Returns the average number of bytes per second.

audio samples per	Returns the audio sampling rate.

second

audio stream	Returns the current audio-stream number.

audio streams	Returns the number of  audio-streams.

current track	Returns 1 on MPEG, on VideoCD the actual track number.

left volume	Returns the volume set for the left audio channel.

length	Returns the duration of the file in the workspace. The value returned is the length of the longest active stream. This is in units of the current time format. The flag returns zero if the workspace is empty.

length track TrackNo	Returns the same value as status length on MPEG, if TrackNo is 1. On VideoCD, the length of the given TrackNo is returned.

mode	Returns the mode of the device: not ready, paused, playing, or stopped.
If it returns not ready, then retrying the command eventually returns one of the other values unless there is a hardware error. During a step or play operation, it returns playing. After a cue operation has completed, it returns paused. After a stop or load operation, and immediately after an open operation, it returns stopped. After a seek, step, or play operation it returns stopped.

nominal frame rate	Returns the nominal frame rate associated with the file. The units are in frames per second multiplied by 1000.

number of tracks	Typically returns 1 on MPEG, track count on VideoCD.

palette handle	Returns the palette handle used for display of motion video in the low-order word of the return value. This flag is supported only in 8 bit primary mode.

position	Returns the current position in the workspace. This is in units of the current time format.

position track	Returns the same value as status position, if TrackNo is 1.

TrackNo	On VideoCD the distance of the beginning of TrackNo to the start of the media is returned.

ready	Returns true, this device instance is always ready to accept another command.

right volume	Returns the volume set for the right audio channel.

seek exactly	Parameter has no effect by now. Returns on or off indicating whether or not seek exactly is set.

speed	Returns the current playback speed.

start position	Returns the frame number for the first frame in the workspace. It is typically zero or one.

time format	Returns the current time format.

video	Returns on or off, reflecting the state set by setvideo.

video brush	Returns the current video brush.

video key index	Parameter has no effect by now. Returns the value for the key index.

video key color	Parameter has no effect by now. Returns the value for the key color.

video stream	Returns the current video-stream number.

video streams	Returns the number of video-streams.

video bitrate	Returns the current video-bitrate (bytes per second)

video maxbitrate	Returns the maximal bitrate ELSAmotion supports.

volume	Returns the average of the volume to the left and right speakers.

window handle	Returns the ASCII decimal value for the current window handle associated with this device instance.

window visible	Returns true if the window is not hidden.

window minimized	Returns true if the window is minimized.

window maximized	Return true if the window is maximized.


step	Description

step items	Advances the position in the workspace. In addition to moving to a following image, this command selects the workspace as the presentation source, and stores the new image in the frame buffer for display. This command always operates on whole frames regardless of the current time format. The step command is not affected by the state of seek exactly. This command always functions as if seek exactly is on. A step command without any flags always advances to the next frame. Audio is muted during the step. After a step command, the mode of the device is the same as defined for seek. This command is modified by the following items:

by frames	Specifies the number of frames to advance before showing another image. The default value is one which steps to the next image. Any images between the current image and the target image are not stored in the frame buffer. The value of frames might be negative, in which case the reverse flag cannot be used.

key	Steps are measured in key frames for faster operation.

reverse	Specifies the given number of frames should be stepped in reverse.


stop	Description

stop	Stops playing motion video or audio. If stop follows a play notify, the notification is aborted.


update	Description

update items	Repaints the current frame into the specified display context. When the application owns the window (it has used window handle hwnd), it must call update whenever the window must be painted; for example, when responding to a WM_PAINT message. The following items modify update:

at rect	Parameter has no effect by now. Specifies the clipping rectangle relative to the client rectangle.

hdc hdc	Specifies the handle of the display context to paint. If this parameter is not present then the device will render into the display context for the display window.

paint	Parameter has no effect by now. An application uses the paint flag with update when it receives a WM_PAINT message intended for a display DC. A frame buffer device will usually paint the key color. A device that does not have a frame buffer may ignore update when the paint flag is used if it is currently playing because the display will be repainted during the play operation.
If the hdc flag is used without paint, the device renders the current frame into the provided hdc. Device supporting this feature will render a full bitmap and not just update the key color.
If both hdc and paint are omitted, the contents of the frame buffer of the video overlay device are refreshed. This is useful to show new live video data after an unfreeze is sent to the device from a paused state.

on	Parameter has no effect by now. Key color shall be painted.

off	Parameter has no effect by now. Key color shall not be painted.


unfreeze	Description

unfreeze	Enables the update of the frame buffer from the presentation source.


window	Description

window items	Changes attributes of the window used to display images or motion video. If a window command is not used, the default window created when the device instance was opened is used. The default window has a style defined or defaulted on the open command and is initially invisible. It is possible to change windows at any time by using the window command. The default window is not destroyed until the device instance is closed; it is also possible to switch back to it.
If the current window is not visible and it is the default window, it becomes visible automatically whenever a play command is used and when the state of setvideo is on. It is also possible to use the window state command to request the device to issue a ShowWindow call for the current window. The default window continues to show and play video when it is iconic. The following items modify window:

handle hwnd	Specifies a window to be used with this device-driver instance. The hwnd parameter contains the ASCII numeric equivalent of the window handle returned by the CreateWindow function. Two device instances can use the same window handle, provided, that each instance updates the video and image pixels in the window as if the other instance did not exist. When video output is disabled with setvideo off, an update command will make the destination rectangle a solid color.

handle default	Specifies that the window associated with the device instance should be the default window created when it was opened. The default window has no owner unless a parent window is specified on open.

state ShowValue	Executes the ShowWindow function for the current window. The following constants are defined for ShowValue:

- hide

- minimized

- maximized

- restore

- show

- show maximized

- show minimized

- show min noactive

- show na

- show noactivate

- show normal

For a description of the behavior of these options, see the description for the  ShowWindow function. In addition, the constants no action (for show na) and minimized / maximized (for show minimized /maximized) are also recognized.

text caption	Specifies the text placed in the current title bar of the window. If this text contains embedded blanks, the entire caption must be enclosed in quotation marks. The default caption for the default window is the filename.


where	Description

where items	Returns the rectangular region that has been previously specified (or defaulted) for the put command. The return string consists of four space-separated integers that describe the X, Y coordinates of the upper left pixel, and the rectangle width and height. When the max flag is used, the command returns the maximum width and height of the region. The upper-left pixel of the maximum region is always 0, 0. The following items modify where:

destination	Returns a description of the rectangular region used to display video and images. This region is a portion of the client rectangle of the current window.

destination max	Returns the maximum size of the client window.

frame	Returns a description of the rectangular region of the frame buffer. Images from the video rectangle are scaled into this region.

frame max	Returns the maximum size of the frame buffer.

source	Returns a description of the rectangular region of the frame buffer used as the source of video images. The device uses this rectangle to crop the image before it is stretched to fit the destination rectangle on the display.

source max	Returns the maximum size of the frame buffer.

source min	Returns the minmal size of the frame buffer.

video	Returns a description of the rectangular region of the presentation source used to fill the frame rectangle in the frame buffer.

video max	Returns the maximum size of the input.

window	Returns the current size and position of the display window frame.

window max	Returns the size of the entire display.


How to contact ELSA
ELSA

ELSA Deutschland	Zentrale Entwicklung, Fertigung, Vertrieb, Support
		Adresse:	ELSA GmbH Sonnenweg 11 D-52070 Aachen Germany
		Telefon: - Vertrieb: - Hotline Datenkommunikation: - Hotline Computergrafik: Fax:	+49 (241) 9177-0 +49 (241) 9177-917 +49 (241) 9177-112 +49 (241) 9177-211 +49 (241) 9177-600
		Mailbox (analog): Mailbox (ISDN):	+49 (241) 9177-981 +49 (241) 9177-7800
ELSA USA	Subsidiary Company Sales, Support
		Address:	ELSA Inc. 2041 Mission College Blvd., Suite 165 Sanat Clara, CA 95054 USA
		Telephone: Fax:	+1 (408) 565-9669 +1 (408) 565-9650
		BBS:	+1 (408) 565-9630
ELSA Far East	Subsidiary Company
		Address:	ELSA Far East Office 5F No. 298 Sec. 5, Nanking East Road Taipei Taiwan, R.O.C.
		Telephone: Fax:	+886 (2) 768 5730 +886 (2) 766 0873
Electronic Mail
		CompuServe: MHS:	GO ELSA +49 (241) 9177-712