               KinoAMP v0.59, an MPEG Movie player
              -------------------------------------
  
This version of the Kino MPEG movie player uses either the AMPlayer or
DiskSample modules to decode and play the audio streams. 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) or A8D (VOB).
To view or change playing options, launch the !KinoAMP application. It is not
necessary to have the Setup Tool running to use the player.

DVDs can be played by selecting the drive containing the DVD from KinoAmp's
iconbar menu. Non-protected DVDs can be played by dropping the VIDEO_TS directory
on the application's icon on the iconbar.

Limitations:
- Playing DVDs directly from a DVD drive requires version 2.42 of CDFSDriver
  (RISC OS 5.28) or a SCSI drive.
- DVDs will probably only be playable when the DVD drive is configured
  to a region matching the DVD's region. Use DVDRegion to alter your DVD
  drive's region setting if required.
- Uncommon features like counter mode, navigation timers, forced action at end
  of PCI validity are not implemented due to lack of DVDs to test.

The player is based on Kino v0.3 from eQ R&D but is self-contained and does not
require the original in order to work.

This program, and its source code, is released under the GNU General Public
License (GPL). A copy of the license should be in the Docs directory. The source
code is available from
  http://www.riscos-digitalcd.net/image/kinoamp/kinoamp.htm.

  --------------------------------------------------------------------------

Controls:
--------

Whilst playing, the following controls as well as those in the 'Multitasking'
section are provided. Changes made whilst playing will only affect the currently
playing film unless the choices are saved from the player. To alter the way
the player behaves for all films, refer to the 'Options Setup' section.

SELECT or Return key:

  Pauses/Resumes the replay unless a DVD menu is displayed in which case
  the action associated to the selected menu entry is executed.

MENU or Escape:

  Switch to the 'Multitasking' mode.

ADJUST or Space Bar:

  Frame by frame advance.

Double-click SELECT or F:

  Switch from the 'Multitasking' mode to the 'Full-Screen' mode with automatic
  selection of the screen mode and colour depth, or returns to the
  'Multitasking' mode.

Ins:

  Shows the root menu of a DVD.

Home:

  Shows the menu associated to the current title of a DVD (or the root menu
  when none exists).

Tab, Shift+Tab, Ctrl+Tab, Ctrl+Shift+Tab:

  Cycle respectively on programs & video streams, on audio streams,
  on subtitles, on angles.
  

Number keys 1...9:

  Audio stream selection, see the Audio stream setup option.

+, - (plus and minus):

  Adjusts the audio volume.

Cursor keys:

  Whilst the player is paused, the Up and Down keys cycle through the following
  parameters: Brightness, Contrast, Colour and Volume while the Left and Right
  keys adjust the value of the selected parameter.

  When not paused, the Left and Right keys perform Rewind and Fast Forward 
  functions by jumping 5% of the film length, while the Up and Down keys
  adjust the volume.

  DVD mode:

    When DVD menus are displayed the arrows are used to navigate the menu.

      Ctrl+Left        selects the prvious chapter.
      Ctrl+Right       selects the next chapter.

  Playlist mode:

    If a playlist is loaded, Ctrl+arrow selects another film from the list.

    In normal mode:
      Ctrl+Left        selects the previous film in the list.
      Ctrl+Shift+Left  selects a random film in the list.
      Ctrl+Right       selects the next film in the list.
      Ctrl+Shift+Right selects a random film in the list.
    In random mode:
      Ctrl+Left        selects a random film in the list.
      Ctrl+Shift+Left  selects the previous film in the list.
      Ctrl+Right       selects a random film in the list.
      Ctrl+Shift+Right selects the next film in the list.

F3:

  Saves the current choices. In 'Multitasking' mode, the configuration
  application will be updated automatically, in the other cases you will have to
  use the 'Reload' option from the from the Icon bar menu once you have regained
  control of the desktop.

F5:
  Switch to 'Multitasking' mode.

F6:
  Switch to 'Desktop' mode.

F7:
  Switch to 'Full-Screen' mode.

F8:
  Switch to 'Manual' mode.

Ctrl+A:

  Starts or stops saving the audio stream as a file named
  "<KinoSave$Dir>.Soundtrack".

A:

  Switches on and off the automatic exit from the player at the end of the
  replay. This option has no effect when 'Continuous loop' is selected.

C:

  Toggles between colour and monochrome rendering.

D, Shift+D:

  Loops on the deinterlacing methods (in reverse order if Shift is pressed).

L:

  Switches on and off continuous looping of the film/playlist.

M:

  Mutes and restores the audio.

