<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>KinoAMP User Guide</title></head>
<body bgcolor="#ffffff" text="#000000" link="#0000ff" vlink="#800080" alink="#ff0000">
<h1><center>KinoAMP User Guide</h1>
<h3>An MPEG Movie player</center></h3>
<p><b><i>v0.27 &nbsp; 10<sup>th</sup> April 2003</i></b>

<p>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.

<p>The player is based on Kino v0.3 from
<a href="http://www.eqrd.net">eQ R&D</a>
but is self-contained and does not require the original in order to work.

<h3>Contents</h3>
<ul>
<li><a href="#controls">Controls</a>
<li><a href="#multitask">Multitasking</a>
<li><a href="#panel">Control Panel</a>
<li><a href="#options">Options Setup</a>
<li><a href="#require">Requirements</a>
<li><a href="#formats">Supported Formats</a>
<li><a href="#install">Installation</a>
<li><a href="#tech">Technical Description</a>
<li><a href="#command">Command Line Options</a>
<li><a href="#probs">Known Problems</a>
<li><a href="#credits">Credits</a>
</ul>

<hr><!-- --------------------------------------------------- -->
<h2><a name="controls">Controls:</a></h2>

Whilst playing, the following controls are provided. See also the section on
<a href="#multitask">multitasking</a>. 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 <a href="#options">options setup</a>.

  <dl>
  <dt><b>Left Mouse Button</b> or <b>Return key:</b>
  <dd>Pause/Resume.<p>
  
  <dt><b>Centre Mouse Button</b> or <b>Q</b> or <b>Escape:</b>
  <dd>Exit.<p>
  
  <dt><b>Right Mouse Button</b> or <b>Space Bar:</b>
  <dd>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.<p>
  
  <dt><b>Number keys 0..9:</b>
  <dd>Audio channel select, see the <a href="#audio_chan">Audio channel</a>
  setup option.<p>
  
  <dt><b><a name="s_key">S:</a></b>
  <dd>Whilst paused, save the current frame as a sprite file,
  &lt;KinoSave$Dir&gt;.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.
  <br>
  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. 
  <p>
  <a name="saved">KinoSave$Dir</a> is set to "&lt;Kino$Dir&gt;.saved" in the
  !Boot file.
  <p>
   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.
  <p>

  <dt><b>+,- (plus and minus):</b>
  <dd>Adjusts the audio volume.<p>
  
  <dt><b>Cursor keys:</b> 
  <dd>Whilst paused, the <b>UP</b> and <b>DOWN</b> keys cycle through the
  following controls,
  <p>Brightness, Contrast, Colour, Volume
  <p>The <b>LEFT</b> and <b>RIGHT</b> keys adjust the value of the control.
  <p>An On Screen display is provided with the default value indicated.
  The player starts with the default settings.
  <p>When not paused, the <b>LEFT</b> and <b>RIGHT</b> keys perform
  <b>Rewind</b> and <b>Fast Forward</b> functions by jumping 5% of the file
  length. For small files the positioning can be very approximate.
  <br>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.<p>

  <dt><b><a name="zx_key">Z:</a></b>
  <dd>Increase Zoom setting.<p>
   
  <dt><b>X:</b>
  <dd>Decrease Zoom setting.<p>
  
  <dt><b>R:</b>
  <dd>Restart the film.<p>

  <dt><b>L:</b>
  <dd>Switches on and off continuous looping or repeating of the film.<p>
   
  <dt><b>A:</b>
  <dd>Switches on and off auto exit. This has no effect if looping is
  selected.<p> 

  <dt><b>M:</b>
  <dd>Mutes and restores the audio.<p>
      
  <dt><a name="F3"><b>F3:</b></a>
  <dd> 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.
      
  </dl>
  
<hr><!-- --------------------------------------------------- -->
<h2><a name="multitask">Multitasking:</a></h2>

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.
<br>The close button of the player window will exit the player.
<br>The adjust size icon will change the display size and aspect ratio.
<br>The <a href="#controls">keyboard controls</a> 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.
<p>
Dragging an MPEG file to the player window will stop the current playback and
start the new file playing.
<p>
A Drawfile banner (&lt;Kino$Dir&gt;.Banner) will be displayed for 1 second before
the film starts. If there is no file, this is skipped.


