rulesPlayer readme
-----------------------------------


Contents:

1. license
2. why
3. default key bindings
4. reseting to default settings
5. the console
6. some stuff explained
	6.1 default subtitle language (console sub_deflang)
	6.2 registering a file extension with the player (console registerext)
	6.3 config files
	6.4 key/mouse bindings note
	6.5 console and playlist size
	6.6 a tip for the compact mode
	6.7 events
7. compiling from source





================
1. license:
================

use without restrictions at your own risk


================
2. why:
================

media player classic is damn slow, bsplayer not much better
alshow doesn't support .srt subtitles
mpui is not very customizable and is ugly and not very fast...
vlc's subtitles are awful
mplayer rules, but without gui is useless


================
3. default key bindings:
================

playlist (buitin can not be changed):

delete selected items - del
play current item - enter
move selection up - alt+up
move selection down - alt+down
escape - close playlist


console (buitin can not be changed):

escape - close console


general (bindings):

1 - decrease brightness
2 - increase brightness
3 - decrease conrast
4 - increase conrast
5 - decrease saturation
6 - increase saturation
7 - decrease hue
8 - increase hue
9 - decrease volume
0 - increase volume
arrow down - step one frame
arrow left - seek back 5 seconds
arrow right - seek forward 5 seconds
ctrl+arrow left - seek back 60 seconds
ctrl+arrow right - seek forward 60 seconds
page up - seek back 600 seconds
page down - seek forward 600 seconds
ctrl+arrow up - increase playback speed
ctrl+arrow down - decrease playback speed
alt+arrow up - move subtitles up
alt+arrow down - move subtitles down
o - change osd mode
v - toggle subtitles visibility
s - take screenshot
f - toggle fullscreen mode
c - toggle compact mode
d - change frame drop mode
p - toggle playlist
j - search the playlist
t - toggle stick on top
` (tilde) - show console (escape to hide it)
escape - hide playlist or console (depending on which one has the focus)
spacebar - play/pause
enter - set window size to 100%
mouse1 - play/pause
mouse1 double - fullscreen
mouse3 - context menu
ctrl+mouse3 - OS shell menu
wheelup - audio volume +5%
wheeldown - audio volume -5%


================
4. reseting to default settings:
================

if you screwed up something or you installed new version of the player without uninstalling the old one you can the the following:
type in the console (without the quotes) "unsetall && unaliasall && unbindall && exec default.kfg && resetall"
note that this will erase all your key bindings, aliases, configurations. so if there is something you want to keep i suggest using autoexec.cfg or learn to like what i like (i.e. my defaults). also note that it is not always necessary to reset any configuration after installing a new version.


================
5. the console:
================

the console is the only way to configure rulesPlayer. some common commands and variables are put in the menus or controls but they all refer to console commands/variables. it is this way because: 1) i like quake 2) it is faster 3) it is flexible 4) i am too lazy to code interfaces

* tab is autocomplete (it will complete built-in commands, aliases and variables)
* help will display list of built-in commands
* commands are handled like on the command line
* "cmd1 && cmd2" (w/o quotes) will execute both cmd1 and cmd2
* $N, where N is number, is replaced with command argument N
* $N, where N is string, is replaced with variable named N
* $#N, where N is number, is replaced with string with id N
* $#N, where N is string or nothing, is replaced with #N
* $$ is replaced with $
* $% is replaced with nothing. it is meant for separator
* $& is replaced with &
* if you prefix a command with @ it will not be echoed to the console
* for some examples open config.kfg or default.kfg
* \" is replaced with "
* \\ is replaced with \
* \t is replaced with tab
* \n is replaced with new line


================
6. some stuff explained:
================

6.1 default subtitle language:
this is a feature used with the subtitle auto loading (the second can be disabled from the subtitles menu). type in the console "sub_deflang en,eng,jpn,de" to set default languages in order of preference. it work like this - if you have a movie named mymovie.avi and few subtitles in the same folder, say mymovie.jpn.sub and mymovie.de.sub, the both subtitles will be loaded automatically when you open the movie and jpn subtitle will be chosen automatically (because it is before de). it also works for built in subtitles.

6.2 registering a file extension with the player:
you can choose to register all supported video formats with rulesPlayer from the file menu (existing associations will be backed up so you can unregister later) or you can use the console to register specific extensions. Open the console and type "registerext .avi my description" 3', where 3 is number of the icon displayed in explorer. you can see the available icons in the images folder of your installation, the default one is number one (1_player.ico).

6.3 config files:
each line in the config files is interpreted as line in the console with one exception. there is support for multiline commands. if the line ends with \ (and not \\), the interpreter will continue reading lines until line without ending \ character is found or it reaches the end of the file. the \ character is skipped.
the configruation files must be in utf8 encoding.

6.4 key/mouse bindings note:
basically you can bind keys like that: bind ctrl+a "yell test", and when you pres ctrl+a you will see a message box saying "text". for more help about the bindings see default.kfg
you can bind mouse and keys with ctrl,alt and shift modifiers, but you can't bind mouse and keys together. this means that ctrl+a is valid binding, ctrl+mouse1 too, but ctrl+a+mouse1 will ignore the a key.

6.5 console and playlist size:
you can resize both the console and the playlist windows. there is no resize cursor, but just click and drag at the bottom/top border of the window...

6.6 a tip for the compact mode:
you can find something like this useful. type in the console: bind c "titlebar && compact && @wndsize 1"
the next time you press 'c' the titlebar of the window will be hidden and it will be resized after the movie.

6.7 events:
rulesPlayer supports simple events in the form of aliases. when some events occurs a command (alias) will be triggered if it is defined. the supported events are:
oninit - when the player starts
onexit - when the player exits
onrestart - when the movie is restarted (usually to change the arguments of mplayer). $1 is the path to the movie
onplay - when movie playback starts (and when the movie is restarted too). $1 is the path to the movie
onclose - when movie playback ends. $1 is the path to the movie
onafterplayback - when all movies in they playlist finished playback. if the $pl_autoadvance is 0 this will be triggered after current movie ends. if the playlist repeat is on this will never be triggered
example: alias onplay "yell \"now playing the movie $$1\""


================
7. compiling from source:
================

DMD 1.0 (http://www.digitalmars.com/d)
DWT (http://www.dsource.org/projects/dwt or find one that compiles with this version of DMD) in your import path
NSIS (http://nsis.sourceforge.net) for the setup