P, Shift+P:

  Loops on resizing modes: Source, Pan & Scan, Stretch (in reverse order
  if Shift is pressed).

Ctrl+P, Ctrl+Shitf+P:

  Loops on the aspect ratios to resize to (in reverse order if Shift is pressed).

Q:

  Closes the player.

R:

  Restarts the film from the beginning.

S:

  Whilst the player is paused, saves the current frame as a sprite file named 
  "<KinoSave$Dir>.frameXXXXX" where XXXXX is the frame number. The directory
  can be opened with the 'Saved' iconbar menu command. The saved sprite
  will have the same colour depth as the display.
  
  If the picture is displayed with the scaler function, the saved sprite will
  have the same size as the original. On the other hand, if one of the fast
  display function is used, the sprite will be a dump of the picture with the
  same zoom as the display. Also, if the picture does not fit completely
  on the screen, only the visible part will be saved.

  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.

  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.

T:

  Toggles timing information on or off.

X, Ctrl+X:

  Decrease zoom setting (faster if Ctrl is used).

Z, Ctrl+Z:

  Increase zoom setting (faster if Ctrl is used).

  --------------------------------------------------------------------------

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 icon of the player window will close the application.

The adjust size icon will change the display size and aspect ratio.

The keyboard controls 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.

If a Drawfile banner is present (<Kino$Dir>.Banner), it will be displayed for 1
second before the film starts.


Control Panel:
-------------

A control panel containing the basic playing controls is available and will
attach itself below the player window when opened. It can be opened and closed
from the player menu. The panel can be moved away from the player window by
dragging its background. It will snap back to the player window if brought near
it. The control buttons are, from left to right:

Play:

  Resumes replay of a paused film or restarts from the beginning a stopped film.

Step:

  Single frame advance.

Pause:

  Pauses playback at the current location.

Stop:

  Stops playback and moves back to the start the film. Once stopped, the
  positioning controls (fast forward, rewind, and progress bar) will not work
  until the film is restarted again.

Rewind:

  Go back 5% of the film length.

Fast forward:

  Go forwards 5% of the film length.

Previous:

  DVD mode:

    SELECT selects the previous chapter.
    ADJUST selects the next chapter.

  Playlist mode:

    If a playlist is loaded, selects another film from the list.

    In normal mode:
      SELECT selects the previous film in the list.
      ADJUST selects a random film in the list.
    In random mode:
      SELECT selects a random film in the list.
      ADJUST selects the previous film in the list.

Next:

  DVD mode:

    SELECT selects the next chapter.
    ADJUST selects the previous chapter.

  Playlist mode:

    If a playlist is loaded, selects another film in the list.

    In normal mode:
      SELECT selects the next film in the list.
      ADJUST selects a random film in the list.
    In random mode:
      SELECT selects a random film in the list.
      ADJUST selects the next film in the list.

Select film:

  If a playlist is loaded, click to choose a film from the list.

Mute:

  Mute/restore audio.


Click anywhere on the progress bar to jump to that location.

For small films the Fast forward and Rewind positioning can be very approximate.
Clicking to new position using the timeline can be more accurate.


Player Menu:
-----------

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

Film -> Info:

  Opens a window containing information on the currently playing film. If the
  window is already open, its content will be updated. The information is
  similar to that obtained from the icon bar menu but for the currently
  playing film instead of the last played film.

Film -> Save choices:

  Saves the current choices. See the notes for key F3.

Film -> 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
  "<KinoSave$Dir>" directory. This path can be opened with the 'Saved' iconbar
  menu command. Once a path is provided, by dragging or typing, it will be
  remembered for the duration of the currently playing film.

Streams -> Program -> :

  Lists the programs present in the file. Choose from the list the program
  you wish to view.

Streams -> Audio -> :

  Lists the audio streams present for the current program.
  Choose from the list the stream you wish to listen to.

Streams -> Subtitle -> :

  Lists the subtitles present for the current program.
  Choose from the list the subtile you wish to view.

Streams -> Video -> :

  Lists the video streams present for the current program.
  Choose from the list the stream you wish to view.

Control -> Zoom:

  Lists the some selectable zoom settings.

Control -> Full-Screen:

  Switches to a full-screen single-tasking playback mode. The screen resolution,
  colour dept and other settings of this mode are independant from the
  multitasking mode to allow an optimised playback.

Control -> Pause:

  Pauses/Resumes the playback.

Control -> Mute:

  Mutes and restores the audio.

Control -> Restart:

  Restarts the film from the beginning.

