play MCI Command String

"play lpszDeviceID, lpszPlayFlags, lpszFlags"

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

The play MCI command string begins playing a MCI device. By default, playback begins at the current position in the device. Of course, this default can be overridden by options specified in lpszPlayFlags.

The following MCI device types recognize the play command string: cdaudio, digitalvideo, sequencer, vcr, videodisk, waveaudio.

Return Value

The play command string does not return a value.

Visual Basic-Specific Issues

None.

Parameters

lpszDeviceID

The device identifer string of the MCI device or file to play. This may be an alias to the device or file.

lpszPlayFlags

Zero or more of the following options for how to play the MCI device:

"at time" (vcr): Specifies when the device should begin playback, especially if it has previously been cued.
"fast" (videodisc): Play the device at a speed faster than normal.
"from position" (all): Specifies the position at which to begin playback. If nothing is specified for position, playback begins at the current position.
"fullscreen" (digitalvideo): Use a full-screen display. This option only works when playing a compressed file.
"repeat" (digitalvideo): Restart playback once the end has been reached.
"reverse" (digitalvideo, vcr, videodisc): Play the device backwards. When using this option, the "to" option cannot be used.
"scan" (vcr, videodisc): Play as fast as possible without disabling video display, although audio may be disabled. This is essentially fast-forwarding the device.
"slow" (videodisc): Play the device at a speed slower than normal.
"speed integer" (videodisc): Play the videodisc at integer frames per second.
"to position" (all): Specifies the position at which to end playback. If nothing is specified for position, playback ends until the end of the device is reached.
"window" (digitalvideo): Use the window associated with the device's instance to display the video.

lpszFlags

Zero or more of the following options:

"notify": When the command finishes, post the MM_MCINOTIFY message to the window specified in the call to mciSendString.
"test" (digitalvideo and vcr only): Test to see if the device supports the play command. Nothing is played, and the call to mciSendString only returns successfully if the device supports the play command.
"wait": Do not have mciSendString return until the command finishes.

Example

To run this code, place two command buttons on a form window. Name one "cmdPlay" and set its Caption to "&Play MIDI File". Likewise, name the other one "cmdStop" and set its Caption to "&Stop MIDI File".

' This code is licensed according to the terms and conditions listed here.

' Declarations and such needed for the example:
' (Copy them to the (declarations) section of a module.)
Public Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal _
	lpszCommand As String, ByVal lpszReturnString As String, ByVal cchReturnLength _
	As Long, ByVal hwndCallback As Long) As Long
Public Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" (ByVal _
	fdwError As Long, ByVal lpszErrorText As String, ByVal cchErrorText As Long) As Long

' Use the MCI to play or stop playback of a MIDI file.  The file C:\Music\canyon.mid
' is opened when the form opens.  The Play and Stop buttons behave as you'd expect.  The
' only potential surprise is that the current position is not reset when playback stops; it
' behaves just as pausing playback would.  The file closes when the form unloads.

' If anything goes wrong in the example, display a message box with
' the MCI error message text.

Private Sub Form_Load()
	' Open the file "C:\Music\canyon.mid" for later use in the example.
	' Give it an alias of "canyon" so we don't need to refer to the filename again.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("open C:\Music\canyon.mid alias canyon", "", 0, 0)
	If errcode <> 0 Then DisplayError errcode
End Sub

Private Sub cmdPlay_Click()
	' Begin playback of the MIDI file when this button is pressed.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("play canyon", "", 0, 0)
	If errcode <> 0 Then DisplayError errcode
End Sub

Private Sub cmdStop_Click()
	' Stop playback of the MIDI file when this button is pressed.
	' The position within the file does not move back to the beginning.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("stop canyon", "", 0, 0)
	If errcode <> 0 Then DisplayError errcode
End Sub

Private Sub Form_Unload(Cancel As Integer)
	' Close the MIDI file when the form unloads.  This is important, because the
	' MIDI driver can only work with one file at a time.  There's no need to check
	' for an error here, since we're just closing the file.
	Dim errcode As Long  ' MCI error code
	
	errcode = mciSendString("close canyon", "", 0, 0)
End Sub

Private Sub DisplayError(ByVal errcode As Long)
	' This subroutine displays a dialog box with the text of the MCI error.  There's
	' no reason to use the MessageBox API function; VB's MsgBox function will suffice.
	Dim errstr As String  ' MCI error message text
	Dim retval As Long    ' return value
	
	' Get a string explaining the MCI error.
	errstr = Space(128)
	retval = mciGetErrorString(errcode, errstr, Len(errstr))
	' Remove the terminating null and empty space at the end.
	errstr = Left(errstr, InStr(errstr, vbNullChar) - 1)
	
	' Display a simple error message box.
	retval = MsgBox(errstr, vbOKOnly Or vbCritical)
End Sub