============
Introduction
============

This is the documentation for the MplayerCtrl, a `wx.Panel <http://docs.wxwidgets.org/stable/wx_wxpanel.html#wxpanel>`_
(wxPython, wxWidgets), which wraps the well known `Mplayer <http://www.mplayerhq.hu/>`_ into wxPython. Through this panel
you have access to each command of the Mplayer's `-slave <http://www.mplayerhq.hu/DOCS/tech/slave.txt>`_ option.

The MplayerCtrl is written in such a way that you can have a *real* media player for wxPython, because the only
alternative is the wx.media.MediaCtrl. The MediaCtrl is very buggy, can't play streams and supports just a few standard
codecs. The Mplayer can play (at the moment) 161 audio and 351 video codecs and it's still under development.
If a new version of the Mplayer releases, you can easily replace the old Mplayer(.exe) file and you won't lose the
functionality of the MplayerCtrl.

The MplayerCtrl isn't 100% working, so if you're an awesome coder and think this project is worthwhile,
then please contribute. You can use the MplayerCtrl on every OS, there are just two requirements: wxPython and
an installed Mplayer. A standalone Mplayer will also work.

How does it work?:
It's quite easy, the Mplayer has a "wid" option::

    This tells MPlayer to attach to an existing window.
    Useful to embed MPlayer in a browser (e.g. the plugger extension).
    This option fills the given window completely, thus aspect scaling,
    panscan, etc are no longer handled by MPlayer but must be managed
    by the application that created the window.

The MplayerCtrl starts a mplayer process with this "wid" option, using the subprocess module (not wx.Process),
and some other options. See the tutorial for additional help about the :ref:`tutorial-arguments`.

Why do I use subprocess and not wx.Process?:
I've also written a "test MplayerCtrl", which uses wx.Process instead of subprocess, but I didn't really like it.
I asked some people about this misery, they all said: "If it works, then use subprocess.", so I did, and it works.

There's also a repository at bitbucket: `BitBucket repository <http://bitbucket.org/dav1d/mplayerctrl/>`_


License
-------

The MplayerCtrl is licensed under the MIT-License::


    Copyright (c) 2010, David Herberth.

    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    THE SOFTWARE.



Easy installation
-----------------
There's nothing to install, just run the setup.py in the MplayerCtrl download directory and you can import
the MplayerCtrl. That's it!::

    > setup.py install

or use easy_install or pip::

    easy_install MplayerrCtrl
    # or
    pip install MplayerCtrl

There is also a Windows installer.

for more information see the :doc:`tutorial`.

Simple usage
------------
Just import the MplayerCtrl and use the :class:`~MplayerCtrl.MplayerCtrl` as a normal wx.Panel with some extra features.
Here is a simple example::

    import wx
    import MplayerCtrl as mpc
    
    class Frame(wx.Frame):
        def __init__(self, parent, id):
            wx.Frame.__init__(self, parent, id)
            
            self.mpc = mpc.MplayerCtrl(self, -1, u'mplayer.exe')
            
            wx.FutureCall(2500, self.mpc.Loadfile, u'testmovie.mpg')
            
            self.Show()
        
    if __name__ == '__main__':
        app = wx.App(redirect=False)
        f = Frame(None, -1)
        app.MainLoop()

In this example, a MplayerCtrl is created and after 2500ms (wx.FutureCall) the file: *testmovie.mpg* is loaded and the playback will start.

To read more see the :doc:`Tutorial <tutorial>`


Links
-----
`BitBucket repository <http://bitbucket.org/dav1d/mplayerctrl/>`_

`wxPython <http://wxpython.org/>`_

`wx.Panel <http://docs.wxwidgets.org/stable/wx_wxpanel.html#wxpanel>`_

`Mplayer HQ <http://www.mplayerhq.hu/>`_

`Mplayer-Documentation <http://www.mplayerhq.hu/design7/info.html#docs>`_