                       KinoAMP v0.27
              --------------------------------

An MPEG Movie player.
  
This version of the Kino MPEG movie player uses the AMPlayer module
to decode and play the soundtrack. Once the !KinoAMP application has
been 'seen' by the filer, double click Select on an MPEG file to
start the player. The file must be filetyped BF8 (MPEG).
To view or change playing options, launch the !KinoAMP application.
It is not necessary to have the Setup Tool running to use the player.

The player is based on Kino v0.3 from eQ R&D (http://www.eqrd.net) but
is self-contained and does not require the original in order to work.


Controls:
---------
Whilst playing, the following controls are provided. See also the section
on multitasking. Changes made whilst playing will only affect the currently
playing file unless the choices are saved from the player. To alter the way
the player behaves for all files, use the Option setup.

Left Mouse Button or Return key:
   Pause/Resume.

Centre Mouse Button or Q or Escape:
   Exit.

Right Mouse Button or Space Bar:
   Frame advance, whilst paused. All frames are displayed when single
   stepping. This means that the sound may become slightly out of sync
   with the vision if many frames are stepped through.
  
Number keys 0..9:
   Audio channel select, see the Audio channel setup option below.
  
S: Whilst paused, saves the current frame as a sprite file,
   <KinoSave$Dir>.frameXXXXX
   where XXXXX is the frame number.
   This is a screen dump of the picture area, which means,
   The sprite will have the same magnification (zoom setting) and colour
   depth as the display.
   If the picture does not fit completely on the screen, only the
   visible part will be saved.
   
   When multitasking, the above rules do not apply and the sprite is
   always 100% magnification. If saving from the player menu, the filename
   is created from the frame number when the menu was opened. The sprite
   name is created from the frame number when the sprite is actually saved.
   These two will be different if the player was not paused before the menu
   was opened. 

   KinoSave$Dir is set to "<Kino$Dir>.saved" in the !Boot file.
   
   note. The frame number is the number of displayed frames since starting or
   restarting. It is not reset or recalculated after rewind or fast forward.

+,- (plus and minus):
   Adjusts the audio volume.
  
Cursor keys:
   Whilst paused, the UP and DOWN keys cycle through the following controls,
   
   Brightness, Contrast, Colour, Volume
   
   The LEFT and RIGHT keys adjust the value of the control.
   
   An On Screen display is provided with the default value indicated.
   
   When not paused, the LEFT and RIGHT keys perform Rewind and Fast Forward
   functions by jumping 5% of the file length. For small files the Fast
   forward and Rewind positioning can be very approximate.
   There is a delay after repositioning before the video playback starts. This
   is because although the sound can start immediately, the video must wait
   until the next 'key' frame is encountered.

Z: Increase Zoom setting.
   
X: Decrease Zoom setting.

R: Restart the film.
   
L: Switches on and off continuous looping or repeating of the film.

A: Switches on and off auto exit. This has no effect if looping is selected. 

M: Mutes and restores the audio.

F3: Saves the current choices. When the player is multitasking, the choices
   window will be updated if it is open. When not multitasking, to update the
   choices window after the player has finished use the reload option from the
   Icon bar menu.


Multitasking:
-------------
Desktop multitasking slows the player down by about 10%. Depending on what else is
running, at least a further 10% is lost to the operating system and other
applications. The speed of full screen and single task desktop modes are unaffected.
There are a few changes to the playing controls when multitasking to maintain
compatibility with other applications.

The close button of the player window will exit the player.
The adjust size icon will change the display size and aspect ratio.

The keyboard controls described in the previous section will only work if the
player window has the input focus. To gain the input focus, click select or adjust
within the player window. Adjust will gain the focus without pausing the player.

Dragging an MPEG file to the player window will stop the current playback and
start the new file playing.

A Drawfile banner (<Kino$Dir>.Banner) will be displayed for 1 second before
the film starts. If there is no file, this is skipped.


Control Panel: 
  A control panel containing basic playing controls is available and when opened
  attaches itself below the picture window. It can be opened and closed from the
  player menu.
  The control buttons are, from left to right,
  
  Play: Resume normal playback.
  
  Step: Single frame advance.
  
  Pause: Stop playback at the current location.
  
  Stop: Stop playback and restart the film.
  
  Rewind: Go back 5% of the file length.
  
  Fast forward: Go forwards 5% of the file length.
  
  Mute: Mute/restore audio.
  
  Click anywhere on the timeline (progress bar) to jump to that position.
  
  For small files the Fast forward and Rewind positioning can be very
  approximate and clicking to new position using the timeline can be more
  accurate.
  There is a delay after repositioning before the video playback starts. This
  is because although the sound can start immediately, the video must wait
  until the next 'key' frame is encountered.


Player Menu:
   Clicking Menu within the Player window will open the player menu. This
   provides the following facilities.

   File Info:
      Opens a window containing information on the currently playing file.
      If the window is already open this will update it. The information is
      similar to that obtained from the Icon bar menu but is the currently
      playing file and not the last played file.
   
   Zoom:
      Select the zoom setting, as 'Z' and 'X'.


   Lock aspect:
      When locked, the aspect ratio of the display is kept the same as the 
      original picture. When unlocked, the adjust size icon can be used to
      adjust the x and y scale factors independently.
      
   Lock size:
      When locked, the picture size always just fills the window. When unlocked,
      the picture is allowed to be larger but not smaller than the window.
      
   Pause:
      Pause/Resume.

   Restart:
      Restarts the film.
         
   Loop:
      Switches on and off continuous looping or repeating of the film.

   Auto exit:
      Switches on and off auto exit. This has no effect if looping is selected.
      
   Mute audio:
      Mutes and restores the audio.

   Controls:
      Opens and closes the control panel.
      
   Save choices:
      Saves the current choices. See the notes for key 'F3'.
         
   Save frame:
      Similar to 'S', but being a normal dialogue box, this allows the frame
      to be saved by dragging, and the name to be changed. The path defaults
      to the 'saved' directory. Once a path is provided, by dragging or typing,
      it will be remembered for the duration of the currently playing file.
      The size of the resulting sprite will always be 100% when multitasking.


Options Setup:
--------------
To change the playing options, launch the !Kino application which will
install itself on the Iconbar. Selecting the Icon will open a
configuration window from which the playing options can be setup.
These options are passed to the player when it starts playing a file.
This means that changes made when the player is multitasking will not take
effect until the next file is played.

Audio Options:

   Play Soundtrack:
      Enables the soundtrack.
  
   Save Soundtrack:
      Saves the soundtrack as an Audio MPEG file,
      <KinoSave$Dir>.Soundtrack
      
   Re-synchronize:
      This will attempt to re-synchronize the audio if it gets out
      of step. It can be disabled if adjustments are made too often
      and become noticeable.

   Audio Channel:
      Select the audio channel to play. This is only of use with clips
      that contain more than 1 audio channel. e.g. 2 languages.
      Most clips only contain channel 0.

Video Options:

   Screen Mode:
      These options select between using the desktop and a full screen
      mode.
      
      Desktop:
         Use the desktop for display.
  
      Auto:
         A full screen mode is automatically selected to give the largest
         display with as many colours as possible. Only modes with an aspect
         ratio between 6:5 and 3:2 are used. Zoom is fixed at 100% when the
         player starts, but can be altered whilst playing.
         
         Colours:
            When Auto mode is selected, the maximum colour depth can be
            specified using the Colours menu. This is a separate colour
            depth setting from the Manual setting.
            
         Resolution:
            When Auto mode is selected, the minimum screen size can be
            specified using the Resolutions menu. This is a separate
            resolution from the Manual setting.
    
      Manual:
         Manually select a screen mode for display with the following
         Colours and Resolution.

         Colours:
            Select the colour depth for full screen operation. Some
            combinations of colour/resolution may not be possible.
            '16 million' provides the highest quality but is slowest.
            '32 thousand' provides reasonable quality and speed.
            '256 colours' provides lower quality but is fastest.
    
         Resolution:
            Select the screen x,y resolution for full screen operation.
            The available screen resolutions will vary between machines.
            The visible aspect ratio of the picture may not be correct
            with non-square pixel modes. A resolution of 480 x 352 will
            suit most MPEG 1 clips.
      
   Zoom:
      Picture magnification. Options are 50% 100% 200% 300% 400%
      The higher the magnification, the slower the player and more frames
      may be skipped to keep time. There are separate settings for Desktop
      and Manual modes. For Auto screen mode, zoom is always started at
      100%, but can be altered whilst playing.

   All Frames:
      The player will drop or skip frames if it is running late. This
      option forces it to display all frames ignoring timing constraints.
      The sound may break up if not disabled.

   Monochrome:
      This uses optimised greyscale drivers to display the video.
      These drivers do not support Brightness, Contrast and Colour
      control.

   Dither:
      Enables dithering on 256 and 32 thousand colour modes. This improves
      the display by increasing the number of perceived colours.        

Desktop Options:

   Multitask:
      Selects desktop multitasking operation.
      
   Lock aspect ratio:
      When multitasking, the height and width can be adjusted independently.
      Setting this option keeps the aspect ratio the same as the original
      picture.
      
   Lock size to window:
      When multitasking, this option makes the picture always just fill the
      window. When not set, the picture is allowed to be larger but not smaller
      than the window.
      
   Control Panel:
      When selected, the player will start with the control panel open when
      multitasking.
      
   Skin:
      Select the control panel skin from those available.

General Options:

   Auto exit:
      When selected, the player will exit when the file has finished.
      When not selected, the player will stop at the end of the film.
      Play will resume from the begining. If the player is set to continuously
      loop, the auto exit option has no effect. When the player stops at the
      end of the film, the positioning controls, fast forward, rewind, and
      time bar will not work until play has resumed from the begining again.
      

   Continuous loop:
      When selected, the film will restart when finished.   
      
Iconbar Menu:

   Choices:
      Opens the configuration window. This has the same effect as
      clicking Select on the Iconbar Icon.
      
   Saved:
      This opens the directory where sprites and soundtracks are saved.
      Clicking Adjust on the Iconbar Icon has the same effect.

   File Info:
      Opens a window containing information on the last file played. If
      the window is already open this will update it. Information is only
      available after a file has been played.
         
   Reload:
      Selecting this will reload the Choices file and update the current
      options. It resets the options to the last save or 'OK'. Avoids
      having to quit and re-run if the Choices file has been edited by
      hand. e.g. when changing debug options.
      
   Help:
      Opens this file.


Requirements:
-------------
   AMPlayer module version 1.39 or later.
   SharedSound module version 0.59 or later.
   32 bit Shared C Library for pre RISCOS 5 machines.

Supported formats:
------------------

MPEG1/2 Program stream containing,
  MPEG1/2 video stream on channel 0.
  Any MPEG audio stream that AMPlayer can cope with on channels 0 to 9.
  
MPEG1/2 Elementary video stream.

The Video decoder is libmpeg2. The project homepage is at
 http://libmpeg2.sourceforge.net/
It should be able to decode all MPEG video streams that conform to certain
restrictions : "constrained parameters" for mpeg-1, and "main profile"
for mpeg-2.


Installation:
-------------
To install, de-archive (unzip) the application to a convenient place on
your Hard Drive. If you are updating a previous version, dragging the new
version over the old should be ok.

If you want to keep the old one, rename it first or hide it away, so it
isn't 'seen' by the filer.

To make sure the new version runs properly, either reboot the machine or
go inside the new version (shift double click Select) and double click
Select on the !Boot file to force the filer to 'see' the new version.


Technical:
---------- 
The player is a command line utility that is started when an MPEG file is
run. Playing options are passed to it on the command line together with
the MPEG filename. The actual command line is contained in the Obey file
RunKino. This file is produced by the Options Setup program when the OK
Icon is selected. Options Setup also produces a file called Choices which
contains the current setup. If debug or unusual options are required, a
special line must be added to the Choices file.

The line "debug options = " cannot be edited via the setup window. It has
to be added manually and should contain any options that are not handled
by the desktop setup program, including text output redirection if
required. This string is appended to the command line so any redirection
must come last.

e.g.
debug options = -d17
debug options = -d62 2><Kino$Dir>.log
debug options = -sp
etc.

This facility is for testing. To use, edit Choices by hand, then run
Options Setup and OK the selection. If Setup is already running, select
the 'Reload' option from the Iconbar menu, then OK. This will update the
RunKino file with current plus extra options. Except for 'all frames'
which is ignored, all other options can be setup as normal.
One comment line starting with a hash '#' will also be retained in
the Choices file, so you can comment out the debug line without
loosing it when the Choices file is updated by the Options Setup program.
 

Command line Options:
---------------------
This lists all command line options. They are only of use to those who wish
to manually edit the Choices or RunKino files or if the player is to be
launched from another application.

-@XX,YY In desktop mode, define the bottom left co-ordinates of the
    display in pixels relative to the bottom left of the screen.
    Adjustments will be made to make the picture fit completely on the
    screen. Without this switch, the default is a centered display.
    Both parameters must be given. i.e. -@400,300
      
-a  Save the soundtrack as the AMPEG file,
    <kinoSave$dir>.SoundTrack
    The default is not to save the soundtrack.
    
-bBB,CC,CC  Set the initial values for Brightness, Contrast, Colour. These
    have default values of 100 and can be set between 0 and 200. All 3
    values must be given. i.e. -b100,66,120

-cN Play audio channel N. where N is a number between 0 and 9.
    This is only of use with clips that contain more than 1 audio
    channel. e.g. 2 languages. The default is channel 0.

-dN Debug level N. This defaults to 0 (no debug). Obtain combinations by
    adding up the values (in decimal). The number can be entered in hexadecimal
    if preferred. i.e. -d0x7e

    bit value
    0    1  : display all frames (ignore timing constraints)
    1    2  : print demux time stamps.
    2    4  : print audio buffer stats.
    3    8  : print picture header stats.
    4   16  : print end of file stats.
    5   32  : print non fatal errors and some extra info.
    6   64  : print frame draw stats.
    7  128  : print seek stats.

    The Debug options are used for testing and can produce a /lot/ of
    output to the screen. If you're into this sort of thing, redirect
    output to a file. e.g.
    -d62 2><kino$dir>.log
    
-f[choices file]
    Read options from [choices file]. eg. -f<Kino$Dir>.Choices
    
-l  Desktop multitasking options.
    -la Lock the aspect ratio. The default is unlocked.
    -ls Lock the size to the window. The default is unlocked.

-m  Select the monochrome video drivers. These are slightly faster than
    the colour drivers and will also be selected whilst playing if the
    colour is turned right down and contrast and brightness are kept at
    their default values.

-r  Audio sync control. This will attempt to re-synchronise the audio
    if it gets out of step. It is an option because it can make matters
    worse if adjustments are made too often. 

-s  Select stream type. By default, the file is checked for being either
    an Elementary Video stream or a Program stream and the demultiplexer
    is selected as required. This option overrides the check and is only
    necessary if the file check fails.
    -se Assume video stream.
    -sp Assume program stream.

-v  Video only, the default is to play the audio.

    note. The combination -a -v is allowed and will not play the audio
          track but will save it to file.
          
-w  Enables desktop multitasking. The default is to singletask.
    
-xa Automatically select the full screen mode to give the largest
    display with as many colours as possible. Only modes with an aspect
    ratio between 6:5 and 3:2 are used. This option forces Zoom to start
    at 100%.
    The maximum colour depth can be specified following the -xa option.
    i.e. -xa32k or -xa256. The default is 16m which will be used if -xa
    is used without a colour modifier.
    
-xNNNyNNNcNNN  Select the screen display mode. By default the player
    uses the desktop. For 'Full Screen' or 'Big Mode' operation, specify
    the mode to use. e.g.
    -x480y352c16m
    Supports 256, 32k and 16m colour modes. It can only use modes that
    are defined in your machine.

-z  Picture Zoom control.
    -z05        50% magnification
    -z2 or -z  200% magnification
    -z3        300% magnification
    -z4        400% magnification
    Without this switch the magnification is 100%, actual size.
    This switch has no effect when -xa is specified and in this case the
    magnification will always start at 100%.

--nodither  Disable dithering for 256 and 32k colour modes. The default
    is to enable dithering.

--loop  Continuously repeat the film. The default is no looping.

--ctrl  When multitasking, display the control panel. The default is not to
    display it.

--skin,[skin directory]  Defines the control panel used when multitasking.
    e.g. --skin,Black
    The actual location is <Kino$Dir>.skins.[skin directory]
    The default is to use the Black skin.
    
--volNN  Sets the starting volume to NN, from 0 to 127. The default is to use
    the current AMPlayer setting.

--noexit Stops the player from exiting at the end of a film. The default is to
    exit.     


Known Problems:
---------------
 Operation direct from CD is not good.
   

Credits:
--------
For the video decoder, the libmpeg2 team.
For the original !Kino, eQ R&D.
For many additions, improvements, and optimisations,
   Andr Timmermans and Henrik Bjerregaard Pedersen.
For sound, the AMPlayer developers.
For help with 32 bit conversion, Peter Naulls.
For the TimerMod module, David Ruck.

 
10/04/03
P.Everett
email: peter@everett9981.freeserve.co.uk
web: http://www.everett9981.freeserve.co.uk/pete.htm

