QUI for MPlayer 1.7b README
Best viewed with word wrap turned on.

Table of Contents:
1. Introduction
2. Install Notes
3. Useful Information (suggested reading)
4. Editing defaults.conf + the new options dialog
5. Button Themes
6. Known Bugs
7. Contact Information and GPL

1. ***Introduction***
First, thanks to Michael Goettsche and everyone on the qt-interest and mplayer-dev-eng/users mailing lists, #qt on irc.freenode.net, TJ Weber for some wav file writing code, and the KDevelop and JustLinux forums.  This couldn't have happened without you.


2. ***Install Notes***
Previously, QUI was installed in /usr/local/kde/bin.  Now it appears to be installing in /usr/bin like one would expect.  This has to do with the way KDevelop does its makefiles, so I have very little control over it.  As such, I can't guarantee that it's going to be installed in either of these places (except the RPM, which I believe should always install to /usr/bin), but if you can't find the executable those are the first places to look (although of course /usr/bin shouldn't be a problem).

QUI requires QT and MPlayer (I recommend a reasonably recent release, as it works much better with QUI than some earlier versions).  I now strongly recommend that you also install aumix and make sure that it is located somewhere in your path (as MPlayer must be).  Using aumix for the volume control is much smoother than the built-in MPlayer functionality.  Additionally, I strongly recommend installing lsdvd now, as it allows QUI to get an accurate time on DVD's.  It will work without, but the times will be as reported by MPlayer (as in wrong).  The configure script will hopefully cover any other incompatibilities.  It does not check for MPlayer, because QUI will still compile without it.  However, QUI itself checks to make sure that MPlayer starts correctly, so if you try to play a file without MPlayer, QUI will now display a proper error message and exit.

Note that in order to use button images you now need ImageMagick installed.  

To sum up, here are the requirements:
KDE (hoping to get rid of this as a dependency since I actually don't need it, but haven't been able to thus far)
QT
MPlayer
ImageMagick (for button images)
Strongly recommended:
aumix
lsdvd


3. ***Useful Information***
If you can't find your answer here, check the FAQ on qui4mplayer.sf.net.

If you know that you have installed MPlayer, but QUI still can't find it, make sure that MPlayer is correctly listed in your path (as the error message states).  It generally seems to install to /usr/local/bin when I compile from source, so that would be my first place to look for it if I were you.

To toggle fullscreen, simply click the "FS" button.  QUI is now capable of being displayed over the MPlayer window so you can interact (pause, stop, adjust volume, etc.) while in fullscreen mode.  I have had some intermittent problems with this though, so to turn it off and go back to the old method of fullscreen simply remove the "-fstype" and "layer,none,fullscreen" lines from the MPlayer options in the options dialog.  You may also want to do this because in KDE the taskbar is displayed over the video as well so it must be hidden manually.  If you run into trouble with fullscreen play you can always click on the video and then press the "f" key to force MPlayer to exit fullscreen mode.  I don't recommend doing this normally though because it messes up the synchronization with QUI.  Note: As of version 1.4 fullscreen play should be much more reliable, so I hope that removing the fstype lines will no longer be necessary.  Also, I have no idea whether the old method even works anymore as I don't really test it.

Do not minimize QUI while in fullscreen mode.  This will force you to use the above method to get out which is bad (of course:-).  Instead click on the video and QUI will be hidden behind it.

You can save the times and titles that appear in the playlist after a file has been played by simply saving the playlist again.  Times and titles are stored along with the file list so they can be displayed immediately the next time a list is loaded.  Some titles may be automatically read from MP3 files when they are added now as well.
 
Since version .93b, you can pass files as arguments to QUI and it will automatically add them to the playlist and start playing them.  However, if you do this from Konqueror (and possibly other file managers), it will open each one in a new instance of QUI.  I believe that this is a quirk of Konqueror itself, so there's not much I can do to fix it.  You can still start QUI from the command-line with as many files as you want, just separate each one with a space (so if the filename has a space, you'll need to enclose it in quotes).  I might be able to fix this, but it's not a real big priority for me.  Feel free to yell at me if it is for you:-)  Note that a possible workaround now is to simply drag and drop to the QUI playlist window.

If you switch virtual desktops away from the one QUI is on when it is not the focused window and then switch back to it, the playlist will not get shown until QUI regains the focus (i.e. clicking on it).  I don't consider this a bug, and I'm not sure I could fix it anyway, so this is just FYI.