<h3><a name="panel">Control Panel:</a></h3>
  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,
  
  <dl>
  <dt><b>Play:</b>
  <dd>Resume normal playback.<p>
  
  <dt><b>Step:</b>
  <dd>Single frame advance.<p>
  
  <dt><b>Pause:</b>
  <dd>Stop playback at the current location.<p>
  
  <dt><b>Stop:</b>
  <dd>Stop playback and restart the film.<p>
  
  <dt><b>Rewind:</b>
  <dd>Go back 5% of the file length.<p>
  
  <dt><b>Fast forward:</b>
  <dd>Go forwards 5% of the file length.<p>
  
  <dt><b>Mute:</b>
  <dd>Mute/restore audio.
  </dl>
  
  Click anywhere on the timeline (progress bar) to jump to that location.

  <p>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.
  <br>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.

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

  <dl>
  <dt><b>File Info:</b>
  <dd>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 <a href="#iconbar">Icon bar menu</a>
  but is the currently playing file and not the last played file.<p>
   
  <dt><b>Zoom:</b>
  <dd>Select the zoom setting, as <a href="#zx_key">'Z' and 'X'</a>.<p>
   
  <dt><b>Lock aspect:</b>
  <dd>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.<p>
      
  <dt><b>Lock size:</b>
  <dd>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.<p>
      
  <dt><b>Pause:</b>
  <dd>Pause/Resume.<p>

  <dt><b>Restart:</b>
  <dd>Restarts the film.<p>
         
  <dt><b>Loop:</b>
  <dd>Switches on and off continuous looping or repeating of the film.<p>
   
  <dt><b>Auto exit:</b>
  <dd>Switches on and off auto exit. This has no effect if looping is
  selected.<p>
      
  <dt><b>Mute audio:</b>
  <dd>Mutes and restores the audio.<p>
      
  <dt><b>Controls:</b>
  <dd>Opens and closes the <a href="#panel">control panel.</a><p>

  <dt><b>Save choices:</b>
  <dd>Saves the current choices. See the notes for key <a href="#F3">F3</a>.<p>
         
  <dt><b>Save frame:</b>
  <dd>Similar to <a href="#s_key">'S'</a>, 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 <a href="#saved">'saved' directory</a>.
  Once a path is provided, by dragging or typing, it will be remembered for
  the duration of the currently playing file.
  </dl>

<hr><!-- --------------------------------------------------- -->
<h2><a name="options">Options Setup:</a></h2>

To change the players starting options, launch the !KinoAMP 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.

<h3>Audio Options:</h3>
  <dl>
  <dt><b>Play Soundtrack:</b>
  <dd>Enables the soundtrack.<p>
  
  <dt><b>Save Soundtrack:</b>
  <dd>Saves the soundtrack as an Audio MPEG file,
  &lt;KinoSave$Dir&gt;.Soundtrack<p>

  <dt><b>Re-synchronize:</b>
  <dd>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.<p>

  <dt><b><a name="audio_chan">Audio Channel:</a></b>
  <dd>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.
  </dl>
  
