
                              HOW TO RUN JOIN
                              +++++++++++++++
  
  
                        Related Documents: ToRunDiff
                                           AE7doc
                                           Extract (Version 2.19, 29 Apr. 1994).

Author:    CRose
Date:      16 May, 1994.
Version:   3.07
File Name: join


                   
 
WHAT DOES JOIN DO? - takes the components of an ARMovie and joins them together
-----------------    to produce ARMovie files with or without video images 
                     and with or without sound.  It can also produce ARMovie
                     files with multiple sound tracks if video images are
                     required, and when building a movie it can compress sound
                     at 16 bits per sample down to 4 bits per sample (format 2,
                     adpcm).
  

THE SOURCE DATA - you need a directory containing the following:
---------------
  
*  a file called "Header"  (more info. further down).
*  a sprite.
*  Images: [optional - without this data the ARMovie file generated will 
                       be sound only and will contain only one sound track]
               
   an Images0 directory containing image files called 00, 01, 02, 03,
   and so on up to a maximum of 76. After this you need to create 
   another Images directory called Images1 and then carry on with 
   00,01,02, etc. again.

*  Keys data:  Same naming convention as above.  i.e. e.g. Keys0.00,
   Keys0.01, etc.

*  Sound data: sound can be read from an already existing ARMovie file
   or by default from data format files. 
   
      DATA FORMAT FILES:  the following files must exist in the source
                          directory:
                          
        For 8 bits per sample (exponential) - (line 13 in the header file):
        Need at least one sound track (obviously).
        
                          Sound       /* 1st soundtrack */
                          Sound2      /* 2nd soundtrack */
                          Sound3      /* and so on ...  */
                          Sound4      
                           etc.
                   
        For 16 bits per sample - (line 13 in header file):
        As above: 
                          Samples
                          Samples2
                          Samples3
                           etc.
                           
        For 4 bits per sample - (line 13 in header file):
        As above:                               
                          Adpcm
                          Adpcm2
                           etc.
                       
      ARMOVIE FILE: join must be supplied with the full path name
                    of this file on the command line.
      
      
THE HEADER FILE:
---------------
    
      The Header file used by Join must comply with the following format (examples
      further below), and it must be kept in the same directory as the sprite, 
      image, keys, and sound data (see section above - "The Source Data").  If
      more than one sound track is required then lines 10 to 13 will be slightly
      different.  This is explained under the heading "Multiple Sound Tracks" 
      further down. 
            
	String          ARMovie
	String          Movie name
	String          date and copyright details
	String          author and other details
	String          video compression format identifier     [1][0 -> no video]
	Decimal number  x size in pixels
	Decimal number  y size in pixels
	Decimal number  z pixel depth in bits [16 or 8]
	Decimal number  number of frames per second to project at
 	String          sound compression format identifier     [0 -> no sound]
	Decimal number  sound replay rate in Hz (or fractions of)
	Decimal number  number of sound channels recorded ("reversed" if l<->r)
	Decimal number  sound precision ("linear" if linear, "unsigned" if unsigned)
	Decimal number  number of frames in a chunk 

      The number of frames per chunk (last line above) must match the video data.
      This information can be found be looking at the header section of the ARMovie
      from which the images were extracted. 
              
        HEADER EXAMPLE (one sound track only):

	ARMovie
	The Concert
	(c) Notts University 1991
	Created by Notts University, digitised by Acorn Computers
	1
	160 pixels
	128 pixels
	16 bits per pixel 
	25 frames per second
	1
	12000 Hz samples
	1 channel
	8 bits per sample (exponential)
	50 frames per chunk            
        
        Multiple Sound Tracks
	---------------------

	The single video track can have an arbitrary number of sound tracks associated
	with it. Extra sound track data for each sound parameter follows the sound
	track marker "|" plus the sound track number. Different sound tracks can have
	completely different parameters - compression format, sample rate, number of
	channels, number of bits per sample. The first sound track is played by 
	default	and does not follow a |1 marker - thus the first additional sound 
	track has parameters following a |2 marker.

	HEADER EXAMPLE (multiple sound tracks):
	
	ARMovie
	The Concert
	(c) Notts University 1991
	Created by Notts University, digitised by Acorn Computers
	1
	160 pixels
	128 pixels
	16 bits per pixel 
	25 frames per second
	1                               |2   1                     |3  1
	12000 Hz samples                |2   16000                 |3  20000
	1 channel                       |2   2 channels            |3  2 channels
	8 bits per sample (exponential) |2   16 bits per sample    |3  4 bits (adpcm)
	50 frames per chunk            
                    	

	                    