Control -> Continuous loop:

  When selected, the film or playlist will be repeated indefinitely till the
  user stops the playback.

  When not selected, the player will stop the playback when the end of the film
  or playlist is reached.

Control -> Auto exit:

  When selected this option causes the application to be closed automatically
  when the playback is completed.

  When not selected, the player will just remain open waiting for the user to
  restart the playback from the beginning of the film or playlist.

  This option has no effect when the 'Continuous loop' option is active.

Control -> Control panel:

  Opens or closes the control panel.

Control -> Scroll bars:

  When selected, the player will have visible scroll bars and an adjust size
  icon. In the other case, their functions will be emulated in a thin invisible
  strip along the bottom and right edges of the window.

Image -> Monochrome:

  When selected, pictures are rendered in monochrome, which is faster
  than colour rendering.

Image -> Lock aspect ratio:

  Used during picture resizing ('Lock size to window' option) to determine
  whether to adjust the height and width of the stretched picture
  independently or to keep the same width/height ratio as the original picture.

Image -> Non-square pixels:

  When the previous option is active, adjust the height of the picture according
  to the pixel height/width aspect ratio defined in the source. In other words,
  we adjust the picture size when the sources uses non-square pixels.

Image -> Lock size to window:

  This option makes the picture always just fill the window (multi-tasking
  mode). When not set, the picture is allowed to be larger but not smaller than
  the window. This option takes into account the 'Lock aspect ratio' option.

Image -> Deinterlace:

  Lists methods to limit the comb effect in images of interlaced videos.

  Method:      Displays:
  None         Both fields as is.
  Blend        Field A as is, field B blended with field A.
  Blend (x2)   Display rate is doubled.
               Field A as is, field B blended with field B of previous image.
               Field A blended with field A of previous image, field B as is.
  Fields (x2)  Display rate is doubled.
               Field A at double height.
               Field B at double height.
               Image resolution is deteriorated but free of comb effects.

Image -> Resize mode:

  Lists methods to alter the aspect of the image.

  Source       Keep orignal aspect of the image.
  Pan & Scan   Cut out parts of the image to fit the aspect ratio specified
               in "Image -> Resize to".
  Stretch      Stretches the image to fit the aspect ratio specified
               in "Image -> Resize to".

Image -> Resize to:

  Used to specify the aspect ratio which the image must fit when using
  Pan & Scan or Stretch resizing modes. When "Monitor" is selected,
  the aspect ratio used will be the aspect ratio of the monitor as defined
  in the "Picture Options".
    
Playlist -> Select:

  Allows to choose a film from the list.

Playlist -> Next:

  Selects the next film from the list.

Playlist -> Previous:

  Selects the previous film from the list.

Playlist -> Random:

  Forces the films in the list will be played (once) in a random order.

Playlist -> Close:

  Play will stop after the currently playing film ends.

  --------------------------------------------------------------------------

Options Setup:
-------------

To change the playing defaults, launch the !KinoAMP application which will
install itself on the icon bar. Clicking SELECT on the icon bar 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 film but will have no
effect on films currently playing.


Main Options:
= - = - = - =

Replay:
- - - -

Mode:

  This option allows to choose one of several available replay modes. Each mode
  can be configured individually to optimise its use (see below).

  Multitasking:

    Plays in multitasking mode in a window.

  Desktop:

    Plays in single-tasking mode on the desktop.

  Full-Screen:

    For each film played, the player will automatically choose an appropriate
    full screen mode to maximize the size of the picture on screen, with as many
    colours as possible. Only modes with an aspect ratio between 6:5 and 16:9
    are used.

  Manual:

    Plays in single-tasking mode in a full-screen mode where the colour depth
    and resolution is fixed by the user.

Auto exit:

  When selected this option causes the application to be closed automatically
  when the playback is completed.

  When not selected, the player will just remain open waiting for the user to
  restart the playback from the beginning of the film or playlist.

  This option has no effect when the 'Continuous loop' option is active.

Continuous loop:

  When selected, the film or playlist will be repeated indefinitely till the
  user stops the playback.

  When not selected, the player will stop the playback when the end of the film
  or playlist is reached.

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

Playlist:
- - - - -

Random play:

  Forces films in the playlist to will be played in random order.

Hardware acceleration:
- - - - - - - - - - -

Use IntelDMA:

  The Iyonix uses a graphic card, located on a PCI port, with its own memory.
  Writing to that memory is thus relatively slow but can be accelerated
  but transfering memory blocks through the DMA channels. The IntelDMA module
  can proceed to such DMA transfers for pictures rendered as is (zoom at 100%,
  square pixels).

