Readme for NiftyPlayer
version 0.0.2
(c) 2001, mmu_man, revol@free.fr

Intro
NiftyPlayer, also known as nplay, is a little media player I wrote from sample source code app from Be (mplay)

I really wanted to be able to watch DivX ;-) movies under BeOs, and since MediaPlayer didn't support RGB32 overlay on my machine it was dropping 60% of the frames, and also VideoPro wes going at half-peed, I had no luck.

So I tried mplay, a sample source-code app from Be, and found it was a bit better, so I decidec to improve it.

It should supports all the types of movies (and sounds also like MP3s) the media kit can handle.

Licence and disclaimer

mplay was under Be's sample source code licence (provided here for reference).

I'd like to release nplay under the Gnu GPL licence, but since I don't know for now if I can use it I'll stick to mplay's licence for now.

I should not be responsible for any damage to your hardware / and software, ... (as usual)

magic overlay code contains some definitions/equations from some places I found on the Net:
http://www.nevrax.org/docs/doxygen/nel/jccolor_c-source.html
http://www.eng2.uconn.edu/~zhangl/convert.htm
I didn't check the licences, since 1) I only few definition lines 2) it is available on the Internet I don't see the point in it.

DivX ;-) is a trademark of <whatever the owner is> (who is he by the way ?)
BeOS is a trademark of Be Inc. ( http://www.be.com/ )
All other trademarks are of their respective owner...
Windows is a trial-mark of Micro$oft Corp ( http://www.microsith.com/ ).

(Who said writing disclaimers wasn't funny ?)

Thanks

I'd like to thank :

	* M and many others on beshare.bentonrea.com for alpha-testing
	* BGA on beshare for:
		- his queryoverlay.cpp, though it was 10 minutes too late (I did the same by hand recompiling the prog for every colorspace :^) ),
		- pointing me to an horrible bug in the Renderer selecting code (wasn't Dispose()ing the old renderer before trying another one),
		- fixing the RGB32 to RGB16 code (I forgot about endianness)
	* Be Inc for the BeOS and the little mplay program which proved useful :)
	* The authors of StampTV ( http://bebits.com/app/907 ) (for the little code to disable the screensaver)
	* OpenTracker ( http://www.opentracker.org/ ) for the always-on-top code (though I could have find it elsewhere)

User manual

Should be pretty straight-forward.

The easiest way to open a file is to drop it on the nplay icon.
Note that it doesn't support drag'n'drop in the player window for now.
You can open more than one movie at once if you drag a group of files on the icon. You can also give it the paths on the command line.

To pause the movie, either click on the play/pause button, or press the space bar.

Note that no codecs are included here, so if you want to watch DivX for ex you need to download the codecs ( from BeBits: http://bebits.com/app/1402 ).

# Hardware overlay

NPlay now supports a new overlay mode called "magic overlay". Since many of you don't have RGB32 overlay on their video card and the DivX ;-) codec only supports this colorspace, I tried to code a new renderer that uses the YCbCr422 overlay that is supported by many more cards (it seems) and converts the RGB32 output from the DivX ;-) codex to it. Though it takes twice the CPU power of the standard overlay (to do the convertion), since it's done before the card scales it in hardware the CPU usage doesn't vary from 100% to full-screen mode (on the oposite drawbitmap uses a bit less CPU in 100% but crawls in full-screen). If your card doesn't supports RGB32 overlay but does for YCbCr422 then openning a DivX ;-) movie will automatically fall down to magic overlay.

The hardware overlay support has some issues :
	* If your video card is like mine you will need to move the window to find the good position (I really should take care of the overlay restrictions, but I didn't have a look at it)
	* If you want to know which type of overlay your card supports, run nplay from the command line with a movie, you will see which ones it asks the codec for support.
	* Anyway, the DivX codec seems to only support the B_RGB32 colorspace (MediaPlayer only tries B_YCbCr422 for overlay, so it won't use it with DivX) (see magic overlay above)
	* The standard mpeg codec supports B_YCbCr422 (only ?)
	* The replacement mpeg codec from Carlos Hasan ( http://bebits.com/app/2338 ) does support B_RGB32 overlay (B_YCbCr422 also, but when I tried to use it I got wrong and faded colors).

# The keyboard control

The current shortcuts are as follows:

SPACE pauses/restarts the media
UP arrow ups the volume a bit
DOWN arrow lowers it

and some more keys (CL-Amp users will be used to them) :

X plays the movies (starts, not necessarily from the beginning)
C pauses
V stops and rewinds

# The Media Bar

The Button serves as a play/pause button (hitting space bar also works)
The sliders allows you to see the current time in the media.
The little speaker is the volume control.
If it is only grey shaded and clicking has no effect, it tells the media has no sound
If it is crossed then it means that the sound has been muted (by setting the volume to 0; there is no separate mute setting for now).
It it is colorful, then the media has sound ans then volume is greater than 0.
Clicking on it will bring the volume slider.

# The menu

Just right-click on the picture to open it.

	File
Only Quit works for now...

	View
You can make the window always-on-top here (note that as a side effect it becomes active in all workspaces).
You can scale the video here, and switch to full-screen (also by zooming the window. to exit from full screen, use the menu either or just left click on the picture)
Note that thanks to a little code from stampTV the screen saver wont launch when in full-screen., so you don't have to disable it yourself.
Note also that depending on how good your overlay support is you will need several attempts to switch fullscreen to have a correct image (at least it does it with my ati rage pro video card). 

	Draw
Here you can change the drawing method used. Though it crashes sometimes, you can try and change the method on the fly.

overlay uses the video card hardware overlay do draw so the CPU is not involved (the card displays it itself), so you have more CPU available to decode the movie.
Since the player first tries to use this mode, another mode is checked either :
- another app or window already uses the overlay (you can only use one at a time),
- your card doesn't support hardware overlay at all,
- the codec used didn't find a colorspace that your card supports as overlay.

magic overlay is a tweak for those who don't have RGB32 overlay suppotr and still want to use overlay to watch DivX ;-) full-screen. (see above).

double buffered is a draw bitmap variation which has an intermediate bitmap buffer so the codec ca decode in it while the app_server draws the picture from the other bitmap.

draw bitmap uses the app_server to draw the picture.

direct window is an experimental mode use it at you own risk (as for the hole proggy, see the disclaimer :p) It draws directly to the framebuffer (implementation is very raw and there is no clipping, so pay attention ,and _do_not_ touch the screen lower and upper edge with the window, don't know if it can damage your card, but I won't try if I were you)

	TimeRef
Here you can change the time reference the video is asserted to. in most cases it is the audio track, or the system time if no audio. changing to video goes at the maximum speed your CPU can decode the video. (only here for completeness)

	Setup
This menu includes openning the player preferences (currently unimplemented), and opening the control panel for the video and audio codecs. (doesn't seem a lot of codecs has control panel support)

	Hacks
Here you can enable various hacks (still under development) :
DivX ,-) seek is a hack that provides you the ability to seek into DivX without the audio getting restarted from the beginning.
DivX ,-) audio sync is a hack that tries to improve audio/video sync (does not seem to work currently, if it does somehing usefull to you, please let me know).


	About
Just to say hello :-)

Performances

It seems they aren't bad. I can only say that for my hardware (K6 II 350), I find them quite acceptable.
Talking about DivX, I cannot watch correctly some movies I can watch under Windows, but they use 100% CPU under windows (though they don't seem to drop many frames), and you know that the divx codec for BeOS is a hack around the Windows one, so there is some processing power wasted in the interaction layer between the Be media API and the windows DLLs.

Some movies I watched nearing perfect (sometimes they get hashed when there are lots of motion) :
The Enforcer (Jet Li) (526M, 640x320, 23fps, DivX ;-) Audio, 16bits-st, 44.1 kHz, 1h45)
Romeo Must Die (Jet Li) (685M, 640x304, 23fps, DivX ;-) Audio, 16 bits-st, 44.1 kHz, 1h52)


Sphere (678M, 640x272, 25fps, DivX ;-) Audio, 16 bits-st, 48 kHz, 2h09):
	(with previous version: both audio and video highly cut (0.2s of good sound+video, 0.2 locked, ...) but I was always at 100% CPU (I also suspect my IDE controler to be lazy-it's only an UDMA))
	now it plays pretty well, only the audio still has cuts and goes twice the normal speed (but it's the decoder fault, the mp3 decoder in the media kit beta that shows in some places makes it work perfectly, I hope Be would be able to release it...)

Highlander 4 (200+150 M, 352x240, 20fps, DivX ;-) Audio, 16 bits-st, 48 kHz, 55'+41'):
	same as for Sphere, it nearly works (perfectly with the beta decoder)

Watching the datas, it seems obvious that the divx audio decoders doesn't work correctly with 48 kHz sampled audio.

Crouching Tiger, Hidden Dragon (801M, 640x512, 29fps, Unknown audio codec (353 could not handle), 2h00, chinese version with subtitles):
	With this file I don't have audio even in media player, though under Windows it tells it's nothing more than DivX ;-) Audio...
	But the video plays nice, and it seeks well also. (Btw I love this film :-) )

Other movies I tried, but didn't go far in time:

Austin Powers (671M, 720x480, 23fps, DivX audio, 16 bits-st, 48 kHz, 1h30)
	same as for Sphere, lots of cuts 
	still is not in sync in this version and I don't know why... (but media player also losts sync)

Small files:
405_DivX (7M, 356x240, 30fps, 3'03):
	had problems with the earlier version (because of no audio track), but now the vide is asserted to system time, and works.

DaveMatthews_Crash_PocketPC.avi (OpenDivX, 320x240, 11fps, DivX audio, 16bits-mono, 48 kHz):
	The audio plays fine, but the video doesn't show (only a green box with a black/white blinking line at the bottom).
Tool_Sober.avi (OpenDivX, 640x480, 29fps, DivX audio, 16bits-st, 48 kHz, 2'09):
	I don't know how MediaPlayer can play it in sync... (drops 50% of frames btw, but nplay couldn't seek it... duno how) any idea ? 
	btw it seems it only has 3 keyframes (1 at the beginning, one in the middle and one maybe at the end), so seeking in it is very strange :)

Without overlay: It seems the perfs are just a bit under MediaPlayer's ones.
DirectWindow mode is untested, but it seems it uses more CPU than DrawBitmap(), without the advantages.

Known bugs

	* sometimes chaning the drawing mode on the fly crashes (seems this version crashes less often)
	* sometimes the menu won't work (when using the open pane mainly) FIXED in this version (I think so, if not let me know)
	* Seeking in DivX ;-) takes a lot of time, since the decoder doesn't support it, so we have to run through the stream to the destination point (wait ~2 minute / 15 minutes of movie)
	* sometimes when it looses the sync it goes 'mad' (freeze, if you don't have enough CPU power). This version should make it happen less.
	* maybe I found a bug in the media kit beta update... (seems the divx audio codec doesn't report the track time correctly (reports the playing time rather than the track time, so when you seek you loose sync; the regular one always return 0x8000000000000000, so I use another method)
	* the slider seems to disapear sometimes, then draw uncorrectly

Todo / Wishlist

Things I want to do, and wishes on beshare, and if there's something I missed just tell me :)

	* use stampTV plugins :)
	* better manage audio buffers (one real-time pool should suffice, not one per window :-) )
	* try to find why somtimes the media_server need to be restarted not to have trashy sound
	* enhance the toolbar with more controls (stop, ...)
	* subtitle support (wanted twice on beshare)
	* skin support ?
	* playlist support ?
