home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Acorn User 7
/
AU_CD7.iso
/
_movies
/
_armovie
/
documents
/
join
< prev
next >
Wrap
Text File
|
1994-04-08
|
21KB
|
405 lines
HOW TO RUN JOIN
+++++++++++++++
Related Documents: ToRunDiff
AE7doc
Extract (Version 2.17, 18 Mar. 1994).
Author: CRose
Date: 08 April, 1994.
Version: 2.09
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 (2.09) & PREVIOUS VERSION (2.08):
--------------------------------------------------------------------
Building sound only ARMovies with format 2 adpcm sound, extra bytes of
state information weren't being added to even and odd max chunk sizes
in the header section of the movie. Unlikely that this would have
caused any problems but to be safe it's now correct.
OUTSTANDING:
-----------
===================================================================================