Use Geminus:

  The Geminus module available on the Iyonix and A9 Home uses the hardware
  of the machines to accelerate the system's image rendering interfaces.
  When the module is detected, KinoAmp will use the system's interfaces instead
  of its own image rendering routines.

Use VideoOverlay:

  The VideoOverlay module available on many RISC OS 5 machines (OS 5.25 or later,
  preferably with a ROM dated from 15-Aug-18 or later and the corresponding
  HardDisc4 disc image) uses the hardware of the machines to accelerate image
  scaling and colour space conversion.

  The display is faster, independant of the number of colors used by the main
  screen but it may affect the display of other windows that are supposed to be
  on top of the player's window and may be subject to hardware limitations.

  Not while multitasking:

    Prevents the use of overlays while multitasking so that windows and menus
    on top of the player's window are displayed correctly.

Picture Options:
= - = - = - = -

Width/Height:
- - - - - - -

Lock aspect ratio:

  Used by picture resizing operations to decide whether to adjust the height and
  width of the stretched picture independently or to keep the width/heigh ratio
  of the original picture.

  This option is ignored in single-tasking modes by the fast display routines
  (zoom is limited to 50%, 100%, 200%, 300% and 400%).

Non-square pixels:

  When the previous option is active, adjust the height of the picture according
  to the pixel height/width aspect ratio defined in the source. In other words,
  we adjust the picture size when the sources uses non-square pixels.

Deinterlace:

  Lists methods to limit the comb effect in images of interlaced videos.

  Method:      Displays:
  None         Both fields as is.
  Blend        Field A as is, field B blended with field A.
  Blend (x2)   Display rate is doubled.
               Field A as is, field B blended with field B of previous image.
               Field A blended with field A of previous image, field B as is.
  Fields (x2)  Display rate is doubled.
               Field A at double height.
               Field B at double height.
               Image resolution is deteriorated but free of comb effects.

Resize:

  Lists methods to alter the aspect of the image.

  Source       Keep orignal aspect of the image.
  Pan & Scan   Cut out parts of the image to fit the aspect ratio specified
               in "Image -> Resize to".
  Stretch      Stretches the image to fit the aspect ratio specified
               in "Image -> Resize to".

Resize to:

  Used to specify the aspect ratio which the image must fit when using
  Pan & Scan or Stretch resizing modes. When "Monitor" is selected,
  the aspect ratio used will be the aspect ratio defined below.

Monitor aspect:

  Defines the aspect ratio of the monitor.


Colours:
- - - -

Use default values:

  This option forces the use of default brightness, contrast and colour levels
  instead of customized values.

Brightness:

  Use the left/right arrows or click directly in the slider to alter the initial
  brightness level of the displayed pictures.

Contrast:

  Use the left/right arrows or click directly in the slider to alter the initial
  contrast level of the displayed pictures.

Colour:

  Use the left/right arrows or click directly in the slider to alter the initial
  colour saturation level of the displayed pictures.


Audio / DVD Options:
= - = - = - = - = - 

Audio
- - -

Play audio stream:

  When selected, the player will attempt to play the audio stream should the
  film contain one.

  When not selected, the player will make no attempt to play audio streams. It
  will not be possible for you to unmute the sound during playback.

Player:

  Either the AMPlayer or DiskSample modules can be used for decoding and playing
  audio streams. AMPlayer can however only decode MPEG 1/2 audio, and so
  DiskSample will be used for all the other audio formats.

Save audio stream:

  Saves the audio stream as a file named "<KinoSave$Dir>.Soundtrack".number.
  The directory can be opened with the 'Saved' iconbar menu command.

Synchronize:

  This option will attempt to synchronize audio and video whilst playing. It can
  be disabled if adjustments are made too often and become noticeable.

Autoselect stream:

  The Player will select the first audio stream encountered.

Audio stream:

  Selects the audio stream to play. This is only of use with clips that contain
  more than 1 audio stream, e.g. multilingual films. Most clips only contain
  stream 1.

Volume:

  Use the left/right arrows or click directly in the slider to alter the volume
  at which to play audio streams.

DVD
- -

Language:

  Prefered language code (2 letters) like en, fr, nl, de, ...

Window Options:
= - = - = - = -

Multiple Windows:

  Allow more than one player window.

Scroll bars:

  When selected, the player window will have visible scroll bars and an adjust
  size icon, otherwise their functions will be emulated in a thin invisible
  strip along the bottom and right edges of the window.

Control Panel:

  When selected, the player will start with the control panel open when
  multi-tasking.

Skin:

  Allows to choose a control panel skin from the list.

Modes Options:
= - = - = - =

