MCI Library v1.1

Summary
MCI Library v1.1
OverviewThis library gives the AutoHotkey developer access to the the Media Control Interface (MCI) which provides standard commands for playing/controlling multimedia devices.
Notes
LinksMCI Reference Guide
CreditThe MCI library is an offshoot of the Sound_* and Media_* libraries provided by Fincs.
Functions
MCI_CloseCloses the device and any associated resources.
MCI_CurrentTrackIdentifies the current track.
MCI_DeviceTypeIdentifies the device type name.
MCI_OpenOpens an MCI device and loads the specified file.
MCI_OpenCDAudioOpens a CDAudio device.
MCI_LengthGets the total length of the media in the current time format.
MCI_MediaIsPresentChecks to see if media is present in the device.
MCI_Notify(Internal function.
MCI_NumberOfTracksIdentifies the number of tracks on the media.
MCI_PausePauses playback or recording.
MCI_PlayStarts playing a device.
MCI_PositionIdentifies the current playback or recording position.
MCI_RecordStarts recording.
MCI_ResumeResumes playback or recording after the device has been paused.
MCI_SaveSaves an MCI file.
MCI_SeekMove to a specified position.
MCI_SetBassSets the audio low frequency level.
MCI_SetTrebleSets the audio high-frequency level.
MCI_SetVolumeSets the average audio volume for both audio channels.
MCI_StatusIdentifies the current mode of the device.
MCI_StopStops playback or recording.
MCI_TrackIsAudioDetermines if the specified track is an audio track.
MCI_ToHHMMSSConverts the specified number of milliseconds to hh:mm:ss format.
MCI_ToMillisecondsConverts the specified hour, minute and second into a valid milliseconds timestamp.
MCI_SendStringThis is the primary function that controls MCI operations.

Overview

This library gives the AutoHotkey developer access to the the Media Control Interface (MCI) which provides standard commands for playing/controlling multimedia devices.

Notes

Devices Referenced Within The Documentation

Driver      Type            Description
------      ----            -----------
MCIAVI      avivideo
MCICDA      cdaudio         CD audio
            dat             Digital-audio tape player
            digitalvideo    Digital video in a window (not GDI-based)
            MPEGVideo       General-purpose media player
            other           Undefined MCI device
            overlay         Overlay device (analog video in a window)
            scanner         Image scanner
MCISEQ      sequencer       MIDI sequencer
            vcr             Video-cassette recorder or player
MCIPIONR    videodisc       Videodisc (Pioneer LaserDisc)
MCIWAVE     waveaudio       Audio device that plays digitized waveform files

MCI Installation

To see a list of MCI devices that have been registered for the computer, go to the following registry locations...

Windows NT4/2000/XP/2003/Vista/7/etc.:

  16-bit:
    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\MCI

  32-bit:
    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\MCI32


Windows 95/98/ME:

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaResources\MCI

To see a list of registered file extensions and the MCI device that has been assigned to each extension, go the following locations...

For Windows NT4/2000/XP/2003/Vista/7/etc., this information is stored in
the following registry location:

    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\MCI Extensions

For Windows 95/98/ME, this information is stored in the %windir%\win.ini
file in the "MCI Extensions" section.

Performance

AutoHotkey automatically loads winmm.dll into memory.  There is no need or advantage to preload this library in order to use the MCI library.

Debugging

OutputDebug statements in the core of some of the functions that only execute on condition are permanent and are provided to help the developer find and eliminate errors.

Credit

The MCI library is an offshoot of the Sound_* and Media_* libraries provided by Fincs.

Credit and thanks to Fincs for creating and enhancing these libraries which are a conversion from the AutoIt “Sound.au3” standard library and to RazerM for providing the original “Sound.au3” library.

Notify idea and code from Sean

mciGetErrorString call from PhiLho

Functions

MCI_Close

MCI_Close(p_lpszDeviceID)

Description

Closes the device and any associated resources.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Remarks

For most MCI devices, closing a device usually stops playback but not always.  If unsure of the device, consider stopping the device before closing it.

MCI_CurrentTrack

MCI_CurrentTrack(p_lpszDeviceID)

Description

Identifies the current track.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

The current track.  Note: The MCISEQ sequencer returns 1.

MCI_DeviceType

MCI_DeviceType(p_lpszDeviceID)

Description

Identifies the device type name.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

A device type name, which can be one of the following...

cdaudio
dat
digitalvideo
other
overlay
scanner
sequencer
vcr
videodisc
waveaudio

MCI_Open

MCI_Open(p_MediaFile,  
p_Alias = "",
p_Flags = "")

Description

Opens an MCI device and loads the specified file.

Parameters

p_MediaFileA multimedia file.
p_AliasAlias.  A name such as media1.  [Optional] If blank (the default), an alias will automatically be generated.
p_FlagsFlags that determine how the device is opened.  [Optional]

Flag Notes

Some commonly used flags include...

type {device_type}
sharable

If more than one flag is used, separate each flag/value with a space.  For example:

type MPEGVideo sharable

Additional notes...

  • The “wait” flag is automatically added to the end of the command string.  This flag directs the device to complete the “open” request before returning.
  • Use the “shareable” flag with care.  Per msdn, the “shareable” flag “initializes the device or file as shareable.  Subsequent attempts to open the device or file fail unless you specify “shareable” in both the original and subsequent open commands.  MCI returns an invalid device error if the device is already open and not shareable.  The MCISEQ sequencer and MCIWAVE devices do not support shared files.”
  • By default, the MCI device that is opened is determined by the file’s extension.  The “type” flag can be used to 1) override the default device that is registered for the file extension or to 2) open a media file with a file extension that is not registered as a MCI file extension.  See the Notes section for more information.
  • For a complete list of flags and descriptions for the “open” command string, see the “MCI Reference Guide” in the Links section.