Sometimes you may have a file that shows up with a time of 1:40, even though that is clearly incorrect.  What is happening is that MPlayer reported the file with a length of 0, so QUI sets the length to 100 seconds, and then seeks to the percent instead of the actual time.  This means that the slider bar will be wrong and will most likely finish either long before the actual file does or not reach the end, but this will no longer cause QUI to go to the next file so it shouldn't be a problem. 


4. ***Editing defaults.conf + new options dialog***
This section will eventually go away completely because it's no longer necessary to edit defaults.conf directly.  All of the options can be taken care of in the options dialog.

A couple of notes about the options dialog: changing the MPlayer options will probably require a restart of QUI to take effect, unless you happen to kill MPlayer, and even then I'm not sure it would change.  The debug option does not require a restart anymore, and the volume doesn't either IIRC.  If it does let me know.  Also, the volume options only take effect if you have aumix installed so QUI can use it.

The deinterlace option may not work correctly if you're using your own -vf pp= options, so if you are turn it off and add your deinterlacing in the MPlayer options.


5. ***Button Themes***
You can now add images to the buttons in the QUI main window.  It's a quite simple process to do so - all you have to do is put the correctly named images in the ~/.qui/Buttons directory and ensure that ImageMagick is installed.  The easiest way to do this is to download one of the tar files available on qui4mplayer.sourceforge.net and untar it in the ~/.qui directory.  They will create the Buttons directory and put all of the files there with the correct names.

Obviously, if you want different images than the ones available, you can simply edit the ones in a tar file or create your own and name them appropriately.  The following are the filenames you need to use and the maximum size that they can be (the size of the button they will appear on).  They should be pretty self-explanatory, but I included short descriptions anyway:-)  Keep in mind that filenames in Linux are case-sensitive as well.

Background.png 400x175 - The background of the window.  All other buttons will get composited with this anywhere that they are transparent.  The existence of this image is what triggers QUI to use button images, so make sure it exists even if it's just a solid color.
DVD.png 50x30 - Add DVD chapter to playlist, no longer used
Fullscreen.png 40x40 - Put video playback into fullscreen
Loop.png 30x30 - Loop toggle button
Next.png 40x40 - Goto next file in playlist
Options.png 40x30 - Image on the options button
Pause.png 70x70 - Displayed on play button while actually playing
Playlist.png 40x40 - The button to show/hide the playlist
Play.png 60x60 - Displayed on play button while paused or stopped
Previous.png 40x40 - Goto previous file in playlist
Random.png 30x30 - Random toggle button
Stop.png 40x40 - Stop button
VCD.png 50x30 - Add VCD chapter to playlist, no longer used


6. ***Known Bugs***
Note that I removed a couple of entries here because the section was getting too long and they weren't really bugs in QUI, but bugs in other programs that affected QUI.

Variable bitrate MP3's - MPlayer doesn't like them much.  They'll play, but the time won't be reported correctly, so the time slider will most likely be off.  They should play all the way through now though.  About the only thing that will fix this is to reencode these files as plain MP3's.  Last I checked, even the newest version (not CVS) of MPlayer has trouble with these, and therefore so does QUI.

I've had problems with the MPlayer pre3 included in Mandrake 10 automatically playing videos fullscreen.  The 'f' key should get you out, but double-clicking WILL NOT because QUI did not put MPlayer into fullscreen mode, so it's not catching mouse events.  If you're still using a version of MPlayer this old, you really need to update anyway.

In KDE 3.2, the playlist window is not shown correctly when switching virtual desktops back to the one QUI is on.  I'm NOT fixing this because I'm sick of putting band-aids on bugs (or at the very least inconsistencies) in the way KDE 3.2 works, and in any case I don't think there's any way for me to fix it.  A signal just isn't getting sent to QUI when it gets reshown and I have no way of making it send properly.

It appears that if you minimize QUI while in fullscreen mode, it won't grab the mouse so you can't get the window back without using the 'f' key to manually get MPlayer out of fullscreen.  Not sure if this is fixable, in fact it doesn't appear to be as QT won't let a non-visible window grab the mouse, so I suspect this one is permanent.

7. ***Contact Information and GPL***
Please feel free to send bugreports to nemecb@gmail.com or post them on sourceforge.net/projects/qui4mplayer

I'm also open to suggestions for new features.  I can't guarantee that I'll be able to do everything you might want, but I'm willing to give it a shot.  I would love to get some feedback from somebody, so even if you hate QUI tell me why:-)

This program is released under the GPL.  See the COPYING file for more info.