These options can be set individually for each replay mode.

Common options:
- - - - - - - -

Fit to screen:

  When not multi-tasking, stretches the picture to the size of the whole screen
  by taking into account then 'Width/Height' options.

  When the fast display routines are used, zoom is limited to 50%, 100%, 200%,
  300% and 400% and the value with the rendering which is the closest
  to the screen dimensions will be used.
  
Zoom:

  Picture magnification. Options are 50%, 100%, 200%, 300% and 400%. The higher
  the magnification, the slower the player and the more frames may be skipped to
  respect the timing.

Scaler:

  Routine used to display pictures stretched to any given of size.

  * The 'Internal' routine is the internal routine used by default (faster in
    256 colours/greys modes).
  * The 'System' routine use OS_SpriteOp. On machine using a graphic
    acceleration card, this routine could well be much faster then
    the 'Internal' one.
  * The 'Linear' routine performs a linear interpolation on points
    on the same line.
  * The 'Bilinear' routine performs a linear interpolation both on lines
    and columns.

  In single-tasking modes, for performance reasons on old machines,
  fast display routines at 50%, 100%, 200%, 300% and 400% can be used
  instead by not enforcing the use of the scaler. Note that these routines
  ignore the 'non-square pixels' option.

Force use of Scaler:

  Allows to scale pictures to any given size in a single-tasking display mode.

Monochrome:

  This option uses optimized drivers without colour processing. These drivers
  do not support control of brightness, contrast or colour saturation.

  Given that even a display in 16 million colours doesn't provide more gray
  levels than a 256 colours display with a palette of only gray levels, use
  the last one as picture quality will be the same but rendering will be
  much faster.

  For the Multitasking and Desktop modes, choose the '256 greys' option from
  the Display Manager. For the other modes, choose a colour depth to 256,
  the player will automatically select a greyscale palette.

BGR -> RGB:

  This option allows to invert the usual colour encoding. This allows
  to use graphic cards which uses the inverted encoding on versions of RISCOS
  older than 5.21, which do not signal this inversion.

Dither:

  This option uses, when available, display drivers with dithering. This
  improves the display by increasing the number of perceived colours.

Options of mode Multitasking:
- - - - - - - - - - - - - - -

Lock size to window:

  This option makes the picture always just fill the window (multi-tasking
  mode). When not set, the picture is allowed to be larger but not smaller than
  the window. This option takes into account the Lock aspect ratio option.

Options of mode Full-Screen:
- - - - - - - - - - - - - -

Colours:

  Sets the maximum colour depth of the mode that will be automatically selected.

  '16 million' provides the highest quality but is slowest.
  '32 thousand' provides reasonable quality and speed.
  '64 thousand' provides reasonable quality and speed.
  '256 colours' provides lower quality but is fastest, especially when combined
  with the monochrome option.

Resolution:

  Sets the minimal screen width and height of the mode that will be
  automatically selected. 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.

Options of mode Manual:
- - - - - - - - - - - -

Colours:

  Sets the colour depth to use. Some combinations of colour depth/resolution
  may not be possible.

  '16 million' provides the highest quality but is slowest.
  '32 thousand' provides reasonable quality and speed.
  '64 thousand' provides reasonable quality and speed.
  '256 colours' provides lower quality but is fastest, especially when combined
  with the monochrome option.

Resolution:

  Sets the screen width and height resolution to use. 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.

  --------------------------------------------------------------------------

Icon bar Menu:
-------------

DVDs -> :

  Lists the available CDFS drives. Select a drive to play the DVD present
  in that drive.

Choices:

  Opens the configuration window. Clicking SELECT on the application icon bar
  icon has the same effect.

Saved:

  This opens the directory where sprites and soundtracks are saved. Clicking
  ADJUST on the application icon bar icon has the same effect.

Film Info:

  Opens a window containing information on the last film played. If the window
  is already open its content will be refreshed. Information is only available
  after a film has been played.

Playlist:

  This opens and clears the Playlist creation window.

Reload:

  Reloads the Choices file and resets the options to the last saved
  configuration. Avoids having to quit and re-run the application if the Choices
  file has been modified by the player.

Help:

  Opens this file.

  --------------------------------------------------------------------------

Playlists:
---------

A playlist is simply a text file containing a list of filenames. It can be
created by choosing 'Playlist' from the icon bar menu, or by using a text
editor.

The Playlist window allows playlists to be created by dragging files and
directories to the drop box within the window. When at least one file has been
added, the text playlist file can be saved in the usual way. If no save path is
given, the playlist will be saved to the default "<KinoSave$Dir>" directory
which can be opened by clicking ADJUST on the icon bar icon.