Returns

The multimedia handle (alias) or 0 (FALSE) to indicate failure.  Failure will occur with any of the following conditions:

  • The media file does not exist.
  • The media file’s extension is not a regisitered MCI extension.  Note: This test is only performed if the “type” flag is not specified.
  • Non-zero return code from the MCI_SendString function.

Remarks

  • Use the MCI_OpenCDAudio function to open a CDAudio device.
  • After the device has been successfully opened, the time format is set to milliseconds which it will remain in effect until it is manually set to another value or until the device is closed.

MCI_OpenCDAudio

MCI_OpenCDAudio(p_Drive = "",
p_Alias = "",
p_CheckForMedia = True)

Description

Opens a CDAudio device.

Parameters

p_DriveCDROM drive letter.  [Optional] If blank (the default), the first CDROM drive found is used.
p_AliasAlias.  A name such as media1.  [Optional] If blank (the default), an alias will automatically be generated.
p_CheckForMediaCheck for media.  [Optional] The default is TRUE.

Returns

The multimedia handle (alias) or 0 to indicate failure.  Failure will occur with any of the following conditions:

  • The computer does not have a CDROM drive.
  • The specified drive is not CDROM drive.
  • Non-zero return code from the MCI_SendString function.

If p_CheckForMedia is TRUE (the default), failure will also occur with any of the following conditions:

  • No media was found in the device.
  • Media does not contain audio tracks.

Remarks

After the device has been successfully opened, the time format is set to milliseconds which will remain in effect until it is manually set to another value or until the device is closed.

MCI_Length

MCI_Length(p_lpszDeviceID,  
p_Track = )

Description

Gets the total length of the media in the current time format.

Parameters

p_lpszDeviceIDDevice name or alias.
p_TrackTrack number.  [Optional] The default is 0 (no track number).

Returns

If a track number is not specified (the default), the length of the entire entire media is returned.  If a track number is specified, only the the length of the specified track is returned.

MCI_MediaIsPresent

MCI_MediaIsPresent(p_lpszDeviceID)

Description

Checks to see if media is present in the device.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

TRUE if the media is inserted in the device, otherwise FALSE. msdn: Sequencer, video-overlay, digital-video, and waveform-audio devices (always) return TRUE.

MCI_Notify

MCI_Notify(wParam,
lParam,
msg,
hWnd)

Description

(Internal function.  Do not call directly)

This function has 2 responsibilties...

1) If called by the MCI_Play function, wParam contains the name of the developer-defined function.  This value is assigned to the s_Callback static variable for future use.

2) When called as a result of MM_MCINOTIFY message, this function will call the developer-defined function (name stored in the s_Callback static variable) sending the MM_MCINOTIFY status flag as the first parameter.

Parameters

wParamFunction name or a MM_MCINOTIFY flag.

MM_MCINOTIFY flag values are as follows...

MCI_NOTIFY_SUCCESSFUL:=0x1
    The conditions initiating the callback function have been met.

