The contents of this distribution are all (C)1996 Acorn Computers Ltd, and
were written by Acorn RISC Technologies.

Acorn TimeCode
--------------

Multimedia hardware devices and software applications which can store,
manipulate and present time based data such as animations, video, audio, MIDI
and presentation timelines can be synchronised by the Acorn TimeCode
subsystem using industry standard MTC timecodes.  This provides the
application developer and end user with a seamless, easy to use interface
which eases the development of broadband multimedia presentations.

By using this software a RISC OS application or a hardware device attached to
a Risc PC can receive, generate or propagate a high resolution time stream. 
The direction and rate at which time flows across the timestream can be
controlled by the application or hardware device, and the timestream may be
routed from the application to other hardware or software clients.

The RISC OS computer system now becomes capable of synchronising with or
controlling a range of other devices which also have an awareness of time. 
Examples of these devices include MIDI sequencers, synthesisers, samplers and
multitrack tape decks, and CD-ROM drives and other computer systems.

Suitable interface hardware (such as a MIDI card) is used to allow reception
and transmission of the time stream from and to external sources.

The TimeCode subsystem provides support for full and quarter frame MTC, and
the 75fps frame addressing of Red Book audio CD.  In addition to these
default rates, frame rates from 1fps to 1800fps are supported. 

Timecode can be routed between applications with on-the-fly conversion of
differing frame rates.  It is possible for instance, to use the 75 fps timing
on an audio CD to produce MTC streams at 30 fps.  Here, the CD could act as
the timing source for the MIDI system.  Other time-aware devices such as
sequencers can follow the time stream from the CD and are therefore
synchronised with it.

TimeCode is currently being developed by Acorn Risc Technologies.

The software provided here is all pre-beta. We believe it is stable enough to
be used, but should be considered to be provided 'as is'. Reports of any
problems, bugs, or comments may be emailed to :

skynet-comment@art.acorn.co.uk

Wishlist items can be sent as plain text. Other reports should use the
FaultRept template in the Doc directory.

Requirements:

!Karaoke was written using Desktop C; and requires RISC_OSLib. The other
applications were written using Acorn C/C++ and require the various
toolbox modules rmensured in each !Run file plus TinyStubs.

The contents are:

Apps - Directory containing various TimeCode aware applications

Apps.!CD-Deck

     This application can control a CD-ROM drive. If used with a conventional
     audio CD it can read the timecode stream present on every audio (Red
     Book) CD and use it to update the TimeCode system's Internal Clock.
     
     Click Select on the icon bar icon to open the CD Player window.
     
     This window contains five buttons, which have these functions (reading
     from left to right):
     
     Decrement programmed track number
     Start CD playing from programmed track number
     Pause (Click on Pause again to release)
     Increment programmed track number
     Eject CD
     
     The display field to the right of the buttons shows the current time
     from the CD, in mm:ss:ff format. Hours are also displayed when
     necessary.
     
     The display field below the icons gives a status indication for the
     application and the CD-ROM transport.
     
Apps.!Karaoke

     This application can be used to display time-synchronised information.
     Unlike the other applications here it only works to second resolution;
     it was originally conceived for displaying the words to a song (using
     the timecode stored on an audio CD). However, it has many more
     applications than that - anything which involves time-synchronised
     information. In the example here we've used it to display some
     explanation about the uses of timecode. You'll see that it begins
     at 00:58:00:00 - this is a default starting time within the audio/video
     industry; though it's usually the start of two minutes of lead-in 
     rather than directly into programme information as here.
     
     The name of the file to use is given in the !Run file. The layout
     of the file indicates its original design - the first line of the
     file must contain a time and a [Album] tag. The content of this line
     is placed on the top line of the window. This is then followed by
     one or more [Track] lines which give the name for a given track;
     that is - what to display on line two of the display.
     
     One other special line is supported - [Quit] which can be used to
     make !Karaoke exit.
     
     All other lines will consist of a time stamp in hh mm ss followed
     by the text (if any) to display.
     
     The display consists of a number of lines in light blue, with the
     current line in dark blue.
     
     !Karaoke will follow timecode whereever it goes; automatically
     adjusting direction or taking account of jumps in time. Put simply
     it makes no assumptions about the direction or speed of time flow.
     This is an essential point to note about timecode; it cannot be
     guaranteed to be advancing forwards monotonically; indeed it could
     be going backwards or not moving at all - and if moving may well 
     not be doing so at real time.
     