This is a very simple file creation facility and does not provide editing
facilities. After a playlist has been created, it can be edited using any text
editor. Comments and blank lines can be added if required, see below for file
format details.

If using a text editor, the full pathname of each film to insert must be given. 
This can be done easily using !Zap by shift dragging the file into a text edit
window. A few rules must be followed:

  * The first 8 characters of the first line must be 'Playlist', the rest of
    line is ignored.
  * Comment lines starting with '#' are ignored.
  * Blank lines containing just a line end are ignored.
  * The playlist can be named anything and can be saved anywhere.
  * There is no limit to the number of files.
  * The filetype should be Text.

e.g.
Playlist 20/8/2003

# Trailers
ADFS::HardDisc4.$.Clips.Trailers.Bond-007.Trailer2
ADFS::HardDisc4.$.Clips.Trailers.Lord-Rings.TwoTowers.Trailer 

# Music
ADFS::HardDisc4.$.Clips.Music.Offspring.WantYouBad
ADFS::HardDisc4.$.Clips.Music.Leader


To start a Playlist drag it to the icon bar icon or to a player window. Only one
playlist can be open in a player window, so dragging to the player window will
close an open playlist in that window. The file will be ignored if it doesn't
start with the word Playlist. When playing, the Ctrl-left and Ctrl-right cursor
keys will move through the list. Additionally, when multi-tasking, the menu can
be used to select a film from the list or to close the playlist.

If an MPEG file is dragged to the player window whilst playing a playlist, the
playlist will be temporarily halted while the new file is played. When the file
has ended the playlist will resume from the next file in the list.

If a directory containing MPEG files is dragged to the player window or to the
icon bar icon, a temporary playlist will be created replacing any current
playlist.

  --------------------------------------------------------------------------

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

  * MPEG 1/2 Program stream (MPEG-PES) containing,
    * an MPEG 1/2 video stream,
    * zero or more audio streams (MPEG/AC3/PCM).

  * MPEG 1/2 Elementary video stream (MPEG-ES).

  * MPEG 1/2 Transport stream (MPEG-TS) containing,
    * one or more programs,
    * zero or one MPEG 1/2 video stream associated to each program,
    * zero or more audio streams (MPEG/AC3/PCM) associated to each program.

The video decoder is based on libmpeg2 (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.

From version 0.29 the 'saved' directory and choices file have been moved from
!KinoAMP to the Choices area. If you have updated by dragging the new version
over the old one, the original choices file and 'saved' directory will not be
harmed but will no longer be used.

From version 0.29 there is no requirement to install the newer 32 bit
libraries machines running RISC OS 3.x 4.x.

The application will work with either 26 or 32 bit libraries.

  --------------------------------------------------------------------------

Hardware, speed versus quality:
------------------------------

Generally speeking the speed and image quality is influenced by:

Multitasking vs Full-Screen
- - - - - - - - - - - - - -

Full-screen mode use (when enough video memory is available) triple buffering
and syncs the video to the monitor to ensure a flicker/tearing free display
(at least if the video is rendered fast enough). Speed wise on one hand you
loose time in waiting for the monitor's sync, on the other hand you don't
loose time switching to other tasks.

Screen mode selection
- - - - - - - - - - -

The number of colours, aka the number of bytes used to encode a pixel's
colour dictates the rendering speed 256 > 4K = 32K = 64K > 16M.
If video rendering is too slow choose a screen mode with less colors.

If you must drop to 256 colours, it is best to use a 256 grey palette
in desktop modes and select the monochrome option (in full-screen mode this
automatically sets a grey palette but mainly it tells the video decoder
to skip decoding of chroma information).

Zoom and scaler
- - - - - - - -

A large zoom will slow down the rendering of the image but the impact is
greater when using scalers like 'Linear' or 'Bilinear'.

The fastest rendering mode is in full-screen when no scaler is forced.
Zoom will then be limited to 50%, 100%, 200%, 300% and 400% using fast
specialised routines. Next comes the forced use of scalers like 'Internal'
and 'System' and finally the slow 'Linear' and 'Bilinear' scalers.

Deinterlacing
- - - - - - -

Deinterlacing will only be used on interlaced videos. As a post-processing
it obviously slows down the rendering, especially if you use (x2) modes which
doubles the display rate of the video.

Hardware accelerated graphics
- - - - - -  - - - - - - - - 

With the trend for RISC OS on new machines to integrate the capabilities of the
graphic hardware cards to accelerate the system's image rendering interfaces,
KinoAMP allows you to configure each display mode to replace the internal scaler
by a system scaler which makes use of the system's image rendering interfaces.
The 'Force use of scaler' option is also provided to use this scaler in place
of the fast display routines used in single-tasking display modes.

Note:
The Geminus module available on the Iyonix and A9 Home uses the hardware
of the machines to accelerate the system's image rendering interfaces.
When the module is detected, KinoAmp will use the system's interfaces instead
of its own image rendering routines.


Behaviour on different machines and known issues
------------------------------------------------

Risc PC
- - - -

A StrongARM based Risc PC is at best able to display VideoCD like videos at
a reasonable frame rate if you use the fastest options and reduce the zoom
or number of colours.

A9Home
- - - 

At the moment KinoAMP will use the standard low resolution (1cs)
OS_ReadMonotonicTime API since the high resolution timer provided by
the TimerMod module doesn't work (The module doesn't find the HAL API
of the Iyonix so it attempts to directly access the IOC Timer1 hardware
and crashes as it is not present on the A9Home).
  
