Version 0.31: minor update, including "MediaEndedNotice" event and "MP3 Karaoke" example overlay - for more information please see the "About PVS.AVPlayer versions.txt" download.
Library size: 53 kB
Platform: Microsoft Windows - WinForms Any CPU
Requirements: Microsoft .NET Framework 2.0 or higher
License: CPOL - Free to Use
Version 0.31, Copyright © 2013 PVS The Netherlands - Free to Use.
Introduction
PVS.AVPlayer is an MCI Wrapper Class Library for .NET developers for easy but powerful playback of movies and/or music from within your application using Microsoft Windows built-in Media Control Interface (MCI), adding:
- display formatting
- multiple fullscreen modes
- display overlays
- true repeat
- trackbar handling
- and more
PVS.AVPlayer and the example application are compiled for .NET Framework 3.5. Other versions of the library (with exactly the same functionality) are available for .NET Framework 2.0, 3.0, 4.0 and 4.5 from the link at the top of this article. PVS.AVPlayer does not contain any viruses, spyware, advertisements or other malware, does not collect any information, changes nothing permanently to your computer and does not connect to the internet.
Please note that a VB.NET version of the article can be downloaded from the link at the top of this article.
PVS.AVPlayer example application
Brief Instructions on How to Use PVS.AVPLAYER
Contents
- Adding PVS.AVPlayer to your Project
- Creating a Player
- Playing a Mediafile
- Player Display
- FullScreen Display
- So Far...
- Display Overlays
- Trackbars
- MediaEvents
1. Adding PVS.AVPlayer to your Project
Before you can use the PVS.AVPlayer library, you have to add a reference to it in your project.
First download "PVS.AVPlayer.zip", if you haven't already done so, and unpack the library (DLL) anywhere you like on your harddisk (the .XML-file contains information for Visual Studio intellisense and is not needed with your finished application). Later on, Visual Studio will automatically copy the DLL to your project output folder (bin\Release) together with the executable (application) you have created.
Next, create a new project (you can also use an existing project of course) and add a reference to the library. You can do this by right-clicking on the project in solution explorer (or using the Project menu) and then select Add Reference: choose the Browse tab and locate and select "PVS.AVPlayer.dll". Now you're ready to use PVS.AVPlayer.
Finally, you might want to include the library namespace in your project files. It allows shorter names to be used. Type at the top of every project file that uses the library:
using PVS.AVPlayer;
If you don't want to get into the examples below, here's how you can play a movie inside a control (in this case 'panel1') on a .NET Windows Forms Application Form:
Player myPlayer = new Player();
myPlayer.Play(@"C:\MyMovie.mpg", panel1);
To stop playing and remove myPlayer, use:
myPlayer.Dispose();
2. Creating a Player
To play a mediafile (movie or music), you'll first have to create a 'Player'.
In your project, you can create as many Players as you like and also get rid of them again when you don't need them anymore. You can use them simultaneously, even to play the same mediafile.
Once you have created a Player, you can keep using it to play mediafiles.
You don't have to stop a playing mediafile in order to play another mediafile, the Player takes care of that.
Usually you would create one or more Players to be used throughout the project, so you declare them at the top of your project, outside any method but within a class (global). In the next example, the name of the Player is "myPlayer1" and a few lines of code are added to use one of the events raised by the Player.
A Player can inform you about changes in its playing state by sending you 'event messages'. You can 'catch' these events with your Player's EventHandler and act upon it. For instance, in case of a MediaEnded event (that tells you that a mediafile has finished playing) you may want to play another (next) mediafile (for more information, please see: 9. MediaEvents).
Adding a Player with EventHandler to a new Windows Forms Application project:
using PVS.AVPlayer;
namespace MyProject
{
public partial class Form1 : Form
{
Player myPlayer1;
public Form1()
{
InitializeComponent();
myPlayer1 = new Player();
myPlayer1.MediaEnded += myPlayer1_MediaEnded;
}
private void myPlayer1_MediaEnded(object sender, EventArgs e)
{
}
}
}
Now all you have to do is tell the Player which mediafile (path and filename) to play and, if it's a movie, where to show it (player display).
3. Playing a MediaFile
To play a mediafile, you can use one of the Player's Play methods, but before you do so, you'll need the path and filename of the mediafile you want to play. Later on, we'll add an OpenFileDialog to select mediafiles, but for now the name of a mediafile is just added to the project (replace "C:\MyMovies\MyMovie.mpg" by the path and filename of one of your movies).
Also, if you're about to play a movie, you have to tell the Player where to display the movie: you can use a Form or a Control on a Form to display the video of a mediafile (for more information please see 4. Player Display).
To create a (tiny) mediaplayer, add a button ('button1') and a panel ('panel1') to your Form and add the PlayMedia method (see below) to the code (for a 'standard display look', you can set the background color of the panel to black). Double-click the button on your Form and add the PlayMedia instruction in the automatically created buttonclick handler. The project code now looks something like this:
using PVS.AVPlayer;
namespace MyProject
{
public partial class Form1 : Form
{
Player myPlayer1;
string myMovie = @"C:\MyMovies\MyMovie.mpg";
public Form1()
{
InitializeComponent();
myPlayer1 = new Player();
myPlayer1.MediaEnded += myPlayer1_MediaEnded;
}
private void myPlayer1_MediaEnded(object sender, EventArgs e)
{
}
private void PlayMedia(string fileName)
{
myPlayer1.Play(fileName, panel1);
if (myPlayer1.LastError)
MessageBox.Show(myPlayer1.LastErrorString);
}
private void button1_Click(object sender, EventArgs e)
{
PlayMedia(myMovie);
}
}
}
Press F5 (Start Debugging), click the button on your Form and see what happens.
4. Player Display
You can display the video of a mediafile using a Form or almost any other type of control, like a picturebox, label or panel. A panel might be the best choice because it has the least resources attached.
Any Form or suitable control will do, it doesn't have to be in the same class as the player. If you have a second Form in your project, you can display the video on that Form, controlling it from the first Form.
You can set or change the display of a player not only with the Play method (as above), but anytime you like, even when a movie is playing, with:
myPlayer1.Display = panel1; myPlayer1.Display = this; myPlayer1.Display = Form2.panel1; myPlayer1.Display = null;
You only have to set the player's display once, the player will 'remember' which display to use (as with all other player settings).
If you don't want to display video at all (but only hear the sound), you can disable the display of video with:
myPlayer1.VideoEnabled = false;
If you just want to play musicfiles, like mp3, you don't have to use a display or disable the display of video:
myPlayer1.Play(@"C:\MyMusic\MySong.mp3");
DisplayMode
Video can be shown in different ways on the player's display by setting the player's displaymode. You can have the video fill the display (stretch), zoom it, use its original size, center it or set it to any size and position you like.
You can set the player's displaymode with (among others):
myPlayer1.DisplayMode = DisplayMode.Stretch; myPlayer1.DisplayMode = Displaymode.ZoomAndCenter;
You can set the position and size of the video at will by setting myPlayer1.VideoBounds. When you do so, the displaymode is set to DisplayMode.Manual. The position is relative to the top-left of the player's display (panel1). With the manual displaymode, the player does not resize the movie (as with most of the other displaymodes) when the size of the player's display changes.
myPlayer1.VideoBounds = new Rectangle(-10, -20, 1000, 750);
myPlayer1.VideoBounds = myPlayer1.Display.DisplayRectangle;
Similar to this option are the options to scroll the position of the video (myPlayer1.VideoMove) and to zoom in or out (myPlayer1.VideoZoom). These options also allow the use of two or more movies in one display (with multiple players using the same display) for instance by scrolling them in and out of view.
for (int i = 0; i < myPlayer1.Display.Height; i++)
{
myPlayer1.VideoMove(0, 1); System.Threading.Thread.Sleep(2); }
Note: A movie is displayed (sort of) on top of a display control (panel1). If you click on the part of the control where the movie is being displayed, the control (panel1) does not 'receive' the mouseclick (exception: right-click for contextmenu). The same goes for most other events. Also any control inside the display control is overwritten (not visible) by the movie. You can display a control on top of a video if its parent control is not the player's display (panel1) or by using a PVS.AVPlayer display overlay, which is more convenient and has more options (like transparency and opacity).
5. FullScreen Display
PVS.AVPlayer has built-in options to display a movie using the entire screen, hiding the desktop, taskbar and anything else. However, you still can have other windows (and the Taskbar) to be displayed in front of your fullscreen application.
You can not only show a Form fullscreen but also a player's display, meaning that you can show a player's display using the entire screen even if it's smaller than the Form it's on (while the player's display still remains part of the Form).
You can switch to fullscreen display with:
myPlayer1.FullScreen = true;
Before (or after) you do so, you can use the FullScreenMode option to select what will be shown fullscreen:
FullScreenMode.Form - shows the Form (the player's display is on) fullscreen. FullScreenMode.Parent - shows the parent control (the player's display is in) fullscreen. FullScreenMode.Display - shows the player display fullscreen (default setting).
myPlayer1.FullScreenMode = FullScreenMode.Form;
The player's display or its parent can't be inside any other control than the Form itself if you want to use fullscreen modes 2 or 3.
Putting It Together
Before adding the fullscreen option to the example code, we must have some way to return to normal display, otherwise we'll be stuck in fullscreen display. The best way perhaps would be to add a contextmenu to panel1 or even an 'always on top' controller Form, but for now we're just going to 'catch' keypress events for the Form, the player's display is on by setting the Form's KeyPreview property to 'true' and add a Form's keyeventhandler to check if the 'Space' key was pressed.
Also a few other things have been added to the code:
- Clicking
button1 now displays an OpenFileDialog to select one or more mediafiles
- Some more declarations at the top (
string array with filenames and 'button1 on top' original position storage)
- More player initialization (display and displaymode are set before using the play method)
- The player's
MediaEnded event now plays 'next' mediafiles added PlayNextMedia method
- Show a control (
button1) on top of a movie in fullscreen mode (without using a display overlay - see 'Note' above).
using PVS.AVPlayer;
namespace MyProject
{
public partial class Form1 : Form
{
Player myPlayer1;
OpenFileDialog myOpenFileDialog1;
string[] myMovies;
int movieToPlay = 0;
Point buttonLocation;
public Form1()
{
InitializeComponent();
myPlayer1 = new Player();
myPlayer1.MediaEnded += myPlayer1_MediaEnded;
myPlayer1.Display = panel1;
myPlayer1.DisplayMode = DisplayMode.Stretch;
myOpenFileDialog1 = new OpenFileDialog();
myOpenFileDialog1.Multiselect = true;
this.KeyPreview = true;
this.KeyDown += new KeyEventHandler(Form1_KeyDown);
}
private void myPlayer1_MediaEnded(object sender, EventArgs e)
{
PlayNextMedia();
}
private void PlayMedia(string fileName)
{
myPlayer1.Play(fileName);
if (myPlayer1.LastError)
{
MessageBox.Show(fileName + "\r\n\r\n" + myPlayer1.LastErrorString);
if (myMovies.Length > 1) PlayNextMedia();
}
}
private void button1_Click(object sender, EventArgs e)
{
if (myOpenFileDialog1.ShowDialog(this) == DialogResult.OK)
{
myMovies = myOpenFileDialog1.FileNames;
movieToPlay = 0;
PlayMedia(myMovies[movieToPlay]);
}
}
private void PlayNextMedia()
{
if (++movieToPlay >= myMovies.Length) movieToPlay = 0;
PlayMedia(myMovies[movieToPlay]);
}
private void Form1_KeyDown(object sender, KeyEventArgs e)
{
if (e.KeyCode == Keys.Space)
{
ToggleFullScreen();
e.Handled = true;
}
}
private void ToggleFullScreen()
{
if (myPlayer1.FullScreen)
{
myPlayer1.FullScreen = false;
button1.Location = buttonLocation;
}
else
{
buttonLocation = button1.Location;
myPlayer1.FullScreen = true;
button1.Location = new Point
(myPlayer1.Display.Width - button1.Width - 24, 24);
button1.BringToFront();
}
}
}
}
6. So Far...
One Form, one button and one panel. That doesn't even come close to being a real mediaplayer (there's not even a 'Stop' button). Still, it already has everything in it to play mediafiles, and more.
The example code was kept short, just to give an idea how to start with PVS.AVPlayer. The code could do with some rewriting for a real application but the building blocks of it can be used as a starting point. You can have only a few lines of code in your application to play a movie or even create your own home mediaplayer.
Still, it's Windows Media Control Interface (MCI) and your application that do all the real work. PVS.AVPlayer just passes on your instructions to MCI and then continues doing nothing until you use another instruction, resize the player's display or when a MediaEvent occurs.
7. Display Overlays
With a PVS.AVPlayer Display Overlay, you can very easily display something (like text, pictures and movies) on top of a movie.
A PVS.AVPlayer Display Overlay is a Form, just like the ones you use in your .NET Windows Forms Application projects. PVS.AVPlayer just displays it on top of a player's display.
To see what that looks like, let's add a display overlay to the example code:
First, create a new Form (in this example 'Form2') in your Project (menu Project: Add Windows Form...) and drag a control from the Toolbox, let's use a Label, on it. We now have a display overlay.
You may want to make some adjustments to the label, like changing the text, increasing the fontsize and changing the foregroundcolor, but for now leave its backgroundcolor the same as the Form's backgroundcolor. And of course you can add as many other controls as you like, and maybe use some of them to control the 'underlying' (or any other) player if you like. Designing a Display Overlay is just like designing a 'normal' Form in your applications, including the code you can add to the Form.
Next (and last), all we have to do is to attach the overlay (Form2) to the player:
Form2 myOverlay1 = new Form2(); myPlayer1.Overlay = myOverlay1;
You can insert these lines in the example's Form1() method (see remarks in the example project code above) or anywhere you like (but of course only after a player with a display has been created), press F5, play a movie and see what it looks like.
Note: You might want to store the overlay reference in a global variable (as with 'myPlayer1') in case you want to dispose (or reuse) the overlay:
myPlayer1.Overlay = null; myOverlay1.Dispose();
Using Display Overlays
To make a display overlay transparent, PVS.AVPlayer sets the Form's TransparencyKey property to the backgroundcolor of the Form. If you don't want the background to be transparent but want to use one of the foregroundcolors for transparency (for 'see through' shapes) you can set the Form's TransparencyKey yourself (if it's set, PVS.AVPlayer doesn't change it).
To avoid unwanted (partially) transparency of items on a display overlay, use a background (or transparencykey) color that is usually not or very rarely used (like maybe 'RosyBrown'). To avoid visible 'edges' around text on a transparent overlay, use a backgroundcolor for the Form that is close to the color of the text. Setting the Form's opacity a little lower than 100% 'softens' text and other items on a transparent display overlay.
An overlay can be displayed using the size of the movie or the size of the player's display. Use the OverlayMode property to set the overlay size.
Usually an overlay is shown only when a movie is being played. If you want it to be always visible, you can set the OverlayHold property to 'true'.
If you want to use an overlay for textinput or have selectable controls (like buttons) on it, you can set the property OverlayCanFocus to 'true'.
To regularly change items (animation) on a display overlay (e.g. the text of a Label) or executing code in the overlay (Form2) class, you can use a timer (the overlay is usually not the Form that has focus).
If the display overlay Form has no contextmenu, it will 'inherit' the contextmenu of the player's display (panel1; if any).
Dynamic Display Overlays
A dynamic display overlay is an overlay that changes its contents when certain events take place, like when a timer's interval has elapsed or a mediafile starts or stops playing.
If you are using a dynamic display overlay, you may want to update the dynamic content only when the overlay is activated and visible (e.g. with myPlayer1.Overlay = myOverlay1 and a mediafile is playing (or the Overlay Hold option is active) and stop updating when the overlay is deactivated (e.g. with myPlayer.Overlay = null) or not visible (minimized).
To enable/disable updating dynamic content of a display overlay, you can use the overlay Form's VisibleChanged event (this may differ from 'normal' Forms - as a display overlay is a child Form the VisibleChanged event is always fired when visibility changes, even when the overlay is 'minimized' or restored from minimized):
private void myOverlay1_VisibleChanged(object sender, EventArgs e)
{
if (this.Visible)
{
}
else
{
}
}
PVS.AVPlayer takes special care the display overlay's VisibleChanged event is fired when appropriate.
Synchronizing a player's display and overlay when opening or restoring a minimized Form
As a display overlay is a top-level control (a Form), it can not be properly attached to a player's display. PVS.AVPlayer takes care of that when an overlay is activated or a player's display is moved or resized, but another technique is required when the main Form (with a player display and overlay) is (re-)opened.
Synchronizing a display overlay with the main Form when restoring a Form from a minimized windowstate is a PVS.AVPlayer built-in option: OverlayDelay. When a Form is opened or restored from minimized, an overlay's visibility is delayed until the main Form is visible. The OverlayDelay option is enabled by default (300 ms) but can be changed with:
myPlayer1.OverlayDelay = ms; myPlayer1.OverlayDelay = 0;
8. Trackbars
You may want to use a trackbar type control with your player to show and change the playback position of a mediafile. That's not a difficult task, although there's more to it than just might seem at first sight. That's why PVS.AVPlayer can handle this kind of control for you.
Just add a TrackBar control to your Form (or Display Overlay) and tell the player to handle it with:
myPlayer1.PositionSlider = trackBar1;
By setting the PositionSliderMode option, you can have the trackbar show the position between the beginning and end of a mediafile (PositionSliderMode.Track) or between the player's media Start- and EndPosition (PositionSliderMode.Progress).
On slower systems, you might want to set myPlayer1.PositionSliderLiveUpdate = false.
Similar, you can also let the player handle an audio volume slider (myPlayer1.AudioVolumeSlider), an audio balance slider (myPlayer1.AudioBalanceSlider), a playback speed slider (myPlayer1.SpeedSlider) and/or a playback shuttle slider (myPlayer1.ShuttleSlider):
myPlayer1.AudioVolumeSlider = trackBar2;
Note
- When you use a player's
PositionSlider, a timer will be used when a mediafile is playing.
- With a shuttle slider, you can repeatedly step fore- or backwards 'frames' with some movie types only.
- With audio (music) only: the playback position returned by MCI with other than normal playback speed is not correct.
9. MediaEvents
The MediaEvents raised by PVS.AVPlayer allow your application to react to certain changes in the state of your player, like when a mediafile has finished playing. You don't have to use any of the events, and if you don't, PVS.AVPlayer will ignore them too and not send any event messages to your application.
The MediaPositionChanged event is a little bit different from the other ones because it gets sent very often when a mediafile is playing and it involves a timer. It informs you about a player's playback position change when a mediafile is playing and you could use it to update some position indicators on the screen, like a slider (if you're not using the player's positionslider) and/or some 'counters':
private void myPlayer1_MediaPositionChanged(Object sender, EventArgs e)
{
myTrackBar1.Value = myPlayer1.Position.TotalMilliseconds;
label1.Text = myPlayer1.GetMediaLength(MediaLength.FromStartPosition).ToString();
label2.Text = myPlayer1.GetMediaLength(MediaLength.ToEndPosition).ToString();
}
By using myPlayer1.TimerInterval, you can change the frequency by which the mediapositionchanged events are sent (default 200 milliseconds).
Submit an article or tip
Post your Blog
News 
Suggestion 
Bug 
Joke 
Rant 
Admin 