Apps.!Scheduler

     This is basic example of an event scheduler built to operate on 
     timecode. It provides minimal editing facilities, and its display
     is not very graphical - it was written to demonstrate the potential
     of the concept rather than be the last word in showing it.
     
     The textual files inside the directory describe the file format for
     the event file. When it starts up it reads in the file
     !Scheduler.Default, and it saves the modified data as !Scheduler.Output
     when the application exits.
     
     You are advised to open the display window by clicking Select on the 
     icon bar icon - this improves the response.

     The default file included with this version is the schedule file used
     to animate the Acorn Conductor at Acorn World - timecode was drawn
     from an audio CD and the scheduler issued pollword changes to the
     application responsible for animating the Acorn Conductor.
     
Apps.!TimeShare

     This application is provided to allow control of the timecode
     system from the desktop environment. It allows clock and clock
     transmitter selection; provides control over the Internal Clock
     and provides diagnostic facilities such as a switchable display
     of the current timecode at a fps rate chosen by the user.

     Note that changes will not take effect until OK is clicked upon,
     and certain controls will have a transitional state where you
     cannot make further changes because a change is already pending
     (for example starting the Internal Clock).
     
Apps.!TimeSpeed

     This application provides a finer control over the Internal Clock.
     You may have as many copies of this application, !TimeShare or
     !Karaoke as you wish loaded and they will all stay in step with each
     other.
     
     You will notice this particularly with !TimeSpeed. The display field
     gives the rate that the Internal Clock is running at in comparison to
     real time. If you have more than one invocation of !TimeSpeed running
     you will see they all remain locked to one another.
     
     Most of the buttons are multi-purpose - reading from left to right
     they operate as follows:
     
     Fast Back:     Select: increase by x1 reverse
                    Adjust: decrease by x1 reverse (will drop to Rev. Play
                                                    at 1x reverse)
     Rev. Play:     Select: set to 1x reverse     
                    Adjust: reduce by 0.1x reverse
                    
     Stop:          Select: stop time flow, cancel pause mode
     
     Play:          as Rev. Play, but for forwards flow
     
     Fast Fwd:      as Fast Back, but for forwards flow
     
     Pause:         enter/leave Pause mode. When in Pause mode the
                    functions of the other buttons change:
                    
                    Fast Back: back by 1 second
                    Rev. Play: back by 1 frame
                    Stop: Exit Pause mode
                    Play: forward by 1 frame
                    Fast Fwd: forward by 1 second
                    
     The display field next to the buttons is used to display the current
     time flow, and the display field at the right of the window shows
     the current timecode value expressed in 25fps.
     
Doc - Useful documents

Doc.FaultRep

     Fill out this template and send it as email to
     skynet-comment@art.acorn.co.uk. Try to give as much information 
     in as impartial fashion as possible. If we can't reproduce a problem due
     to insufficient information we stand little chance of fixing it!

Futures - contains an indication about what we're thinking of for the future

Futures.Control

     This is an internal *draft* document giving a proposed wimp message
     interface to allow applications which handle resources which are
     timecode-aware to interface with a application/resource manager
     which would handle all the interlinking between all such applications
     and resources. Amongst other things it could remove the need for
     most every application to have a tape-transport style of its own
     which is subtly different to every other one.
     
MergeBoot - supplementary and replacement items for !Boot

     See the ReadMe file for additional information. RISC OS 3.10 users
     should manually update their !System to have the same structure
     as is represented within the !Boot.!Resources.!System here.

     Note that this is NOT a replacement !Boot for RISC OS 3.50 or
     RISC OS 3.60 users - it contains additional and updated items
     which must be merged correctly with your existing !Boot 
     structure.
     
TimeLib - a timecode interface library for C

     This directory contains the TimeLib library and its associated
     header file.
     
     This library provides a simple interface to all the SWIs which
     are provided by the TimeShare module. By supplying a library
     only those functions you need will be incorporated in the 
     object code. Note that wimplib is also needed.
     
*** IMPORTANT ***

This material is provided for personal use only. If you wish to
include the TimeShare module, or anything else here, in distributed
code you should contact ART for licensing terms. 
     
Although the software here is in an advanced state, we reserve the right
to make any changes to the software or its interfaces we deem necessary
or desirable. If you are considering building a product using this
technology you are advised to contact ART for advice beforehand.
     