Iyonix
- - - 

The Iyonix uses a graphic card, located on a PCI port, with its own memory.
Writing to that memory is thus relatively slow but can be accelerated
but transfering memory blocks through the DMA channels. The IntelDMA module
can proceed to such DMA transfers for pictures rendered as is (zoom at 100%,
square pixels).

To use it you have to ensure that the IntelDMA module is loaded
by starting the !IntelDMA application (see 'Additional Requirements').

Raspberry Pi (without overlays)
- - - - - - - - - - - - - - - -

On the Raspberry Pi 3 with a USB harddisk, a DVD like video can be rendered
in 'Fit to screen' mode with scaler 'Internal' to 1920x1080 in 16M at about
30fps. With 'Linear' or 'Bilinear' scalers, you will have to seriously reduce
screen size or zoom.

This is why, in full-screen mode with 'Fit to screen option' selected and when
module AnyMode is present, KinoAmp will switch to a resolution corresponding to
the final non-zoomed image size. The scaler thus just scales the original image
to its 'non-square pixels' corrected size and the Raspberry's graphic processor
scales the image to the monitor's resolution.

Note that with recent ROMs (13 Oct 2016 and later ?), for AnyMode to work, the
system must be told not to handle mode changes but work at the resolution set
in 'config.txt' like older ROMs. For that you must create within the
!BootLoaderpartition a 'cmdline.txt' file containing
the line 'disable_mode_changes'.

Deinterlacing in 'Blend' mode is ok speed wise but 'Blend (x2)' is really too
much even when using the AnyMode trick.

Overlays on recent machines
- - - - - - - - - - - - - -

Overlays are supported on many RISC OS 5 machines (OS 5.25 or later,
preferably with a ROM dated from 15-Aug-18 or later).

Different kind of machines may be subject to different limitations
(like the 2048 x 2048 limit on the Raspberry Pi) or implementations issues.
If you encounter problems, consult the following forum:
https://www.riscosopen.org/forum/forums/3/topics/11504

Supported overlay types by decreasing order of preference:
  YV16, Plane 0 is 8bpp Y, Plane 1 Cb, Plane 2 Cr, 2x1 sub-sampled
  UYVY, 32bpp words of Y1.Cr.Y0.Cb, 2x1 sub-sampled
  YUY2, 32bpp words of Cr.Y1.Cb.Y0, 2x1 sub-sampled
  YV12, Plane 0 is 8bpp Y, Plane 1 Cb, Plane 2 Cr, 2x2 sub-sampled
  NV12, Plane 0 is 8bpp Y, Plane 1 is 16bpp Cr.Cb, 2x2 sub-sampled
  NV21, Plane 0 is 8bpp Y, Plane 1 is 16bpp Cb.Cr, 2x2 sub-sampled
  16M, 64K, 32K or 4K colors BGR or RGB, with alpha or transparency channel

  --------------------------------------------------------------------------

Additional Requirements:
-----------------------

To use AMPlayer as audio codec, the following modules are required:

  SharedSound module version 0.24 or later.
    http://www.espmusic.co.uk/acorn.htm

  AMPlayer module version 1.36 or later.
    http://www.amplayer.org/

To use DiskSample as audio codec, the following module is required:

  DiskSample module version 0.33 or later.
    http://www.riscos-digitalcd.net/digitalcd/modules/disksample.htm

