MCI Library v1.0 | |
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 | |
Links | MCI Reference Guide |
Credit | The MCI library is an offshoot of the Sound_* and Media_* libraries provided by Fincs. |
Functions | |
MCI_Close | Closes the device and any associated resources. |
MCI_CurrentTrack | Identifies the current track. |
MCI_DeviceType | Identifies the device type name. |
MCI_Open | Opens an MCI device and loads the specified file. |
MCI_OpenCDAudio | Opens a CDAudio device. |
MCI_Length | Gets the total length of the media in the current time format. |
MCI_MediaIsPresent | Checks to see if media is present in the device. |
MCI_Notify | (Internal function. |
MCI_NumberOfTracks | Identifies the number of tracks on the media. |
MCI_Pause | Pauses playback or recording. |
MCI_Play | Starts playing a device. |
MCI_Position | Identifies the current playback or recording position. |
MCI_Record | Starts recording. |
MCI_Resume | Resumes playback or recording after the device has been paused. |
MCI_Save | Saves an MCI file. |
MCI_Seek | Move to a specified position. |
MCI_SetBass | Sets the audio low frequency level. |
MCI_SetTreble | Sets the audio high-frequency level. |
MCI_SetVolume | Sets the average audio volume for both audio channels. |
MCI_Status | Identifies the current mode of the device. |
MCI_Stop | Stops playback or recording. |
MCI_TrackIsAudio | Determines if the specified track is an audio track. |
MCI_ToHHMMSS | Converts the specified number of milliseconds to hh:mm:ss format. |
MCI_ToMilliseconds | Converts the specified hour, minute and second into a valid milliseconds timestamp. |
MCI_SendString | This is the primary function that controls MCI operations. |
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
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/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/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.
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.
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
MCI_Close( p_lpszDeviceID )
Closes the device and any associated resources.
p_lpszDeviceID | Device name or alias. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
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_Open( p_MediaFile, p_Alias = "", p_Flags = "" )
Opens an MCI device and loads the specified file.
p_MediaFile | A multimedia file. |
p_Alias | Alias. A name such as media1. [Optional] If blank (the default), an alias will automatically be generated. |
p_Flags | Flags that determine how the device is opened. [Optional] |
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 multimedia handle (alias) or 0 (FALSE) to indicate failure. Failure will occur with any of the following conditions:
MCI_OpenCDAudio( p_Drive = "", p_Alias = "", p_CheckForMedia = True )
Opens a CDAudio device.
p_Drive | CDROM drive letter. [Optional] If blank (the default), the first CDROM drive found is used. |
p_Alias | Alias. A name such as media1. [Optional] If blank (the default), an alias will automatically be generated. |
p_CheckForMedia | Check for media. [Optional] The default is TRUE. |
The multimedia handle (alias) or 0 to indicate failure. Failure will occur with any of the following conditions:
If p_CheckForMedia is TRUE (the default), failure will also occur with any of the following conditions:
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( p_lpszDeviceID, p_Track = )
Gets the total length of the media in the current time format.
p_lpszDeviceID | Device name or alias. |
p_Track | Track number. [Optional] The default is 0 (no track number). |
If a track number is not specified (the default), the length of the entire media is returned. If a track number is specified, only the the length of the specified track is returned.
MCI_MediaIsPresent( p_lpszDeviceID )
Checks to see if media is present in the device.
p_lpszDeviceID | Device name or alias. |
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( wParam, lParam, msg, hWnd )
(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.
wParam | Function 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.
lParam | lDevID. 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. |
Per msdn, returns 0 to indicate a successful call.
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( p_lpszDeviceID )
Identifies the number of tracks on the media.
p_lpszDeviceID | Device name or alias. |
The number of tracks on the media.
msdn: The MCISEQ and MCIWAVE devices return 1, as do most VCR devices. The MCIPIONR device does not support this flag.
MCI_Pause( p_lpszDeviceID )
Pauses playback or recording.
p_lpszDeviceID | Device name or alias. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
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( p_lpszDeviceID, p_Flags = "", p_Callback = "", p_hwndCallback = 0 )
Starts playing a device.
p_lpszDeviceID | Device name or alias. |
p_Flags | Flags that determine how the device is played. [Optional] If blank, no flags are used. |
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...
p_Callback | Function 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_hWndCallback | Handle 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. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
MCI_Position( p_lpszDeviceID, p_Track = )
Identifies the current playback or recording position.
p_lpszDeviceID | Device name or alias. |
p_Track | Track number. [Optional] The default is 0 (no track number). |
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( p_lpszDeviceID, p_Flags = "" )
Starts recording.
p_lpszDeviceID | Device name or alias. |
p_Flags | Flags that determine how the device operates for recording. [Optional] If blank, no flags are used. |
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 return code from the MCI_SendString function which is 0 if the command completed successfully.
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.
Original function and examples by heresy.
MCI_Resume( p_lpszDeviceID )
Resumes playback or recording after the device has been paused. See the MCI_Pause function for more information.
p_lpszDeviceID | Device name or alias. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
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.
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( p_lpszDeviceID, p_FileName )
Saves an MCI file.
p_lpszDeviceID | Device name or alias. |
p_FileName | File 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. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
This command can overwrite existing files. Use with care.
Original function and examples by heresy.
Move to a specified position.
p_lpszDeviceID | Device name or alias. |
p_Position | Position to stop the seek. Value must be “start”, “end”, or an integer. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
MCI_SetBass( p_lpszDeviceID, p_Factor )
Sets the audio low frequency level.
p_lpszDeviceID | Device name or alias. |
p_Factor | Bass factor. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
MCI_SetTreble( p_lpszDeviceID, p_Factor )
Sets the audio high-frequency level.
p_lpszDeviceID | Device name or alias. |
p_Factor | Treble factor. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
MCI_SetVolume( p_lpszDeviceID, p_Factor )
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.
p_lpszDeviceID | Device name or alias. |
p_Factor | Volume factor. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
MCI_Status( p_lpszDeviceID )
Identifies the current mode of the device.
p_lpszDeviceID | Device name or alias. |
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( p_lpszDeviceID )
Stops playback or recording.
p_lpszDeviceID | Device name or alias. |
The return code from the MCI_SendString function which is 0 if the command completed successfully.
MCI_TrackIsAudio( p_lpszDeviceID, p_Track = 1 )
Determines if the specified track is an audio track.
p_lpszDeviceID | Device name or alias. |
p_Track | Track number. [Optional] The default is 1. |
TRUE if the specified track is an audio track, otherwise FALSE.
This command will only work on a device that supports multiple tracks.
MCI_ToHHMMSS( p_ms, p_MinimumSize = 4 )
Converts the specified number of milliseconds to hh:mm:ss format.
p_ms | Number of milliseconds. |
p_MinimumSize | Minimum 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. |
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.
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
This function is a customized version of an example that was extracted from the AutoHotkey documenation.
MCI_SendString( p_lpszCommand, ByRef r_lpszReturnString = "", p_hwndCallback = 0 )
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.
p_lpszCommand | MCI command string. |
r_lpszReturnString | Variable name that receives return information. [Optional] |
p_hwndCallback | Handle to a callback window if the “notify” flag was specified in the command string. [Optional] The default is 0 (No callback window). |
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.
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.
Closes the device and any associated resources.
MCI_Close( p_lpszDeviceID )
Identifies the current track.
MCI_CurrentTrack( p_lpszDeviceID )
Identifies the device type name.
MCI_DeviceType( p_lpszDeviceID )
Opens an MCI device and loads the specified file.
MCI_Open( p_MediaFile, p_Alias = "", p_Flags = "" )
Opens a CDAudio device.
MCI_OpenCDAudio( p_Drive = "", p_Alias = "", p_CheckForMedia = True )
Gets the total length of the media in the current time format.
MCI_Length( p_lpszDeviceID, p_Track = )
Checks to see if media is present in the device.
MCI_MediaIsPresent( p_lpszDeviceID )
(Internal function.
MCI_Notify( wParam, lParam, msg, hWnd )
Identifies the number of tracks on the media.
MCI_NumberOfTracks( p_lpszDeviceID )
Pauses playback or recording.
MCI_Pause( p_lpszDeviceID )
Starts playing a device.
MCI_Play( p_lpszDeviceID, p_Flags = "", p_Callback = "", p_hwndCallback = 0 )
Identifies the current playback or recording position.
MCI_Position( p_lpszDeviceID, p_Track = )
Starts recording.
MCI_Record( p_lpszDeviceID, p_Flags = "" )
Resumes playback or recording after the device has been paused.
MCI_Resume( p_lpszDeviceID )
Saves an MCI file.
MCI_Save( p_lpszDeviceID, p_FileName )
Sets the audio low frequency level.
MCI_SetBass( p_lpszDeviceID, p_Factor )
Sets the audio high-frequency level.
MCI_SetTreble( p_lpszDeviceID, p_Factor )
Sets the average audio volume for both audio channels.
MCI_SetVolume( p_lpszDeviceID, p_Factor )
Identifies the current mode of the device.
MCI_Status( p_lpszDeviceID )
Stops playback or recording.
MCI_Stop( p_lpszDeviceID )
Determines if the specified track is an audio track.
MCI_TrackIsAudio( p_lpszDeviceID, p_Track = 1 )
Converts the specified number of milliseconds to hh:mm:ss format.
MCI_ToHHMMSS( p_ms, p_MinimumSize = 4 )
Converts the specified hour, minute and second into a valid milliseconds timestamp.
MCI_ToMilliseconds( Hour, Min, Sec )
This is the primary function that controls MCI operations.
MCI_SendString( p_lpszCommand, ByRef r_lpszReturnString = "", p_hwndCallback = 0 )