<h3>Video Options:</h3>
  <dl>
  <dt><b>Screen Mode:</b>
  <dd>These options select between using the desktop and a full screen
  mode.<p>
    <dl>
    <dt><b>Desktop:</b>
    <dd>Use the desktop for display.<p>
  
    <dt><b>Auto:</b>
    <dd>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.<p>
      <dl>
      <dt><b>Colours:</b>
      <dd>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.<p>

      <dt><b>Resolution:</b>
      <dd>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.
      </dl><p>
    
    <dt><b>Manual:</b>
    <dd>Manually select a screen mode for display with the following
    Colours and Resolution.<p>
      <dl>
      <dt><b>Colours:</b>
      <dd>Select the colour depth for full screen operation. Some
      combinations of colour/resolution may not be possible.
      <br>'16 million' provides the highest quality but is slowest.
      <br>'32 thousand' provides reasonable quality and speed.
      <br>'256 colours' provides lower quality but is fastest.<p>
    
      <dt><b>Resolution:</b>
      <dd>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.
      </dl>
    </dl>
    
  <dt><b>Zoom:</b>
  <dd>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.<p>

  <dt><b>All Frames:</b>
  <dd>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.<p>

  <dt><b>Monochrome:</b>
  <dd>This uses optimised greyscale drivers to display the video.
  These drivers do not support Brightness, Contrast and Colour control.<p>

  <dt><b>Dither:</b>
  <dd>Enables dithering on 256 and 32 thousand colour modes. This improves
  the display by increasing the number of perceived colours.

  </dl>

<h3>Desktop Options:</h3>
  <dl>
  <dt><b>Multitask:</b>
  <dd>Selects desktop multitasking operation.<p>
      
  <dt><b>Lock aspect ratio:</b>
  <dd>When multitasking, the height and width can be adjusted independently.
  Setting this option keeps the aspect ratio the same as the original
  picture.<p>
      
  <dt><b>Lock size to window:</b>
  <dd>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.<p>

  <dt><b>Control Panel:</b>
  <dd>When selected, the player will start with the
  <a href="#panel">control panel</a> open when multitasking.<p>
      
  <dt><b>Skin:</b>
  <dd>Select the <a href="#panel">control panel</a> skin from those
  available.
      
  </dl>
        
<h3>General Options:</h3>
  <dl>
  <dt><b>Auto exit:</b>
  <dd>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.<p>

  <dt><b>Continuous loop:</b>
  <dd>When selected, the film will restart when finished.

  </dl>    

<h3><a name="iconbar">Iconbar Menu:</a></h3>
  <dl>
  <dt><b>Choices:</b>
  <dd>Opens the configuration window. This has the same effect as
  clicking Select on the Iconbar Icon.<p>
      
  <dt><b>Saved:</b>
  <dd>This opens the directory where sprites and soundtracks are saved.
  Clicking Adjust on the Iconbar Icon has the same effect.<p>
      
  <dt><b>File Info:</b>
  <dd>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.<p>
         
  <dt><b>Reload:</b>
  <dd>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.<p>
      
  <dt><b>Help:</b>
  <dd>Opens this file.
  </dl>

<hr><!-- --------------------------------------------------- -->
<h2><a name="require">Requirements:</a></h2>

<a href="http://www.amplayer.org/">AMPlayer module</a> version 1.39 or later.
<br>SharedSound module version 0.59 or later.
<br><a href="http://www.iyonix.com/32bit/system.shtml">32 bit Shared C Library</a>
for pre RISCOS 5 machines.<p>

<hr><!-- --------------------------------------------------- -->
<h2><a name="formats">Supported formats:</a></h2>

MPEG 1/2 Program stream containing,
<ul>
  <li>MPEG 1/2 video stream on channel 0.
  <li>Any MPEG audio stream that AMPlayer can cope with on channels 0 to 9.
</ul>  
MPEG 1/2 Elementary video stream.
<p>
The Video decoder is <a href="http://libmpeg2.sourceforge.net/">libmpeg2</a>.
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.<p>

<hr><!-- --------------------------------------------------- -->
<h2><a name="install">Installation:</a></h2>

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.
<p>
If you want to keep the old one, rename it first or hide it away, so it
isn't 'seen' by the filer.
<p>
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.<p>

<hr><!-- --------------------------------------------------- -->
<h2><a name="tech">Technical:</a></h2>

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.
<p>
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.
<pre>
e.g.
   debug options = -d17
   debug options = -d62 2&gt;&lt;Kino$Dir&gt;.log
   debug options = -sp
etc.
</pre>
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.<p>

<hr><!-- --------------------------------------------------- -->
<h2><a name="command">Command line Options:</a></h2>

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 used
as part of another Application.