To use Thomas Milius accelerated display on the Iyonix, the following
application/module is required:

  IntelDMA module version 0.01 or later.
    http://www.thomas-milius.homepage.t-online.de/Download/Freeware/inteldma.zip


  --------------------------------------------------------------------------

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.
Options Setup produces a file called Choices when the OK Icon is selected, which
contains the current setup. The normal command line contains a single option to
make the player read the choices file directly. If debug or unusual options are
required, these must be manually added to the command line in the RunKino file.
An example is provided in the RunKino file.

  --------------------------------------------------------------------------

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

-f[choices file]

  Read options from [choices file]. e.g. -f<KinoChoices$Dir>.Choices.

General options
- - - - - - - -

--noexit

  Stops the player from exiting by itself. The default is to exit when playing
  ends.

--loop

  Continuous loop.

Audio options
- - - - - - -

-v

  Video only. The default is to play the audio.

-a

  Save audio stream.

-r

  Synchronize audio and video.

-cN

  Play audio stream N, where N is a number between 1 and 9. The default is
  stream 1.

--volNN

  Sets the starting volume to NN, from 0 to 127. The default is 127.

Windows options
- - - - - - - -

-ls

  Lock size to window

--noscroll

  The player window will not have scroll bars or an adjust size icon.
  The default is to have them.

--ctrl

  When multi-tasking, 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.

Video options
- - - - - - -

-w

  Multitask.

-la

  Lock aspect ratio.

-m

  Monochrome.

--nodither

  Disables dithering.

-@XX,YY

  In desktop mode, define the bottom left coordinates of the display in pixels
  relative to the bottom left corner of the screen. Adjustments will be made
  to make the picture fit completely on the screen. Without this switch, the
  default is a centred display. Both parameters must be given. i.e. -@400,300.

-bBB,CC,CC

  Set the initial values for Brightness, Contrast and 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.

-xa

  Automatically selects 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 16:9
  are used. This option forces Zoom to start at 100%. The maximum colour depth
  can be specified following the -xa option. i.e. -xa64k, -xa32k or -xa256.
  The default is 16m which will be used if -xa is used without a colour
  modifier.

-xNNNyNNNcNNN

  Selects the screen display mode. By default the player uses the desktop. For
  full screen operation, specify the mode to use. e.g. -x480y352c16m.

  Supports 256, 32k, 64k 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%.

Other options
- - - - - - -

--noerrors

  Do not report errors.
  Useful for running a test playlist including broken/unsuported files.

-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(hex)  Function
   0      1        Display all frames, and this as fast as possible,
                   disregarding the delay between each frame.
   1      2        Log subtitle codec stats.
   2      4        Log audio codec stats.
   3      8        Log video codec picture header stats.
   4     10        Log an end of film summary.
   5     20        Log non fatal errors and some extra info.
   6     40        Log frame drawing stats.
   7     80        Log seek stats.
   8    100        Log buffer/stack stats.
   9    200        Log subtitle packets pushed on stack.
  10    400        Log audio packets pushed on stack.
  11    800        Log video packets pushed on stack.
  12   1000        Log demuxer stats.
  13   2000        Log subtitle packets pulled from stack for decoding.
  14   4000        Log audio packets pulled from stack for decoding.
  15   8000        Log video packets pulled from stack for decoding.
  16  10000        Log replay stats.
  17  20000        Log navigation 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.

  To just display the end of film timing stats on the screen use, -d16.

-p[playlist file]

  Loads the file. If recognized as a playlist, start playing the list.

-s

  Selects MPEG stream type. By default, an MPEG film is checked for being either
  an Elementary Video stream or a Program stream and the appropriate demuxer is
  selected. This option overrides the check and is only to be used when this one
  fails.

  -se  Assume MPEG elementary video stream.
  -sp  Assume MPEG program stream.

  --------------------------------------------------------------------------

Known Problems:
--------------

AMPlayer crashes sometimes when KinoAMP plays films containing corrupted sound
packets. Saving the sound into a file and playing it with AMPlayer causes no
problem so it just seems to be limited to the AMPlayer streaming interface.

  --------------------------------------------------------------------------

Credits:
-------

For the original MPEG video decoder, the libmpeg2 team.
For the original !Kino, eQ R&D.
For many additions, improvements, and optimizations, André Timmermans and Henrik
Bjerregaard Pedersen.
For sound, the AMPlayer developers, and André Timmermans.
For help with 32 bit conversion, Peter Naulls.
For the TimerMod module, David Ruck.
For the French version, Jérôme Mathevet.
For the Iyonix optimizations, Thomas Milius.

  --------------------------------------------------------------------------

17th May 2024.

A. Timmermans
  mailto:fa044826@skynet.be

Website
  http://www.riscos-digitalcd.net/image/kinoamp/kinoamp.htm
