Update: August 16, 2011 - I made some major format changes with this article. It should be much easier to read and follow. It is definitely a much smoother layout. Also this article will work for Visual Basic 2008 and MCI for Visual Basic 2010.
Purpose of this Tutorial: To explain how you can use the Windows MCI Command Interface to create your OWN media applications including: Music Players, Movie Players, CD Players and more. File formats include: MP3 files, Wav files, MPEG, WMA, WMV, and More! Hopefully before you finish this article, you will have a better understanding on how you can make your own media applications.
Visual Basic 5.0/6.0 Information: While this tutorial’s source code is made with Visual Basic.NET, Visual Basic 2005/2008 and VB 2010 in mind, the principals are the same for all languages. The biggest change to make the example code work in VB 6/5 is to change the “Integer ” variables and parameters to “Long” value types instead. I have a link to a tutorial in Word format you can download with VB 6.0 below.
Note: The tutorial in Microsoft Word RTF format and a example application is available for download at this link.
With this tutorial you can learn how to code the MCI Device via the Mci Command String Interface. I will not give you much specific code but show you how to write your OWN code to suit your needs. That way you will learn how to program using the MCI Command String Interface. The MCI Interface is fairly powerful and can be very useful. You can play almost any movie file available. Including DVD Movie’s (If you have a Video Card that has hardware support for dvd playback or a software decoder installed), Play Divx Movie’s(Must have the Divx Codec installed), AVI movies, QuickTime movies and more. Can also play a wide range of music files including MP3, WAVE, MIDI, ASF, and more. In this tutorial I will show you how to program the Mci Device so you would have the ability to make a feature rich media player to your exact specifications. As for the exercise in this tutorial I will show you how to make a music player with a few features. If I get good response’s and feedback I may create another tutorial in the future. I am pretty sure though, after you read and study this tutorial you will be able to create your own music and movie player with ease. Some of you may be familiar with my various Media Library’s (csMusicLibrary, csMovieLibrary, ect…) Almost ALL of them are based on the mciSendString command interface. So, you can really see how powerful this interface can be.
Note: I didn’t go through by over my writing with a fine toothed comb. So, there could be some mistakes.
Lets get some Documentation
Start out by going to: http://msdn2.microsoft.com/en-us/library/ms712587.aspx– website, then click on the: ‘Multimedia Command Strings’ link if it doesn’t go directly to that page. Go ahead and look over some of the documented MCISendString Commands available. For example: Click on the ‘open’ command at the left side of the webpage. Scroll down alittle on the right side of the page and you will see the documented device types and the device flags available for that device type. Scroll down alittle more and it will explain what the meaning of each device flag is for. For example: On the same ‘open’ page, scroll down till you find the waveaudio device listing. Look at the column to the right and you will see the available flags and the meanings that will work with the waveaudio device. Scroll down to the Value section listings of the page and find the ‘buffer buffer_size’ flag and look to the right and it explains what it is for and what it does. So, now that we’ve got that out of the way, lets get started with programming the Mci Device.
Note: The mpegvideo device driver is not documented at the msdn webpage. We can still do quite alot with it since alot of the commands from the digitalvideo device and waveaudio device will work with the mpegvideo device. The MpegVideo device type would be the Device Driver of choice for most of our multi-media needs since it will play alot of the movie and music formats out there.
What is mciSendString?
The first step you will want to do is add:
Private Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal lpstrCommand As String, ByVal lpstrReturnString As String, ByVal uReturnLength As Integer, ByVal hwndCallback As Integer) As Integer
– to the declarations section of our form. The return value of the mciSendString function will be a number. It will return different numbers for different errors or return a 0 if the command was successful. Example: Say we made a variable;
Dim retVal As Integer
We would use our mciSendString function in this manner…
retVal = mciSendString("Open " & filename & " alias movie", 0, 0, 0)
– retVal would contain a number returned by our Mci Device to let us know what happened. More on that below. I will briefly go over each parameter of the mciSendString function.
The lpstrCommand parameter is a string that specifys the MCI command string and flag. In other words this parameter would be our command that we pass to the MCI Device. Like in our paragraph above, open would be a command string that we passed to the MCI Device. It tells the MCI Device to do something. The command string could also have flags associated with it. More on that below in the tutorial.
The lpstrReturnString parameter is a buffer that receives the return information. Example: If we used the status command string and used the position flag, lpstrReturnString would contain the position information of the music or movie we are playing. We would just create a string variable with a character buffer.
Dim returnData As String = Space(128)
ReturnData is now a String with a 128 Space buffer.
We would put ReturnData in the parameter and it will receive our position value.
The uReturnLength parameter is the size, in characters of the lpstrReturnString parameter. If we used
Dim returnData As String = Space(128)
– for our lpstrReturnString parameter. Then the size we would put for the uReturnLength parameter would be 128 or you can put Len(ReturnData).
The hwndCallback parameter you will most likely never use. It would contain the Handle to to a callback window if the Notify flag was used in our command string. Just set this parameter to 0.
Note: If the command string does not return a value in the lpstrReturnString parameter then you can set the lpstrReturnString, uReturnLength, hwndCallback parameter to “0”. More on that further in the tutorial.
What is mciGetErrorString?
OK, the second step you would want to do is add:
Private Declare Function mciGetErrorString Lib "winmm.dll" Alias "mciGetErrorStringA" (ByVal dwError As Integer, ByVal lpstrBuffer As String, ByVal uLength As Integer) As Integer
– to the declarations of the form. This is a very useful function for programming the Mci Device. This will convert the number returned by our retVal variable (from the mciSendString function) into something that we will be able to understand alittle more. It will give us a brief description of what happened. I will briefly go over each parameter in this function.
The dwError parameter will contain our return value from our mciSendString function.
Say we used retVal as our variable to recieve the return value of our mciSendString function. In the dwError parameter we would put in the RetVal varaiable.
The lpstrBuffer parameter will contain the string value of our dwError parameter.
Example: Say we had
Dim GetError As String = Space(128)
If you put GetError in the lpstrBuffer parameter, then GetErrorwould receive the error string.
The uLength parameter is the character length of the dwError parameter.
Example: Say we used the above GetError string variable. We would create the string to have a buffer of 128 characters.
Dim GetError As String = Space(128)
So, in the uLength parameter we would put 128 or you can put Len(GetError). Either way will work just fine.
Write your own Music Player
Let start doing alittle MCI Programming by making a simple mp3/wave player. Put 4 command buttons, 3 labels, and a timer on the form. With the first command button name it btnPlay set the .Text property to “Play”, the second button name btnStop and set the .Text property to “Stop”, the third button, name it btnPause and set the .Text property to “Pause”, the fourth name btnClose and set the .Text property to “Close”; name one of the labels lblPosition and will be used for the position status, name the second label lblLength and will be used for the length, and the third name lblError will be used to give us our Mci error status(Make the label fairly big because it could have a long explanation.) The timer will give the position status of the music every second, so set the interval to 1000.
Pretty much always the first step in programming the Mci Device is starting with the open command string, since it is where we select the device type we want to use and create the alias we want to use. So go to the webpage I stated at the beginning of this tutorial and find the ‘open’ command string and click on it to read the documentation. Look over our available flags. We will want to use 2 of the flags. The type device_type*(note below) and alias device_alias*(note below) flag. The next step you want to do is select the file you want to play. One annoying thing about the Mci Device is that it has a hard time with long filenames, so you will either have to convert the filepath and name to the shortpath of the file or a easier and recommended way is just putting quotes around your filepath and name. The way to do this is first select the file you want to play. Then wrap the filepath and name in quotes.
Dim fileName As String = Chr(34) & "C:\MP3 Music\mysound.mp3" & Chr(34)
That will wrap the filepath in quotations. ( Chr(34) is the code for ” *Quotes* ) Of course, change the path and filename to a music file you have on your computer. Each time you use the open command, you will want to put the quotes ” ” around the file you want to play. Ok, so now that we have selected the file we want to play and put the quotes around the path, lets start programming the Mci Device. Put this in the declarations section of our form.
'Will store our return value from the mciSendString function.
Dim retVal As Integer
'This variable will contain the data from the lpstrReturnString parameter. It will have a 128 character buffer.
Dim returnData As String = Space(128)
'Will store our return string from the mciGetErrorString function. With a buffer of 128 characters.
Dim errorString As String = Space(128)
'Will contain True or False if our mciGetErrorString was successful at determining our error returned
'from the mciSendString function.
Dim errorSuccess As Boolean
In the btnPlay button put:
'Replace the path and filename' with file that you have.
fileName = Chr(34) & "C:\MP3 Music\mysound.mp3" & Chr(34)
retVal = mciSendString("open " & fileName & " type mpegvideo alias oursong", 0, 0, 0)
O.k. Lets break this down. Our retVal variable will contain the return value of the ‘mciSendString command’. The open command will open our fileName using the mpegvideo device type and create a alias named oursong.
*Note: The type flag can be optional. The Mci Device is usually very good about auto-selecting the correct device driver of our specified file.
*Note Again: The alias flag can also be optional. I highly recommend using it so you don’t have to keep referring to your device by the fileName variable. Just use oursong to refer to our opened device. Or any other name to refer to the device.
To see if the Mci Device was successful lets call our mciGetErrorString function. In the same command button below the code we already put in add:
errorSuccess = mciGetErrorString(retVal, errorString, 128)
O.k. Lets break this down. Our errorSuccess variable will contain the return boolean value of our mciGetErrorString function. It will contain either “True” if it was successful or “False” if it was not successful. The retVal variable we used contains the return value from our mciSendString function.
Lets get the description of our error if one was created. In the same command button type in:
lblError.Text = "Error Status: " & errorString
Run the program and press the “Play” button. lblError should read “The Specified Command Was Carried Out.” That means that everything went smooth and is O.K.
Now goto the webpage again and find the close command string. In the btnClose button type:
retVal = mciSendString("close oursong", 0, 0, 0)
errorSuccess = mciGetErrorString(retVal, errorString, 128)
O.k. Lets break this down. You should already know what the retVal variable returns. So, I won’t go over that again. What the close command does is close either a specified device identifier(Alias) or you can close all device identifiers(Alias’s) by using the all flag. So, what we just told the Mci Device to do is close our oursong device from memory. Notice that the other 3 parameters are “0” zero? Well, since the close command does not return anything we can just set the parameters to “0”. You should already know what the mciSendErrorString does so I won’t go over that again.
Now run the program again and press the play button twice. lblError should now read “The specified alias is already being used in this application. Use a unique alias.” The error string returned should be self-explanatory, but I will explain it briefly. What its saying is that the oursong alias is already opened and is being used so if we wanted to open another Mci Device we need to supply a new alias. Now press the btnClose button. lblError should now read that “The Specified Command Was Carried Out.” That means that our close command was successful at closing our oursong from memory. Now press the play button and lblError should read “The Specified Command Was Carried Out.” Press the play button again and lblError should read that “The specified alias is already being used in this application. Use a unique alias.” If you press that “Close” button lblError should read that the command was carried through. If you press that “Play” button lblError should again read that the command was carried through. Blah.. Blah.. Blah.. O.k. enough of that stuff.
Now lets program the Mci Device to play our Mp3, Wave, ect. song. Go to the webpage and select the play command and look over it. Every device type recognizes the play command string. In the “Play” button between the mciSendString code and the mciGetErrorString code that we already put their type:
retVal = mciSendString("play oursong", 0, 0, 0)
O.k. Let break this down. The play command tells the Mci Device to start playing the file contained in the ‘oursong’ alias. Pretty simple. Run the program and press the “Play” button and it should start playing the song you specified in the ‘fileName’ variable. Everything should be going well. If it isn’t check the lblError Text and see what the mciGetErrorString function is returning. Maybe while you was looking at the documentation on the play command you noticed a from position flag and a to position flag. What these 2 flags do is allow you to start playing at a certain point in the file and play to a specified point in the file. If you want to play the complete file then just ignore these 2 flags. But if you want to specify a starting point and a ending point you would program the Mci Device in this manner. (You can also specify whether to start playing the song from a specified point to the end of the song, or tell it to start from the beginning but only to a specified point.)
retVal = mciSendString("play oursong from " & 1000 & " to " & 3000, 0, 0, 0)
O.k. Lets break this down. We told the Mci Device to play ‘oursong’ from “1000 milli-seconds” to “3000 milli-seconds”. Pretty simple right? Now that we have a play command and a close command, what if you just wanted to stop the song at its current playing position and not completely close the file? Well, thats where the ‘stop’ command comes in. Go back to the msdn documentation website and click on the ‘stop’ command. Notice that their is only 1 flag available and thats for digital devices? Their are no other flags we need for this command. Lets write our stop command. In the btnStop button type:
retVal = mciSendString("stop oursong", 0, 0, 0)
O.k. Lets break this down. Well, theres not much to break down. Its pretty self-explanatory. What it will do is tell the Mci Device to stop playing ‘oursong’. Not really anything more to say.
What if you wanted to add a pause command to our music player? Nothing to it. Just go to our Mci documentation website and click on the pause command. Pretty much like our stop command it doesn’t have any special flags associated with it. Lets write our pause command. In the btnPause button type:
retVal = mciSendString("pause oursong", 0, 0, 0)
O.k. Lets break this down. The ‘pause’ command is simply telling the Mci Device to stop playing oursong at the current playing position. Pretty simple. What if you wanted to resume a song that you paused with the ‘pause’ command? Nothing to it. Just go to the website and click on the ‘resume’ command and look at the documentation. Just like our ‘pause’ command their are no special flags associated with the ‘resume’ command. Put another command button on the form and name it btnResume and set the .Text property to “Resume”. Lets write our code to resume the playing of oursong.
retVal = mciSendString("resume oursong", 0, 0, 0)
O.k. Lets break this down. It is just simply telling our Mci Device to ‘resume‘ playing from where it was paused at when we used our ‘pause’ command. Nothing to it huh?
O.k. Now you have some basic functionality for your music player. Now you may want to be able to track the current position that the music is currently playing at. No Problem. Go to our documentation website and click on the ‘status’ command string. Look around on that page you see a ton of flags available with this command string. If you look at the waveaudio device you will see a position flag. That is the one we want to use to get the current position of our song. Lets write some code for it. In the timer control put:
retVal = mciSendString("status oursong position", returnData, 128, 0)
lblPosition.Text = "Position: " & Val(returnData)
O.k. Lets break this down. you should already know what the retVal variable is for. The ‘status’ command is telling the Mci Device that we want to get the status of oursong. But to use the ‘status’ command we have to specify a flag. So, you will have to tell the Mci Device what status information to return. We specified the position flag so, it will return the current playing position of oursong. lblPosition will contain the position value. Noticed that I used Val(returnData) for the lblPosition .Text? I did it so that lblPosition will only contain the numbers in the ReturnData string and not the remaining spaces in the buffer. Getting the hang of it now? Lets get our Mci Device to do more.
Did you happen to wonder what time format the position flag was returning to us? Well, lets have the Mci Device tell us what the answer is. Looking at our documentation webpage you should still be at the ‘status’ command string documentation. Look under either the digital video or waveaudio device type. You will see that there is a time format flag. That is the flag that we will use to get the current time format the Mci Device is using. Just draw a command button on the form and name it btnTimeFormat set the .Text property to “Time Format:”. In the code window of that button type:
retVal = mciSendString("status oursong time format", returnData, 128, 0)
O.k. Lets break this down. We are passing the ‘status’ command string to the Mci Device and using the time format flag. This will tell the Mci Device to give us the current time format. We will get our answer by getting the value of our returnData variable. If you want you can just open the Mci Device by pressing the “Play” button and then press the “Time Format” command button. It will throw a Messagebox with the time format that the Mci Device is currently using. It most likely should say “milliseconds”. Still with me? Easier then you thought huh? What if you wanted the format in seconds? Well, the Mci Device doesn’t support returning the time format in seconds but you can easily do it yourself. 1000 milliseconds = 1 second. So, all you would need to do it create a variable to divide our Val(returnData) / 1000. The variable will contain the value in seconds. What if you wanted to get the length of the song? Well, that is just as easy as getting the position. In the “Play” command button right above our mciGetErrorString function type:
retVal = mciSendString("status oursong length", returnData, 128, 0)
lblLength.Text = Val(returnData)
O.k. Lets break this down. We are simply telling our Mci Device to tell us the length of oursong. Earlier we asked the Mci Device to give us the current time format and it returned “milliseconds”. So, that will be the format that our length will be returned in since we haven’t changed the time format. Can we change the time format? Yeps we sure can. Goto our Mci document page and click on the ‘set’ command string. Just like our ‘status’ command string the ‘set’ command string has a few flags available to use. The flag we want to use to change the time format would be none other than the time format flag. What you will find out though is some files, like mp3’s, the Mci Device only supports the “milliseconds” time format. If we use the mpegvideo device driver then the only available time formats would be “frames” and “milliseconds. Since we are playing music files we won’t be able to get a time format in “frames”, only “milliseconds”. If you only wanted to play wave files, for example, you could use the waveaudio device type and get the time format in “bytes”, “milliseconds”, and “samples”. I don’t think “milliseconds” is all that bad though. What else would you want to add to your music player?
Do you want to know if the music is currently playing? Would you like to change the position of the file in real time? How about a volume control? Want all 3? Well, lets get started and first write a simple function that will let our application know if it is playing or not. Write the code below in the form.
Private Function playingStatus() As Boolean
retVal = mciSendString("status oursong mode", returnData, 128, 0)
If returnData.Substring(0, 7) = "playing" Then
playingStatus = True
playingStatus = False
O.k. Lets break this down. We are going to use our playingStatus function to contain “True” or “False” depending on whether or not the Mci Device is playing. If you check out our documentation website and clicked the status command string. Then scrolled down you would find a mode flag available. If you read the description of the mode flag it tells you what value’s it would return. So, now to get the playing status we would just need to get the value that is stored in our ReturnData variable. But since our ReturnData variable is 128 characters long we only want to get the first 7 characters. If ReturnData contains “playing”(which is 7 characters long) then our Mci Device is currently playing and will put “True” in our playingStatus function. Other modes are available too. The device can return “stopped”, “paused”, “not ready”, ect. Right now we are only interested in checking our Mci Device to see if it is “playing” or not. Thats important for our changing the position code. Lets write that now. Put a Hscrollbar control on our form and name it posChange. Type this code in the “posChange_Scroll” sub:
If playingStatus() Then
' The Mci Device is playing so play from.
retVal = mciSendString("play oursong from " & (posChange.Value * 1000), 0, 0, 0)
' TheMci Device is not playing so seek to.
retVal = mciSendString("seek song to " & (posChange.Value * 1000), 0, 0, 0)
O.k. Lets break this down. If you go to our documentation webpage and click on the play command string you will see a available flag named from. That is the command string and flag we will use to keep the file playing but at a position specified by our posChange.Value. If you go to our documentation website and click on the seek command string you will find a available flag named to. That is the command string and flag that we will use to move the position and but not start playing. Got that? To recap what I said above if oursong is already “playing” we will want to continue “playing” oursong but at the point in the file specified by our posChange control. So we will use the commandstring ‘play’ and use the flag ‘from’ to continue playing oursong “from” the position specified by our posChange control. Enough about that already. Lets move on. The Hscrollbar cannot contain a value larger than “32767”*. Since the time format of the Mci Device is in “milliseconds” and the total length of almost every song would be larger then “32767 milliseconds”* we must convert the “milliseconds” format to a smaller number. The useful and easy thing to do would be to convert it to “seconds”. So, we will set the .Max property of our Hscrollbar to equal the total length of the song in “seconds”. To do this. Let go back to the btnPlay button and type this code below our code that tells the Mci Device to “play”.
'Get the length of the song in milli-seconds.
retVal = mciSendString("status oursong length", returnData, 128, 0)
'This will convert our “millisecond” value to a value in “seconds”
'Remember that 1000 milliseconds will equal 1 second. 2000 milliseconds = 2 seconds and so on.
posChange.Max = Val(returnData) / 1000
*Note; Update: Visual Basic.NET does NOT seem to have the .Max property of the scrollbars limited to a value of ‘32767’ as it was in VB 5.0, 6.0. So, it seems that you no longer need to worry about setting the above code up by converting the milli-seconds to seconds. It looks like it is now able to contains milliseconds with no overflow.
O.k. This should be fairly simple to understand. We are just telling the Mci Device to return the length of oursong. posChange.Max property will now contain the length in seconds (or milliseconds, its your choice as to how accurate you want to be able to change the position). We divided the number returned by our ReturnData variable by 1000 which would equal “seconds”. Got that? I hope so. Now if you go back and look at the code above to change the position you should understand it alittle more. I hope this helped you instead of confused you. I’m trying to thoroughly explain it so you will completely understand. Just as a reminder. If the code is not doing what you expected and you want to find out what is going on use the mciGetErrorString function. O.k. Enough on this. Lets do one last thing that would be useful for a basic music player. Lets create a volume control. Put a Vscrollbar control on the form and name it volScroll and set the .Max value to “1000”. “1000” is the max for the volume. “0” is the minimum. Then go to our documentation webpage and click on the setaudio command string. Look over the available flags and you will find a volume to flag. That is the command string and flag we will want to use. So in the volScroll _Scroll sub put in this code.
retVal = mciSendString("setaudio oursong volume to " & volScroll.Value, 0, 0, 0)
O.k. This should be pretty simple to understand. We are simply telling our Mci Device to set the volume of oursong to the current value of the volScroll control. Thats it for a music media player with basic features! Check out my examples and libraries at www.vbcodesource.comwebsite.
Below is the final product…
I hope this tutorial we went over gave you a nice understanding of how to program the Windows Mci Device. As you can see there are quite a few commands and flags available to do almost anything you want in a Movie or Music player. You could “turn of the left audio channel”, “set the volume for the right audio channel”, “you could open and close the cd door”, “change the speed at which the movie or music plays at” and much more. You should be able to decide what features you want and program the Mci Device yourself and have it do it for you. Remember to use the mciGetErrorString function as it is very useful. It tells you if the device understood what you told it to do, if the Device Type that you are using supports that command string, and much more. Bookmark the msdn webpage I gave you: http://msdn2.microsoft.com/en-us/library/ms712587.aspx – so you can have it as a good reference to see what command strings and flags are available. Reference – http://www.vbcodesource.com – Have Fun!