MCI_NOTIFY_SUPERSEDED:=0x2
    The device received another command with the "notify" flag set and
    the current conditions for initiating the callback function have
    been superseded.

MCI_NOTIFY_ABORTED:=0x4
    The device received a command that prevented the current conditions
    for initiating the callback function from being met. If a new
    command interrupts the current command and  it also requests
    notification, the device sends this message only and not
    MCI_NOTIFY_SUPERSEDED.

MCI_NOTIFY_FAILURE:=0x8
    A device error occurred while the device was executing the command.
lParamlDevID.  This is the identifier of the device initiating the callback function.  This information is only useful if operating more than one MCI device at a time.

Returns

Per msdn, returns 0 to indicate a successful call.

Remarks

This function does not complete until the call to the developer-defined function has completed.  If a MM_MCINOTIFY message is issued while this function is running, the message will be treated as unmonitored.

MCI_NumberOfTracks

MCI_NumberOfTracks(p_lpszDeviceID)

Description

Identifies the number of tracks on the media.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

The number of tracks on the media.

Remarks

msdn: The MCISEQ and MCIWAVE devices return 1, as do most VCR devices.  The MCIPIONR device does not support this flag.

MCI_Pause

MCI_Pause(p_lpszDeviceID)

Description

Pauses playback or recording.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Remarks

msdn: With the MCICDA, MCISEQ, and MCIPIONR drivers, the pause command works the same as the stop command.

Observation: For MCISEQ devices, pause works OK for me.

MCI_Play

MCI_Play(p_lpszDeviceID,  
p_Flags = "",
p_Callback = "",
p_hwndCallback = 0)

Description

Starts playing a device.

Parameters

p_lpszDeviceIDDevice name or alias.
p_FlagsFlags that determine how the device is played.  [Optional] If blank, no flags are used.

Flag Notes

Some commonly used flags include...

from {position}
to {position}

If more than one flag is used, separate each flag/value with a space.  For example:

from 10144 to 95455

Additional notes...

  • With the exception of very short sound files (<300 ms), the “wait” flag is not recommended.  The entire application will be non-responsive while the media is being played.
  • Do not add the “notify” flag unless you plan to have your script trap the MM_MCINOTIFY message outside of this function.  The “notify” flag is automatically added if the p_Callback parameter contains a value.
  • For a complete list of flags and descriptions for the “play” command string, see the “MCI Reference Guide” in the Links section.
p_CallbackFunction name that is called when the MM_MCINOTIFY message is sent.  [Optional] If defined, the “notify” flag is automatically added.

Important: The syntax of this parameter and the associated function is critical.  If not defined correctly, the script may crash.

The function must have at least one parameter.  For example...

MyNotifyFunction(NotifyFlag)

Additional parameters are allowed but they must be optional (contain a default value).  For example:

MyNotifyFunction(NotifyFlag,FirstCall=False,Parm3="ABC")

When a notify message is sent, the approriate MM_MCINOTIFY flag is sent to the developer-defined function as the first parameter.  See the MCI_Notify function for a description and a list of MM_MCINOTIFY flag values.

p_hWndCallbackHandle to a callback window if the p_Callback parameter contains a value and/or if the “notify” flag is defined.  [Optional] If undefined but needed, the handle to default Autohotkey window is used.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

MCI_Position

MCI_Position(p_lpszDeviceID,  
p_Track = )

Description

Identifies the current playback or recording position.

Parameters

p_lpszDeviceIDDevice name or alias.
p_TrackTrack number.  [Optional] The default is 0 (no track number).

Returns

The current playback or recording position in the current time format.  If the p_Track parameter contains a non-zero value, the start position of the track relative to entire media is returned.

MCI_Record

MCI_Record(p_lpszDeviceID,  
p_Flags = "")

Description

Starts recording.

Parameters

p_lpszDeviceIDDevice name or alias.
p_FlagsFlags that determine how the device operates for recording.  [Optional] If blank, no flags are used.

Flag Notes

Some commonly used flags include...

from {position}
to {position}
insert
overwrite

If more than one flag is used, separate each flag/value with a space.  For example:

overwrite from 18122 to 26427

Additional notes...

  • The “wait” flag is not recommended.  The entire application will be non-responsive until recording is stopped with a Stop or Pause command.
  • For a complete list of flags and descriptions for the “record” command string, see the “MCI Reference Guide” in the Links section.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Remarks