<dl> 
<dt><b>-@XX,YY</b>
<dd>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<p>
      
<dt><b>-a</b>
<dd>Save the soundtrack as the AMPEG file,
&lt;kinoSave$dir&gt;.SoundTrack The default is not to save the soundtrack.<p>

<dt><b>-bBB,CC,CC</b>
<dd>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<p>

<dt><b>-cN</b>
<dd>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.<p>

<dt><b>-dN</b>
<dd>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

<p><table border=1 align=center cellpadding=4>
<tr><th>Bit<th>Value<th>Function
<tr><td>0<td>1<td>display all frames (ignore timing constraints)
<tr><td>1<td>2<td>print demux time stamps.
<tr><td>2<td>4<td>print audio buffer stats.
<tr><td>3<td>8<td>print picture header stats.
<tr><td>4<td>16<td>print end of file summary.
<tr><td>5<td>32<td>print non fatal errors and some extra info.
<tr><td>6<td>64<td>print frame draw stats.
<tr><td>7<td>128<td>print seek stats.
</table>

<p>The Debug options are used for testing and can produce a <i>lot</i>
of output to the screen. If you're into this sort of thing, redirect output to a
file. e.g. -d62 2&gt;&lt;kino$dir&gt;.log To just display the end of file timing
stats on the screen use, -d16<p>

<dt><b>-f[choices file]</b>
<dd>Read options from [choices file]. eg. -f&lt;Kino$Dir&gt;.Choices<p>
    
<dt><b>-l</b>
<dd>Desktop multitasking options.
<table>
<tr><td><b>-la</b><td>Lock the aspect ratio. The default is unlocked.
<tr><td><b>-ls</b><td>Lock the size to the window. The default is unlocked.
</table><p>

<dt><b>-m</b>
<dd>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.<p>

<dt><b>-r</b>
<dd>Audio sync control. This will attempt to re-synchronize the audio
if it gets out of step. It is an option because it can make matters
worse if adjustments are made too often.<p>

<dt><b>-s</b>
<dd>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.
<table>
<tr><td><b>-se</b><td>Assume video stream.
<tr><td><b>-sp</b><td>Assume program stream.
</table><p>

<dt><b>-v</b>
<dd>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.<p>
    
<dt><b>-w</b>
<dd>Enables desktop multitasking, the default is to singletask.<p>
    
<dt><b>-xa</b>
<dd>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.<p>
    
<dt><b>-xNNNyNNNcNNN</b>
<dd>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

<p>Supports 256, 32k and 16m colour modes. It can only use modes that are defined in
your machine.<p>

<dt><b>-z</b>
<dd>Picture Zoom control.
<table>
<tr><td><b>-z05</b><td>50% magnification.
<tr><td><b>-z2</b>&nbsp;or&nbsp;<b>-z</b><td>200% magnification.
<tr><td><b>-z3</b><td>300% magnification.
<tr><td><b>-z4</b><td>400% magnification.
</table>
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%.<p>


<dt><b>--nodither</b>
<dd>Disable dithering for 256 and 32k colour modes. The default is to enable
dithering.<p>

<dt><b>--loop</b>
<dd>Continuously loop or repeat the film. The default is to not repeat.<p>

<dt><b>--ctrl</b>
<dd>When multitasking, display the control panel. The default is not to display
it.<p>

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

<dt><b>--noexit</b>
<dd>Stops the player from exiting at the end of a film. The default is to
exit.     
    
</dl>


<hr><!-- --------------------------------------------------- -->
<h2><a name="probs">Known Problems:</a></h2>

<br>Operation direct from CD is not good.


<hr><!-- --------------------------------------------------- -->
<h2><a name="credits">Credits:</a></h2>

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

<hr><!-- --------------------------------------------------- -->
<p><center><i>
<a href="mailto:peter@everett9981.freeserve.co.uk">P.Everett</a>
10<sup>th</sup> April 2003
<a href="http://www.everett9981.freeserve.co.uk/pete.htm">Website</a>
</i></center>
</body>
</html>