THE COMMAND LINE   
----------------

        Parameters for running join on the command line are shown below,
        followed by specific examples.
        
        -help               : on-line help (limited in comparison with this text).
        
        -dest f             : set destination file name (default 'JoinOp').
        
        -index N            : select different Header, Images, Keys combination.
                              
        -nokeys             : prevent the key frames being written to the new
                              ARMovie generated by join.  (You can see whether 
                              or not an ARMovie has keys by looking at the end 
                              of the header section in the ARMovie).
        
        -size N             : set chunk alignment size to N.  Default is 2047 bytes.
                              (The smaller the value of N, the smaller the size of
                              the output file generated by join).  This is an
                              optimization parameter, the value of which depends
                              upon the media being used.   
        
        -source             : set name of source directory.
        
        -armovie n file/s   : name of ARMovie sound source file/s.  'n' is the 
                              number of files specified, for example, -armovie 3 
                              $.dir1.file1 $.dir1.file2 $.dir2.file3 (all on the 
                              same line). "file1" will provide the first sound 
                              track, "file2" will provide the second sound track, 
                              and "file3" will provide the third sound track. If
                              e.g. file1 provided both sound tracks 1 and 2 and 
                              file2 provided the third sound track, then
                              the -armovie parameter list would be -armovie 2
                              $.dir1.file1 $.dir1.file2 . n simply tells join how
                              many ARMovie sound source files you are about to
                              specify.  It is nothing to do with the number of 
                              sound tracks. Examples are included below.          
                              
                              
                              
