# MCI Library v1.0

Summary

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.

### 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/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.

#### 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.

### Links

MCI Reference Guide

- http://msdn.microsoft.com/en-us/library/ms709461(VS.85).aspx

### Credit

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

- http://www.autohotkey.com/forum/viewtopic.php?t=20666
- http://www.autohotkey.com/forum/viewtopic.php?t=22662

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

- http://www.autohotkey.com/forum/viewtopic.php?p=132331#132331

mciGetErrorString call from PhiLho

- http://www.autohotkey.com/forum/viewtopic.php?p=116011#116011

### Functions

### MCI_Close

> MCI_Close( | p_lpszDeviceID | )

#### Description

Closes the device and any associated resources.

#### Parameters

p_lpszDeviceID | Device 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_lpszDeviceID | Device 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_lpszDeviceID | Device 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_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]

#### 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_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.

#### 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_lpszDeviceID | Device name or alias.
p_Track | Track number. [Optional] The default is 0 (no track number).

#### Returns

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

> MCI_MediaIsPresent( | p_lpszDeviceID | )

#### Description

Checks to see if media is present in the device.

#### Parameters

p_lpszDeviceID | Device 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

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.

#### 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_lpszDeviceID | Device 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_lpszDeviceID | Device 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_lpszDeviceID | Device name or alias.
p_Flags | Flags 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_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.

#### 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_lpszDeviceID | Device name or alias.
p_Track | Track 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_lpszDeviceID | Device name or alias.
p_Flags | Flags 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_lpszDeviceID | Device 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_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.

#### 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_lpszDeviceID | Device name or alias.
p_Position | Position 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_lpszDeviceID | Device name or alias.
p_Factor | Bass 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_lpszDeviceID | Device name or alias.
p_Factor | Treble 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_lpszDeviceID | Device name or alias.
p_Factor | Volume 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_lpszDeviceID | Device 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_lpszDeviceID | Device 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_lpszDeviceID | Device name or alias.
p_Track | Track 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_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.

#### 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, Sec | Position 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_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).

#### 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