msdn: Recording stops when a Stop or Pause command is issued.  For the MCIWAVE driver, all data recorded after a file is opened is discarded if the file is closed without saving it.

Credit

Original function and examples by heresy.

MCI_Resume

MCI_Resume(p_lpszDeviceID)

Description

Resumes playback or recording after the device has been paused.  See the MCI_Pause function for more information.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Remarks

msdn: Digital-video, VCR, and waveform-audio devices recognize this command.  Although CD audio, MIDI sequencer, and videodisc devices also recognize this command, the MCICDA, MCISEQ, and MCIPIONR device drivers do not support it.

Programming Notes

The MCI_Play function can sometimes be an alternative to this function.  Many devices will begin to play where they were last paused.  If the device does not begin playback correctly, try specifying an appropriate “From” and “To” value (if needed) in the p_Flags parameter.

MCI_Save

MCI_Save(p_lpszDeviceID,
p_FileName)

Description

Saves an MCI file.

Parameters

p_lpszDeviceIDDevice name or alias.
p_FileNameFile name to store a MCI file.  If the file does not exist, a new file will be created.  If the file exists, it will be overwritten.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Remarks

This command can overwrite existing files.  Use with care.

Credit

Original function and examples by heresy.

MCI_Seek

Description

Move to a specified position.

Parameters

p_lpszDeviceIDDevice name or alias.
p_PositionPosition to stop the seek.  Value must be “start”, “end”, or an integer.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

MCI_SetBass

MCI_SetBass(p_lpszDeviceID,
p_Factor)

Description

Sets the audio low frequency level.

Parameters

p_lpszDeviceIDDevice name or alias.
p_FactorBass factor.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Observations

  • Factor range appears to be from 0 to ?????.
  • Most MCI devices do not support this command.

MCI_SetTreble

MCI_SetTreble(p_lpszDeviceID,
p_Factor)

Description

Sets the audio high-frequency level.

Parameters

p_lpszDeviceIDDevice name or alias.
p_FactorTreble factor.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Observations

  • Factor range appears to be from 0 to ?????.
  • Most MCI devices do not support this command.

MCI_SetVolume

MCI_SetVolume(p_lpszDeviceID,
p_Factor)

Description

Sets the average audio volume for both audio channels.  If the left and right volumes have been set to different values, then the ratio of left-to-right volume is approximately unchanged.

Parameters

p_lpszDeviceIDDevice name or alias.
p_FactorVolume factor.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Observations

  • Factor range appears to be from 0 to 1000.
  • Most MCI devices do not support this command.

MCI_Status

MCI_Status(p_lpszDeviceID)

Description

Identifies the current mode of the device.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

The current mode of the device.

msdn: All devices can return the “not ready”, “paused”, “playing”, and “stopped” values.  Some devices can return the additional “open”, “parked”, “recording”, and “seeking” values.

MCI_Stop

MCI_Stop(p_lpszDeviceID)

Description

Stops playback or recording.

Parameters

p_lpszDeviceIDDevice name or alias.

Returns

The return code from the MCI_SendString function which is 0 if the command completed successfully.

Remarks

  • After close, a “seek to start” is not done because 1) it slows down the stop request and 2) it may be unwanted.  If you need to set the media position back to the beginning after a stop, call the MCI_Seek function and set the p_Position parameter to 0.
  • For some CD audio devices, the stop command stops playback and resets the current track position to zero.

MCI_TrackIsAudio

MCI_TrackIsAudio(p_lpszDeviceID,  
p_Track = 1)

Description

Determines if the specified track is an audio track.

Parameters

p_lpszDeviceIDDevice name or alias.
p_TrackTrack number.  [Optional] The default is 1.

Returns

TRUE if the specified track is an audio track, otherwise FALSE.

Remarks

This command will only work on a device that supports multiple tracks.

MCI_ToHHMMSS

MCI_ToHHMMSS(p_ms,  
p_MinimumSize = 4)

Description

Converts the specified number of milliseconds to hh:mm:ss format.

Parameters

p_msNumber of milliseconds.
p_MinimumSizeMinimum size.  [Optional] The default is 4.  This is the minimum size in characters (not significant digits) that is returned.  Unless you want a “:” character to show as the leading character, don’t set this value to 3 or 6.

Returns

The amount of time in hh:mm:ss format with leading zero and “:” characters suppressed unless the length is less than p_MinimumSize.  Note: If the number of hours is greater than 99, the size of hour (“hh”) will increase as needed.