EXAMPLES OF HOW TO RUN JOIN:
---------------------------

   Example 1:  join -help
   ---------    
               This will provide on-line help.  It will also tell you the version
               number and date of the program.  Obviously, this document provides
               more information than join -help does.
               
   Example 2:  join -source $.DataToJoin 
   ---------
               This will generate an ARMovie file using source data held in the
               directory $.DataToJoin (source data being the header, sprite,
               and so on as explained at the beginning of this document).  By
               default, the name of the new ARMovie file will be "JoinOp".  The
               information which you supply in the header determines whether or
               not the ARMovie file will have sound, whether or not it will have 
               image data, what the sound replay rate will be, and so on (see 
               Header sections above).  If line ten of your header is 0 then 
               join will not look for any sound data but if it is 1 then join 
               will expect to see one or more sound files in $.DataToJoin or it
               will expect you to specify one or more ARMovie sound source files
               (examples 4,5, and 7 below).
               (If you want more than one sound track do not forget to indicate
               this in your header - see sub heading "Multiple Sound Tracks"
               above).
               
   Example 3:  join -source $.DataToJoin -dest $.Movies.Elephants
   ---------   
               This will generate an ARMovie file called "Elephants" in the 
               directory called $.Movies, using source data held in the 
               directory $.DataToJoin.  Explanation is identical to example 2
               above with the exception that the name of the generated ARMovie
               file no longer defaults to "JoinOp".
               
   Example 4:  join -source $.DataToJoin -armovie 3 cdfs::replay_demo.$.movies.
   ---------   shuttle $.DataToJoin.Planes $.Movies.Elephants (all on one line).
   
               This will generate an ARMovie file called "JoinOp" using the source
               data held in $.DataToJoin.  The -armovie parameter instructs join to
               use sound from other ARMovie files rather than use sound from ordinary
               sound files.  ARMovie file/s acting as the sound source do not 
               necessarily have to live in the same directory as all the other source
               data, which is why you must specify full path names as shown in this
               example.  So this example will generate an ARMovie file with three
               sound tracks.  The first sound track will be extracted from cdfs::
               replay_demo.$.movies.shuttle, the second sound track will be 
               extracted from $.DataToJoin.Planes, and the third sound track will 
               be extracted from $.Movies.Elephants.  Your header file in $.DataTo
               Join must also indicate that there is to be three sound tracks (refer
               to the sub heading - "Multiple Sound Tracks" above).  You should look 
               at the header sections in your ARMovie sound source files to see 
               what the sound replay rates are and what the sound precision should 
               be for a particular sound track in your own header.  The number 3 
               after -armovie simply tells join that there are three sound file 
               parameters to read next.  It does not tell join anything about the 
               number of sound tracks.  Example 7 is useful at this point.
               
   Example 5:  join -source $.DataToJoin -armovie 2 cdfs::replay_demo.$.movies.horses
   ---------   cdfs::replay_demo.$.movies.shuttle
               
               This example is identical to example 4 above with the exception that
               it will generate an ARMovie file called "JoinOp" with two sound 
               tracks instead of three.  Hence 2 follows -armovie instead of the 
               previous number 3. You must also ensure that your header file in 
               $.DataToJoin complies with what you have specified on the command 
               line ie. in this example you are telling join to look for two sound 
               tracks so lines ten to thirteen of your header must indicate this 
               (refer to the sub heading - "Multiple Sound Tracks" above). You 
               should look at the header sections in your ARMovie sound source files 
               to see what the sound replay rates are and what the sound precision 
               should be for a particular sound track in your own header).
               
   Example 6:  join -source $.JoinData -index 3 -dest $.Movies.horses
   ---------
               This will generate an ARMovie file called $.Movies.horses using 
               source data found in the directory $.JoinData but the -index
               parameter tells join to select a different set of images and
               keys and a different header.  In this case, join will look for
               the directories $.JoinData.3Images0 and $.JoinData.3Keys0, and
               it will read from the header called $.JoinData.3Header .
               
   Example 7:  join -source $.JoinData -armovie 2 $.oldmovie $.Movies.horses
   ---------   
               You could do this if your header indicated that two sound tracks
               were required and one sound track was in $.oldmovie, the other in
               $.Movies.horses .  You would also use this join command if your
               header indicated that three sound tracks were required, two of
               the sound tracks being in $.oldmovie and the third one being in
               $.Movies.horses (or one track being in oldmovie, the other two
               being in horses).  The number 2 tells join how many ARMovie sound
               source files it must use.  It does not tell join anything about
               the number of sound tracks.  Similarly, if your header indicated
               that five sound tracks were required and $.oldmovie had five
               sound tracks, you would say join -source $.JoinData -armovie 1
               $.oldmovie .
               
   
   
 COMPRESSION DOWN TO 4 BITS PER SAMPLE:
 -------------------------------------           
    
  Join will allow you to compress 16 bits per sample sound down to 4 bits per
  sample (adpcm) format 2 when building an ARMovie.  To do this via the front
  end (!AREncode) you need to click on the compress box when building the
  ARMovie.  To do this without using !AREncode you join the movie components
  in the normal way but you make sure that the sound format in your header
  reads "2 adpcm" and that your header reads 16 bits per sample.  Join will
  then know to compress it down.  Compression does not apply when building
  multiple track ARMovies.
   
   
	    
