Mci Command

Purpose

Executes a Mci (Multimedia Control Interface) command.

Syntax

Mci cmd$

cmd$sexp

Description

Executes a Mci command (as Mci "close all"). An error (in the command string, or any other error) is reported with a message box. Error free execution set _EAX to 1. GFA-BASIC sets _EAX to -1 if the mmsystem could not be found.

Remarks

Multimedia is supported in Windows 3.x as a MMSYSTEM.DLL. It allows the handling of sound cards, audio CD-ROMs, videodisks, overlay video and animation etc. The lowest system of multimedia programming is by directly calling the device drivers for each device. Even the device independent programming interface of the multimedia system is quite complicated. There are different layers of multimedia support routines inside the mmsystem. The mmio system is a low level system for accessing multimedia files, it can only be used if the file structure is very well known, and is intended to be used in low level recording and manipulation systems and, as such, provides little help for standard presentation programs. Above this is the Mci system. This Multimedia Control Interface provides all the routines to access the devices in an orderly way. It's possible to use a message based system, with mciSendMessage, but this leads to hard to read code. The Mci provides a string based system, with mciExecute and mciSendString, which allows readable strings to be used for communication with the devices (as in "play tune", "seek to start"). This is the system chosen for GFA-BASIC. Multimedia is supported in GFA-BASIC for Windows version 4.22 upwards.

The command Mci and the function Mci$ handle all the Mci operations, supported by mciErr$ and mciID for error text and a device id used for the notification message.

The Mci command strings are all used as "cmd id param", optional followed by "notify" or "wait".

cmd is one of the command words as open, play, record ...

id is the ID of a device. That can be one of the following:

Dummy	Sequencer	MIDI or AdLib-Sound (build into virtually all sound cards)
	WaveAudio	The usual sampled sound (voice, digital sound effects ...)
	CDAudio	A Sound playing CD-ROM (attached to a sound card)
	Videodisc	A Video CD
	Overlay	An overlay of video images onto the computer screen
	Animation	The Movie, similar to overlay, but the "video" is computer generated as well, from a (compressed) file.
		There is plenty of expansion possible, like mmmovie for microsoft's animation. Most of the time, the device name is only used with the "capability" and "info" verbs to get information on the device without opening it. The "open" does support an "alias name". This let's you define a name to reference the device (and files) in a more abstract way. It allows to reference different files with the same, short identification.

param is an, often optional, parameter, or list of parameters. For open this is usually at least the "alias id".

notify optional following all commands is notify. If used, usually in a play, record or seek, a message (_Mess = $3b9) is sent to a window The Handle has to be given as the optional second parameter to Mci$()

wait optional following all commands is wait. If used, the Mci function waits for completion.

The functions returning some value, as "capability", "info", "status", "sysinfo" or "where" are always used in Mci$(). There is exactly one parameter (as "status id length"), it returns a string (as "12340", "12:59:30:72", "true"). Commands, as "set", usually accept several parameters in one call (as "set id samplespersec 11025 bitspersample 8 time format ms channels 1"). The commands may be used with the GFA-BASIC command Mci or the function Mci$().

MCI Commands

In the list the character "{", "}", "[", "]" and "|" have a special meaning.

A string in [] is optional (without the []).

A | marks alternatives (one of a group of strings).

A string group in {}, separated by | means one of the strings in the {} is required, but only one..

Examples:

[ insert | overwrite ]:-> "insert" or "overwrite", or "".

{ to end | to start }:-> "to start" or "to end"

[a] [b] [c]:-> "", "a", "b", "a b", "c b a" or "c" or ...

A % is a place holder for a number (123) or a time (depending on time format). A group of four % % % % is a rectangle (example: "100 80 400 120" := left 100, top=80, width=400, height=120). A $ is a string, a series of characters (TestTitel). Optionally it can be enclosed in quotation marks ("Test Title") to allow spaces in the string.

Time formats are used in position, to % or from%. There are several time formats defined, to be selected with "set id time format $".

	time	format	Position is