Usage Notes

To use this function to create separate variables for the number of hours, minutes, and seconds, set the p_MinimumSize parameter to 8 and use simple SubStr commands to create these variables.  For example:

x:=MCI_ToHHMMSS(NumberOfMilliseconds,8)
HH:=SubStr(x,1,2)
MM:=SubStr(x,4,2)
SS:=SubStr(x,6,2)

To remove leading zeros from these variables, simply add 0 to the extracted value.  For example:

MM:=SubStr(x,4,2)+0

Credit

This function is a customized version of an example that was extracted from the AutoHotkey documenation.

MCI_ToMilliseconds

MCI_ToMilliseconds(Hour,
Min,
Sec)

Description

Converts the specified hour, minute and second into a valid milliseconds timestamp.

Parameters

Hour, Min, SecPosition to convert to milliseconds

Returns

The specified position converted to milliseconds.

MCI_SendString

MCI_SendString( p_lpszCommand,  
ByRef r_lpszReturnString = "",
 p_hwndCallback = 0)

Description

This is the primary function that controls MCI operations.  With the exception of formatting functions, all of the functions in this library call this function.

Parameters

p_lpszCommandMCI command string.
r_lpszReturnStringVariable name that receives return information.  [Optional]
p_hwndCallbackHandle to a callback window if the “notify” flag was specified in the command string.  [Optional] The default is 0 (No callback window).

Returns

Two values are returned.

1) The function returns 0 if successful or an error number otherwise.

2) If the MCI command string was a request for information, the variable named in the r_lpszReturnString parameter will contain the requested information.

Debugging

If a non-zero value is returned from the call to the mciSendString API function, a call to the mciGetErrorString API function is made to convert the error number into a developer-friendly error message.  All of this information is sent to the debugger in an easy-to-read format.

MCI_Close(p_lpszDeviceID)
Closes the device and any associated resources.
MCI_CurrentTrack(p_lpszDeviceID)
Identifies the current track.
MCI_DeviceType(p_lpszDeviceID)
Identifies the device type name.
MCI_Open(p_MediaFile,  
p_Alias = "",
p_Flags = "")
Opens an MCI device and loads the specified file.
MCI_OpenCDAudio(p_Drive = "",
p_Alias = "",
p_CheckForMedia = True)
Opens a CDAudio device.
MCI_Length(p_lpszDeviceID,  
p_Track = )
Gets the total length of the media in the current time format.
MCI_MediaIsPresent(p_lpszDeviceID)
Checks to see if media is present in the device.
MCI_Notify(wParam,
lParam,
msg,
hWnd)
(Internal function.
MCI_NumberOfTracks(p_lpszDeviceID)
Identifies the number of tracks on the media.
MCI_Pause(p_lpszDeviceID)
Pauses playback or recording.
MCI_Play(p_lpszDeviceID,  
p_Flags = "",
p_Callback = "",
p_hwndCallback = 0)
Starts playing a device.
MCI_Position(p_lpszDeviceID,  
p_Track = )
Identifies the current playback or recording position.
MCI_Record(p_lpszDeviceID,  
p_Flags = "")
Starts recording.
MCI_Resume(p_lpszDeviceID)
Resumes playback or recording after the device has been paused.
MCI_Save(p_lpszDeviceID,
p_FileName)
Saves an MCI file.
MCI_SetBass(p_lpszDeviceID,
p_Factor)
Sets the audio low frequency level.
MCI_SetTreble(p_lpszDeviceID,
p_Factor)
Sets the audio high-frequency level.
MCI_SetVolume(p_lpszDeviceID,
p_Factor)
Sets the average audio volume for both audio channels.
MCI_Status(p_lpszDeviceID)
Identifies the current mode of the device.
MCI_Stop(p_lpszDeviceID)
Stops playback or recording.
MCI_TrackIsAudio(p_lpszDeviceID,  
p_Track = 1)
Determines if the specified track is an audio track.
MCI_ToHHMMSS(p_ms,  
p_MinimumSize = 4)
Converts the specified number of milliseconds to hh:mm:ss format.
MCI_ToMilliseconds(Hour,
Min,
Sec)
Converts the specified hour, minute and second into a valid milliseconds timestamp.
MCI_SendString( p_lpszCommand,  
ByRef r_lpszReturnString = "",
 p_hwndCallback = 0)
This is the primary function that controls MCI operations.
MCI Reference Guide
Move to a specified position.
Close