OTHER POINTS WORTH MENTIONING / TROUBLESHOOTING:              
-----------------------------------------------                                

 Join will not read image data from anywhere but the image files in the source
 directory.  It cannot read image data from another ARMovie file.  If you do 
 want to use image files from another ARMovie file this can be done via use of the
 Extract program mentioned at the end of this document.                             

 If there are no image files, only one sound track will be generated so the header 
 information should only ask for 1 sound track and line 5 of the header should be 
 zero.
                                
 If ARMovie files are the sound source, lines 11 to 13 inclusive in header sections
 of these source files should correspond to the relevent track numbers in your own
 header (see sub-heading "Multiple Sound Tracks" above).
 
 If you use the -armovie parameter and the ARMovie file generated by join is 
 obviously garbage, play back the original ARMovie source file/s and check that 
 none of these are corrupt (e.g. if join was stopped by the user before completion 
 then the  generated ARMovie file will be corrupt and will therefore give problems 
 if it is later used by join again as a source for the sound data in  generating 
 another ARMovie file). 
 
 If you play back the newly generated ARMovie file and it freezes unexpectedly, make
 sure that you haven't attempted to run the movie with an invalid sound track number.
 e.g. if you played the ARMovie by typing $.JoinOp -tracks 3 on the command line and 
 JoinOp did not have a third sound track this would cause the movie to freeze at the 
 start.
                                                       
 If your new ARMovie runs out of sound on  a particular sound track and 
 you think it shouldn't have, check that the replay rate (line 11) in your header 
 is identical to the replay rate given in the ARMovie sound source file for that 
 particular track (this of course does not apply if you are not using the -armovie 
 parameter with join).  e.g. if you use an ARMovie file with a sound track created 
 at 12000 Hz and in your own header you indicate that this track is now to be 
 created at 13000 Hz, you will obviously run out of sound data if the files were 
 previously identical in size.  This does not matter as join will adjust the
 catalogue information resulting in a period of silence at the end.
                      
 You cannot output to the same ARMovie file that you are reading sound data from
 (this applies to use of the -armovie parameter). e.g. join -source $.DataToJoin 
 -dest $.runfile -armovie $.runfile is illegal.  Join will tell you that it is 
 unable to open $.runfile.
 
 If -armovie is given on the command line, join will not look for local Sound,
 Samples, or Adpcm files.  If you want to generate an Armovie using sound from
 an already existing Armovie AND from a Sound, Samples, or Adpcm file, you should
 first convert the Sound, Samples, or Adpcm file into an Armovie (using join)
 and then simply join the two together.
 
 If the files given after -armovie have multiple sound tracks, join will try to
 use all the tracks in accordance with your header (see example 7 above). For
 example, if your header indicates that the new Armovie will have six sound
 tracks, you could use three Armovie files as the sound source.  The first 
 Armovie might have three sound tracks, the second might have two, and the
 third would have only one, adding up to give a total of six tracks as specified
 in your header.  The total number of sound tracks in the source files must
 add up to the number of sound tracks you specify in your header.  Alternatively,
 for a six track header, you could use one Armovie with five sound tracks and
 another Armovie with only one sound track, or you could use two Armovies each
 with three sound tracks, and so on.
                                
 If join is terminated prematurely (e.g. user presses escape), an exception
 handler will ensure that any open files are closed.  For obvious reasons this
 only applies to files opened by join.                               
 
 There are two classes of error message.  Warning errors may be ignored 
 depending on context and whether or not a fatal error follows.  Fatal errors
 will actually stop the program at that point.  As mentioned above, any files
 left open by join will be closed by the exception handler.
 
 As well as taking in parameters from the command line, join will also look for
 parameters held in the environment variable join$ExtraArgs.  The split can 
 occur anywhere.  e.g. join -source $.DataToJoin -de may be entered on the command
 line, while st $.runit may be held in join$ExtraArgs.  join will simply join the
 two together to produce join -source $.DataTojoin -dest $.runit.
                                
 A separate program exists called "extract", which does the reverse of what "Join" 
 does.  "Extract" can take an ARMovie file and extract its header, sprite, keys (if 
 there are any), sound track/s, and images.  It is perfectly acceptable for this
 extracted data to be used by Join. (Extract is accompanied by written documentation
 which you should read if you have never used it before). If you want join to use 
 sound tracks from other ARMovie files join can do this directly (as mentioned many 
 times above) using the -armovie parameter.  But if you want join to use image data 
 from other ARMovie files you must use Extract to generate the image data which can
 then be used by join.                        
                                                           
                                                           
 DIFFERENCES BETWEEN CURRENT VERSION (3.07) & PREVIOUS VERSION (3.06):
 ----------------------------------------------------------------------------
 
 In the previous version it was a requirement that the string "frames per     
 second" be present along with the actual value in the header.  This          
 requirement no longer applies.                                               
 

                                                                               
 OUTSTANDING:
 -----------
 
 
                                                                               
===================================================================================