millisecond	2000	2 seconds
ms	2000	2 seconds
msf	23:40:23	minute : second : frame	0-99:0-59:0-74
tmsf	3:23:40:23	track : minute : second : frame	0-99:0-99:0-59:0-74)
hms	23:59:59	hour : minute : second
frames	2728	frame	2728
bytes	2700	byte	no 2700
samples	2700	sample	no 2700
track	3	track	3
song pointer	32	sixteenth notes	note 2
SMPTE x	02:12:0:08	hour : minute : second : frame (MIDI specific)

System Commands

break id { on % | off }

sysinfo id { installname | quantity | quantity open | name % | name % open }

Required Commands

capability id { can eject | can play | can record | can save | uses files }

capability id { compound device | device type | has audio | has video }

close { id | all }

info id product

open device[!file] [alias $id] [shareable] [type $device_type]

status id mode

Basic Commands

load dev [filename]

pause id

play id [from %] [to %]

record id [insert | overwrite] [from %] [to %]

resume id

save id [filename]

seek id { to % | to start | to end }

set id { audio all off | audio all on | audio left off | audio left on }

set id { audio right off | audio right on | door closed | door open }

set id { video off | video on | time format millisecond | time format ms }

status id { current track | length | length track % | ready | start position}

status id { number of tracks | position | position track % | time format }

stop id

Animation Commands

capability id { can reverse | can save | can stretch | fast play rate }

capability id { normal play rate | slow play rate | uses palette | windows }

info id { file | window text }

open id [nostatic] [ parent %] [style { % | child | overlapped | popup }]

play id [fast] [reverse] [scan] [slow] [speed %]

put id { destination | source } [at % % % %]

realize id { background | normal }

set id time format frames

status id { forward | media present | palette handle | speed | stretch }

status id { time format | window handle }

step id [by %] [reverse]

update id hdc % [at % % % %]

where { destination | source }

window id [fixed] [handle %] [handle default] [state hide] [state iconic] [state maximized]

window id [state minimize] [state minimized] [state no Purpose] [state no activate]

window id [state normal] [state show] [stretch] [text $]

Cdaudio Commands

set id time format { msf | tmsf }

Sequencer Commands (midi)

info id file

save id [filename]

set id [master MIDI] [master none] [master SMPTE] [offset %] [port %] [port mapper]

set id [port none] [slave file] [slave MIDI] [slave none] [slave SMPTE] [tempo %]

set id [time format song pointer] [time format SMPTE 24] [time format SMPTE 25]

set if [time format SMPTE 30] [time format SMPTE 30 drop]

status id { division type | master | offset | port | slave | tempo }

Videodisc Commands

capability id { CAV | CLV }

escape id $

seek id reverse

set id [time format hms] [time format track]

spin id { up | down }

status id { disc size | forward | media type | side }

set id [ by % | by % reverse | | reverse | by -%]

Overlay Commands

capability id windows

freeze id [at % % % %]

info id window text

load id [filename] [at % % % %]

put id [video [at % % % %]] [frame [at % % % %]]

put id [source [at % % % %]] [destination [at % % % %]]

save id filename [at % % % %]

unfreeze id [at % % % %]

where id { video | frame }

Waveaudio Commands

capability id { inputs | outputs }

cue id { input | output }

delete id [from %] [to %]

info id { input | output }

open ... [buffer %]

open new type waveaudio ...

set id [alignment %] [any input] [any output] [bitspersample %]

set id [bytespersec %] [channels %] [format tag $] [format tag pcm]

set id [input %] [output %] [time format bytes] [time format samples]

status id { alignment | bitspersample | bytespersec | channels | format tag }

status id { level | input | output | samplespersec }

Important: The Mci does not work for a synchronous wave device. That is the PC speaker driver from Microsoft. The speaker driver does only work with PlaySound.

Example

// play alarm01.wav three times

// first version checks for end of sound playing with the "status id mode" function.

// second version checks using the notify flag, and is about 30 times faster.

// If MCI can not find the above files, change the addresses to files on your local machine.

Auto i%, q%

OpenW # 1

Mci "open c:\windows\media\alarm01.wav alias bong"

For i% = 1 To 3

Mci "play bong from 1"

q% = 0

PeekEvent

q%++

Loop Until Mci$("status bong mode") != "playing"

Print q%

Next i%

Mci "close bong"