home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
World of A1200
/
World_Of_A1200.iso
/
datafiles
/
text
/
c_manual
/
devices
/
narratordevice
/
narratordevice.doc
< prev
next >
Wrap
Text File
|
1995-02-27
|
43KB
|
1,215 lines
5 NARRATOR DEVICE
5.1 INTRODUCTION
The Amiga can not only produce crisp clear four channel stereo
sound, it can even speak. The operating system was designed so
this unique feature easily and efficiently can be used. With
very little effort you can let the Amiga read information.
Sadly very few programs use this extremely useful feature.
Although artificial speech sounds a bit monotone and
uninteresting it can be used in many situations to transfer
information from the computer to the user.
Imagine if the user has to check hundreds of different numbers
on the screen when the original numbers are on papers. This
very boring and slow task can be made much easier if the Amiga
automatically reads the values and the user only has to look at
the paper.
5.2 ARTIFICIAL SPEECH
Imitating human speech is a very difficult process. Even the
most sophisticated super computers can still not manage to
produce all the different intonations and sounds as a real
human voice can. The Amiga's synthesized speech mechanism is
not at all as powerful as what these super computers have, but
compared to other home computers, it is outstanding.
Producing artificial speech on the Amiga can be divided into
two steps:
1. First we have to convert the text we want to be read into
phonetical text. Phonetical text is written as the words
should sound and not as how the words are spelled.
If you open a dictionary you will notice that there exist
a specification on how every word should be pronounced.
The special symbols used to tell you how the word should
sound are usually called "the phonetic symbols", and are
defined in the beginning or end of the dictionary. The
pronunciation of all words can be constructed with help
of these symbols.
On the Amiga we use the same technique. However, since the
real phonetical symbols are very strange and can not be
typed with a normal keyboard, we use a special
"computerised" version of these symbols See next section
for a complete list of these phonetical symbols.
A great news is that you do not have to write the text
with the phonetical language. You can instead use a
special function called Translate() which can be found in
a the "Translator Library". This function can
automatically convert english text into phonetics.
2. After you have created a string with the phonetical text
you send it to the "Narrator Device" which will transform
the phonetical symbols into sound, and the text is read.
5.2.1 PHONETIC SYMBOLS
The phonetical symbols used by the dictionaries can sadly not
be used on normal computers since they use very strange
signs that can not be reproduced on normal keyboards. Instead
we have to use a special computerized set phonetical symbols
which is defined like this:
Sound Phoeme Example Type
---------------------------------
A AE Hat Vowel
AO Talk Vowel
EY Page Diphthong (A diphtong is a union
--------------------------------- of two vowel sounds or
B B Bad Consonant vowel letters.)
---------------------------------
C CH Chin Consonant
K Car Consonant
---------------------------------
D D Did Consonant
---------------------------------
E EH Ten Vowel
IY Feet Vowel
---------------------------------
F F Four Consonant
---------------------------------
G G Got Consonant
---------------------------------
H /H How Consonant
---------------------------------
I AY Five Diphthong
ER Fur Vowel
IH Sit Vowel
---------------------------------
J J Yes Consonant
---------------------------------
K K Cat Consonant
---------------------------------
L L Leg Consonant
---------------------------------
M M Man Consonant
---------------------------------
N N No Consonant
NX Sing Consonant
---------------------------------
O AA Got Vowel
AW Now Diphthong
AX About Vowel
IX Solid Vowel
OH Saw Vowel
OW Home Diphthong
OY Join Diphthong
UH Put Vowel
---------------------------------
P P Pen Consonant
---------------------------------
Q K Cat Consonant
---------------------------------
R R Red Consonant
---------------------------------
S S Sit Consonant
SH She Consonant
---------------------------------
T DH Then Consonant
T Tea Consonant
TH Thin Consonant
---------------------------------
U AH Cup Vowel
UW Too Diphthong
---------------------------------
V V Voice Consonant
---------------------------------
W W Wet Consonant
---------------------------------
X /C Loch Consonant
---------------------------------
Y Y Yellow Consonant
---------------------------------
Z Z Zoo Consonant
ZH Vision Consonant
---------------------------------
For example, the word "hello" can phonetically be written as
"/HEHLOW", and the word "house" as "/HAWZ".
5.2.2 INTONATION
When you are speeking you do not use the same voice all the
time. Some parts of the words or sentences are stressed by
using a higher voice, were other parts are prounounced more
softly.
For example, the letter "e" in the word "hello" is usually
prounounced in a higher voice. By stressing some words the text
will sound more interesting, and if used with care it can be a
very effective way to get the user's attention.
Futhermore, by stressing different parts of a sentence the
whole meaning of the sentence can change quite dramatically.
Take the sentence "I will go home" for example. By stressing
different words the user will interpretate the meaning
differently. With these four words we can actually get five
rather different meanings:
1. If no stressin is used, the meaning is simply that the
person is going home.
2. By stressing the first word "I" it now sounds like the
person him/her self is going home but the other persons
(if there are any) may do something differently.
3. By stressing the second word "will" it now sounds like
the persons is really determined and that he/she really
wants to go home.
4. If the person stresses the third word "go" he/she means
that he/she will walk home, although the word "go" can
mean travelling by car, train etc.
5. Finally, if the last word is stressed the person wants
to go to his/her home, and not any other place.
To stress parts of a word you can put a single digit directly
after the phonem which should use a higher intonation. The
digit 0 means no special intonation, while the higher digit
the more stressed will the phonem be. The digit 9 should be
used when you want maximum intonation.
For example, the stress the letter "e" in the word "hello" the
phonetically string should be written as "/HEH4LOW". The
phonem "EH" will then be medium stressed.
5.2.3 PUNCTATION AND SPECIAL SYMBOLS
There exist some symbols which are used to help the reader to
use the righ intonations. The most commonly used symbole is the
puncation ".", but others are the question mark "?", the comma
",", dash "-", etc... Most of these common punctations are
understod by the Amiga, and will automatically alter the
intonation and speed correctly.
Here are the symbols you may use:
Type Symbol How it affects the intonation
------------------------------------------------------------
Punctation . This will make the intonation of the
last word a bit softer, and there will
be a long pause before any following
words are read.
Question mark ? This will cause the Amiga to increase
the intonation of the last word so it
sounds like a question, and it will be
followed by long pause before any
following words are read.
Comma , The comma is used to divide a sentense
into several parts, but putting a small
pause before the following text.
Dash - The dash can be used as the comma, and
works much in the same way. There exist
a lot of confusing rules on when the
dash and when the comma should be used,
but I do not intead to expalin it here.
(Mainly because I do not know anything
about these rules, sadly. I use what
looks best, which I think is an
excellent rule.)
Parentheses ( ) Parantheses are used to explain
something which is not so important that
it has to be in the main sentense, but
is can still be important for the
reader. The text inside parantheses
starts off by using less intonation than
the rest of the sentense.
5.2.4 VOLUME
Although the intonation is altering the volumne a little, most
of the text will be read with the same volume. You can however
tell the narrator device to use a completely different volume,
and this can be very effective. If you normally use a soft
voice, but suddenly increase it to the maximum the user will
not miss that part.
Producing the correct sound can take some time, but once you
have mastered it, the text will sound rather smooth and,
although a bit computerized, rather human.
5.3 CONVERT TEXT INTO PHONETIC SYMBOLS
Converting text into phonetical symbols does not have to be a
hard task. If you are going to read an English text (or
American, Irish, Scottish etc...) you can use the Translate()
function. It will automatically convert the text into (almost)
correct phonetics which can be used.
The Translate() function is located in the "Translator" library
which must be opened before you can use the function. The
Translate() function is actually the only function in this
library.
5.3.1 OPEN THE TRANSLATOR LIBRARY
To open the translator library you declare a global pointer
to it which must be called "TranslatorBase", and you then call
the function OpenLibrary() to open it.
Synopsis: library_ptr = OpenLibrary( name, revision );
library_ptr: (struct Library *) If the function could open
the library it returns a pointer to it, else
NULL is returned. The translator library is
located on the system disk, and is therefore
loaded when needed. If some other program
already has opened it has already been loaded
into memory and a pointer is immediately
returned to it.
Be careful to close the library before your
program terminates. If you forget it, the
library will remain in the memory until the
computer is switched off.
name: (char *) Pointer to a string containing the
name of the library you want to open. When
you open the translator library, the name
should be "translator.library".
revision: (long) This value tells the Amiga which oldest
version may be used. If there exist a library
with the same or higher value the function will
successfully open the library, else NULL is
returned. If you simply want any version, set
this field to zero.
Here is an example: (Remember that the pointer to the
translator library must ALWAYS be called "TranslatorBase"!)
/* Pointer to the translator library: */
struct Library *TranslatorBase;
/* Open the library: */
TranslatorBase = OpenLibrary( "translator.library", 0 );
/* Have we successfully opened it? */
if( !TranslatorBase )
clean_up( "Could not open the translator library!" );
5.3.2 TRANSLATE TEXT
Once you have opened the translator device you may start to
use the Translate() function. This function will work best
with English sentences, but can be used for many other
languages if you afterwards do some small changes of the
phonetic text.
Synopsis: char_left = Translate( in, in_len, out, out_len );
char_left: (long) If not all phonetic text could fit in the
out string the function will automatically only
translate the words which will fit. (It will not
stop in the middle of a word.) If all words could
be translated zero is returned, else a negative
value is returned. This value tells us how many
letters of the "in" string have been translated.
With this value we can then call the function
again and translate the remaining text.
Note that the number is negative.
in: (char *) Pointer to the (English) text string
which should be read.
in_len: (long) The length of the (English) text string.
out: (char *) Pointer to a string where the phonetic
text string will be stored. (The "in" string is
converted and copied to the "out" string.)
out_len: (long) The length of the phonetic (out) string.
Here is an example on how to translate a string. The nice thing
is that we can translate strings of any size. If the translated
string does not fit in the buffer, we divide it up into smaller
parts.
/* Translated buffer size: */
#define PHONETIC_BUFFER_SIZE 50
/* Number of characters that were translated, or */
/* zero if all characters were translated: */
int char_translated;
/* This variable contains the current position */
/* in the string which is translated: */
int current_position;
/* The original string: */
char *original_string = "The Amiga C Encyclopedia!";
/* The phonetic string: */
char phonetic_string[ PHONETIC_BUFFER_SIZE ];
/* Open the translator library: */
TranslatorBase = (struct Library *)
OpenLibrary( "translator.library", 0 );
/* Have we successfully opened the library? */
if( !TranslatorBase )
clean_up( "Could not open the translator library!" );
/* Start with the first character in the original string: */
current_position = 0;
/* Translate (parts of) our string into phonetics: */
char_translated =
Translate( original_string,
strlen( original_string ),
phonetic_string,
PHONETIC_BUFFER_SIZE );
/* Print the translated part: */
printf( "%s\n", phonetic_string );
/* As long as Translate() does not return zero we stay */
/* in this while loop and continues to translate the */
/* original string into phonetics: */
while( char_translated )
{
/* Increase the current position in the original string: */
/* (Remember that "char_translated" variable is negative, */
/* and we must therefore use the "-=" operator and not */
/* the "+=" to increase the current position.[-- = +]) */
current_position -= char_translated;
/* Translate the following part our string into phonetics: */
/* (Note that when we put brackets after a string we we */
/* get the character at the specified position, but since */
/* we want the address of that position we also have to */
/* put the pointer "&" sign in front of the string.) */
char_translated =
Translate( &original_string[ current_position],
strlen( &original_string[ current_position] ),
phonetic_string,
PHONETIC_BUFFER_SIZE );
/* Print the translated part: */
printf( "%s\n", phonetic_string );
}
/* All words have now been translated! */
5.3.3 CLOSE THE TRANSLATOR LIBRARY
Before your program terminates it must close the translator
library. This is especially important with this library since
it is loaded from the system disk when opened, and if you do
not close it a lot of memory is wasted. Be careful about this.
As I have said many times, make sure that your program does not
only terminate nicely when it has reached the end. It must also
manage to terminate nicely if it suddenly has to quit because of
some error. If you look at the examples which accompanies this
manual you will see that most of them use a function called
"clean_up()". The idea with this function is that it examines
all resources, and if it finds out that something has been
opened or allocated it closes it before the program terminates.
Because it examines all the resources before it attempts to
close or deallocate them the function can always be called and
it will clean up everything, even if you only have opened and
allocated some resources. Try to use something similar in your
own programs.
5.4 READ PHONETIC SYMBOLS
The translator library and the function Translate() are only
used to convert normal (English) text into phonetical strings.
These phonetical strings can then be read by the Amiga, but to
do this you have to use another resource on the Amiga which is
the famous "Narrator Device". (Tataaa, trumpets and drums!)
The narrator device is very straight forward and easy to use.
As always you use request blocks to send your commands, and the
device will reply by sending messages to a reply (message)
port. The device should of course first be opened by calling
the OpenDevice() function. When your program wants to terminate
the device and message port are closed and the request block
is deallocated.
5.4.1 NARRATOR REQUEST BLOCK
When you are using the narrator device you have to use an
extended request block called "narrator_rb" which is defined
like this: (Defined in header file "devices/narrator.h".)
struct narrator_rb
{
struct IOStdReq message;
UWORD rate;
UWORD pitch;
UWORD mode;
UWORD sex;
UBYTE *ch_masks;
UWORD nm_masks;
UWORD volume;
UWORD sampfreq;
UBYTE mouths;
UBYTE chanmask;
UBYTE numchan;
UBYTE pad;
};
message: The top part of this request block consists of the
standard input output request block. This IOStdReq
block is explained below.
rate: The speaking rate in words per minute. The default
rate (DEFRATE) has been defined as 150 words per
minute. The maximum speed (MAXRATE) is 400 words and
the minimum speed (MINRATE) is 40 words per minute.
pitch: The voice's pitch. This is the medium pitch value.
Stressed words are spoken with a higher pitch, while
soft words are spoken with a lower pitch. By
changing this value the whole voice is affected.
The default pitch (DEFPITCH) is 110. The maximum
pitch (MAXPITCH) is 320 and the minimum pitch is 65.
mode: This value will affect the way the text is read. If
you set the flag "NATURALF0" the voice will go up
and down as the text is read. On the other hand, if
you set the flag "ROBOTICF0" the voice will be very
dull and does not change as the text is read.
sex: If the flag "MALE" is set a dark male voice will be
used. If you instead set the flag "FEMALE" a lighter
and sharper voice will be used. (Do not ask me why
they did not define it as "BITCH".)
*ch_masks: This field should be given a pointer to an
"allocation array" which specifies which audio
channels that should be used.
There exist four sound channels which can be used.
The first and last sound channel is connected to the
left audio port, while the second and third is
connected to the right audio port.
To specify which channels you want to use you use
a value where the first bit represents the first
sound channel, the second bit the second sound
channel and so on...
Bit: 3 2 1 0
-------------------------------------
Value: 8 4 2 1
Channel: 3 2 1 0
Audio port: Left Right Right Left
To reserve the first and last channel (both using
the left sound channel) you would use the value 9
(1001[bin] = 9[dec]). To reserve the second and
third channel (both using the right sound channel)
you would use the value 6 (0110[bin] = 6[dec]).
To reserve all four sound channels set the value to
15 (1111[bin] = 15[dec]).
The allocation array should consist of all the
channel combinations you like. The narrator device
will first try to reserve the channels specified by
the first value. If it could not get these channels,
it tries the next values until if finds a
combination it could reserve or it reaches the end
of the allocation array and the operation fails.
For example. If you want that the text should be
read in stereo you have to use one audio channel
from the right and one from the left port. There
exist four possible combinations which satisfy this,
and the "allocation array" should therefore look
like this:
UBYTE allocation_array = { 3, 5, 10,12 };
Dec Bin Description
---------------------------------------------------
3 0011 First left and first right channel.
5 0101 First left and second right channel.
10 1010 Second left and first right channel.
12 1100 Second left and second right channel.
nm_masks: This field should be given a number which tells the
narrator device how many values there are in the
allocation array.
volume: The volume of the voice. The default volume (DEFVOL)
is the same as the maximum volume (MAXVOL) which is
defined as 64. The minimum volume (MINVOL) is 0
which is the same thing as silent.
I myself does not like that the maximum volume is
often used. It would be much better if everyone were
using the medium volume as the default value. The
user will then turn up the volume on his/her stereo
to compensate for the lower volume. The advantage is
that if you now suddenly play a very loud sound or
use a very loud voice it will also be very loud.
Imagine a game which is normally using a sound level
of 32. The user is sitting alone in his/her own room,
and it is very late. Imagine what would happen if a
monster would appear in the the game and at the same
time the volume was increased to maximum. It will
undoubtedly be a nice (hmmm) surprise for the user.
sampfreq: This field specifies which frequency should be used.
The default frequency (DEFFREQ) is 22200. The
maximum value (MAXFREQ) is 28000 and the minimum
value (MINFREQ) is 5000.
mouths: Normally this field should be set to zero. However,
of you are going to use the "mouth" request, as
explained below, you should set a non zero value.
chanmask: This field contains the value which was used of the
allocation array to reserve the audio channel(s).
This field is used by the system, but if you like
you may examine it, but you may never change it.
numchan: Number of channels used. This field is also used by
the system, but if you like you may examine it, but
you may never change it.
pad: This field is not used, and should therefore never
be used.
The IOStdReq structure (which is a part of the narrator_rb
structure) is defined in the "exec/io.h" header file like this:
(Only some parts of this structure will be used, so you do not
have bother too much about it.)
struct IOStdReq
{
struct Message io_Message;
struct Device *io_Device;
struct Unit *io_Unit;
UWORD io_Command;
UBYTE io_Flags;
BYTE io_Error;
ULONG io_Actual;
ULONG io_Length;
APTR io_Data;
ULONG io_Offset;
};
io_Message: The top part consists of a Message structure which
will be sent to us when the request has been
completed (successfully or not). This message
structure will automatically be given a pointer to
the reply port when the narrator_rb structure is
created, and the priority will automatically be set
when used, so we do not have to bother too much
about it.
io_Device: This field will automatically be initialized when
you use this request block together with an
OpenDevice() function call. It is simply a pointer
to the device which this request block is made for.
io_Unit: This field will automatically be initialized when
you send the request block to the narrator device.
io_Command: The following commands are accepted by the narrator
device, and may be used: (Will be explained below.)
CMD_WRITE Start to speak.
CMD_STOP Stop all speech requests.
CMD_START Start to speak again.
CMD_FLUSH Remove all queued requests.
CMD_RESET Reset the narrator device.
io_Flags: No flags are used.
io_Error: If the request can not successfully be executed by
the narrator device, it will be returned with one
of the following error flags:
ND_NoMem Not enough memory for the request.
ND_NoAudLib Can not open the audio device.
ND_MakeBad Can not execute the MakeLibrary()
function.
ND_UnitErr Wrong unit number (not 0).
ND_CantAlloc Can not find any free audio channels
to reserve.
ND_Unimpl Not a valid command.
ND_NoWrite Nothing is being read, so you can
not read any "mouth" values.
ND_Expunged Wrong expunge value.
ND_PhonErr Wrong phonetic code.
ND_RateErr Too large or small rate value
ND_PitchErr Too large or small pitch value
ND_SexErr Wrong sex number used.
ND_ModeErr Wrong mode value used.
ND_FreqErr Too high or low frequency value.
ND_VolErr Too high or low volume value.
io_Actual: Used by the system.
io_Length: The number of characters in the phonetic string
that should be read.
io_Data: Pointer to the phonetic sting.
io_Offset: Used by the system.
5.4.2 OPEN THE NARRATOR DEVICE
To open the narrator device does not differ from opening other
devices. First you have to create a message port to which the
device can send messages to you. Secondly you have to create
one or more narrator_rb structures by using the CreateExtIO()
function. Finally you can open the narrator device with help
of one of the request blocks.
1. Open a message port. Since it is only our task and the
narrator device that will use the message port, we do not
need to make it "public", therefore no name. Priority
should as usual be set to 0, normal priority.
struct MsgPort *replymp;
replymp = (struct MsgPort *)
CreatePort( NULL, 0 );
if( !replymp )
clean_up( "Could not create the reply port!" );
2. Allocate a request block of type narrator_rb structure.
The narrator_rb structure is an extended version of the
normal request block, and should therefore be allocated
with help of the CreateExtIO() function with the size
set to sizeof( struct narrator_rb ).
struct narrator_rb *narrator_req;
narrator_req = (struct narrator_rb *)
CreateExtIO( replymp, sizeof( struct narrator_rb ) );
if( !narrator_req )
clean_up( "Not enough memory!" );
3. Once the message port and the request block have
successfully been created you can "open" (gain access to)
the narrator device. The default values will now also be
set in the request block.
error = OpenDevice( "narrator.device", 0, narrator_req, 0 );
if( error )
clean_up( "Could not open the Narrator Device!" );
5.4.3 READ PHONETIC TEXT
Once you have successfully opened the narrator device you may
start to use the narrator device. The fields of the request
block with which the narrator device was opened with have
automatically been given the default values:
1. The rate is set to 150 words per minute.
2. The pitch is set to 110 Hz.
3. The mode is set to normal (living) voice.
4. The sex field is set to man.
5. The sampfreq is set to 22200.
6. The volume is set to 64.
The following fields must be initialized by yourself:
1. You must give the "io_Data" field of the IOStdReq
structure a pointer to the string of phonetic words that
should be read.
2. Give the "io_Length" field of the IOStdReq structure the
number of translated characters that should be read.
You can use the function strlen() to find out how long
the translated string is.
3. You have to give the "ch_masks" field a pointer to the
allocation array that should be used.
4. Give the "nm_masks" field the number of values which exist
in the allocation array.
5. Finally you should give the "io_Command" field of the
IOStdReq structure the "CMD_WRITE" flag. (We are going to
send [write] text to the narrator device.)
Here is an example:
/* The text should be read in stereo: */
UBYTE allocation_array[]=
{
LEFT0F|RIGHT0F, /* First left and first right channel. */
LEFT0F|RIGHT1F, /* First left and second right channel. */
LEFT1F|RIGHT0F, /* Second left and first right channel. */
LEFT1F|RIGHT1F /* Second left and second right channel. */
};
/* The phonetic string: */
char *phonetic_string = "/HEH4LOW";
/* Message port opened... */
/* "narrator_rb" created... */
/* Narrator device opened... */
/* Set our requirements: */
/* 1. Give it a pointer to the phonetic string: */
narrator_req->message.io_Data = (APTR) phonetic_string;
/* 2. Set the length of the phonetic string: */
narrator_req->message.io_Length = strlen( phonetic_string );
/* 3. Desired channel combinations: */
narrator_req->ch_masks = allocation_array;
/* 4. Size of the allocation array: */
narrator_req->nm_masks = sizeof( allocation_array );
/* 5. Send (write) the text to the device: */
narrator_req->message.io_Command = CMD_WRITE;
You may of course also change the other values if you do not
want to use the default ones.
After the request has been initialized can it be sent to the
narrator device which will read the phonetic string. To send
request you can either use the synchronous command DoIO() or
the asynchronous command SendIO().
The DoIO() function will send the request to the device and
put your program to sleep. When the device has finished your
request it is returned and your program wakes up. If something
failed will DoIO() return an error number and a copy of their
value will also be stored in the "io_Error" field of the
request block.
The SendIO() function should be used when you want to continue
to do something while the narrator device is reading the text.
After you have called SendIO() you can put your task to sleep
by either using the WaitIO() or Wait() function. If you want
to check if the request has been completed you can use the
CheckIO() function.
All these functions have been described in chapter "Devices",
and will therefore not be repeated here.
An example on a synchronous call: (Your program is put to sleep
while the narrator device completes your request.)
BYTE error;
/* ... */
/* Read the text: */
error = DoIO( narrator_req );
/* Were there any errors? */
if( error )
clean_up( "Problems with reading the text!" );
An example on an asynchronous call: (Your program continues to
run while the text is read.)
/* Start to read: */
SendIO( narrator_req );
while( !CheckIO( narrator_req ) )
{
/* Do something... */
}
/* Collect message at the reply port... */
/* Were there any errors? */
if( narrator_req->message.io_Error )
clean_up( "Problems with reading the text!" );
5.4.4 USING SEVERAL REQUEST BLOCKS
If you have created several request blocks will only the one
which you opened the narrator device with be correctly
preinitialized. These structures which have not been initialized
must be prepared before they may be used. The simplest solution
is actually to copy the whole structure, because you will then
be sure that no values are forgotten.
Here is an example:
/* Source and destination pointers: */
BYTE *first_ptr;
BYTE *second_ptr;
/* Allocate request blocks, open narrator device, etc... */
/* (The two request blocks are called "first_narrator_req" */
/* and "second_narrator_req".) */
/* Copy the first request block to the second one: */
/* Get the start addresses of both request blocks: */
first_ptr = (BYTE *) first_narrator_req;
second_ptr = (BYTE *) second_narrator_req;
/* Copy byte by byte: */
for( loop = 0; loop < sizeof( struct narrator_rb ); loop++ )
{
/* Copy: */
*second_ptr = *first_ptr;
/* Next byte: */
first_ptr++;
second_ptr++;
}
5.4.5 CLEAN UP
When your program terminates you have to clean up and free all
allocated resources. This is what has to be done:
1. Remove any messages still left at the message (reply) port.
2. Close the message (reply) port(s).
3. Close the narrator device.
4. Deallocate the request blocks.
5.4.5.1 REMOVE ALL MESSAGES
Before you close anything you should first remove all messages
from the message (reply) port. A short while loop that removes
the messages until it can not find any more is a simple but
effective solution.
while( GetMsg( replymp ) )
printf( "Collected a message at the reply port.\n" );
5.4.5.2 CLOSE MESSAGE PORT
After all messages have been removed from the port you may close
it by calling the DeletePort() function. Note that you should
never try to close a message port you have not opened.
DeletePort( replymp);
5.4.5.3 CLOSE THE NARRATOR DEVICE
The narrator device itself must of course also be closed if you
have opened it. Note that you should never try to close a
device you have not opened.
CloseDevice( narrator_req );
5.4.4 DEALLOCATE THE REQUEST BLOCKS
Finally you should deallocate all request blocks you have
created. Use the DeleteExtIO() function. The size should be set
to the size of a narrator_rb structure. Just remember to close
the narrator device before you deallocate the request block(s).
DeleteExtIO( narrator_req, sizeof( struct narrator_rb ) );
5.5 THE NARRATOR'S MOUTH
The narrator device offers a rather unique but sometimes useful
feature. The narrator device can be used to draw a mouth as the
text is read. It may sound a bit strange, but if you are using
animations this can be very helpful.
The narrator device will tell us how wide and high the mouth
should be, and with this we can easily construct a simple
mouth.
5.5.1 MOUTH REQUEST BLOCK
To use this "mouth" feature you have to use a special request
block which is called "mouth_rb", and looks like this: (Defined
in header file "devices/narrator.h".)
struct mouth_rb
{
struct narrator_rb voice;
UBYTE width;
UBYTE height;
UBYTE shape;
UBYTE pad;
};
voice: The top part of the mouth block consists of a
"narrator_rb" structure. When you create this structure
the message port will automatically be initialized.
The following fields must however be initialized by
yourself:
1. You must copy the "io_Device" pointer from the
request which is reading the text.
2. The "io_Unit" number must also be copied.
3. The "io_Error" field should be set to zero.
4. Finally you should set the command "CMD_READ"
in the "io_Command" field.
After you have sent this request block and it is
returned you can examine the "io_Error" field to
check if there were any problems. See above for a
complete list of error flags.
When you are using this request, it will be returned to
you if one of the following thing has happened:
1. The size of the mouth has changed.
2. Something went wrong, and the "io_Error" field will
contain an error flag. If you have received the
"ND_NoWrite" the Amiga has stopped talking, and
you should not try to draw any mouth any more.
width: After you have successfully executed this request you
can examine this field to check how wide the mouth
should be. The request block will only be returned when
the size of the mouth has changed, or the Amiga has
stopped talking.
height: This field will contain the height of the mouth.
shape: This field may only be used by the system, and should
never be changed.
pad: No used, and should not be used.
5.5.2 CREATE A MOUTH REQUEST BLOCK
Since the size of the mouth_rb is larger than the standard
sized request block you have to use the CreateExtIO() function
to allocate and preinitialize the request block. Normally it
is easiest to connect this structure to the same message port
as the other request blocks are connected to. You can of course
use a separate message port if you want.
struct mouth_rb *mouth_req;
mouth_req = (struct mouth_rb *)
CreateExtIO( replymp, sizeof( struct mouth_rb ) );
if( !mouth_req )
clean_up( "Not enough memory!" );
5.5.3 PREPARE THE MOUTH REQUEST BLOCK
After you have created the mouth_rb structure you have to copy
some values, as explained above, from the request block which
will read the text. You must also set some values yourself.
Here is an example on how to initilaize the mouth request:
/* Set the mouth width and height to zero: */
mouth_req->width = 0;
mouth_req->height = 0;
/* Give the mouth request a pointer to the narrator device: */
mouth_req->voice.message.io_Device = narrator_req->message.io_Device;
/* Give the mouth request the current unit number: */
mouth_req->voice.message.io_Unit = narrator_req->message.io_Unit;
/* No error number (so far): */
mouth_req->voice.message.io_Error = 0;
/* The mouth request should look at (read) the request */
/* which is currently talking: */
mouth_req->voice.message.io_Command = CMD_READ;
The mouth_rb request block can now be used.
5.5.4 GET THE SIZE OF THE MOUTH
The mouth request block should be sent to the narrator device
after you have sent a normal read request. If the device is
currently not reading any text the mouth request will
immediately be returned with the error flag "ND_NoWrite" set.
If the device is reading some text the mouth request will first
be returned when the mouth has changed size, or if the narrator
device has reached the end of the text string. If the device
reached the end of the string and stops talking the mouth
request will be returned with the error flag "ND_NoWrite" set.
However, if the request is returned and no error flag is set,
the mouth has changed size and should be redrawn.
Since your program must be able to work while the narrator
device is reading the text you have to use the asynchronous
command SendIO() to start the read request. Here is an example
on how to use the narrator's mouth:
/* TRUE as long the Amiga is reading text: */
BOOL still_talking;
/* ... */
/* Start to read: (The read request must be sent by */
/* the asynchronous command SendIO().) */
SendIO( narrator_req );
/* The Amiga is reading the text: */
still_talking = TRUE;
/* As long as the Amiga is reading the text */
/* we stay in the while loop: */
while( still_talking )
{
/* Send the mouth request to the narrator device. The request */
/* will be returned when the mouth width and/or height have */
/* changed, or the device has stopped reading the text: */
DoIO( mouth_req );
/* Has the device stopped reading the text: */
if( mouth_req->voice.message.io_Error == ND_NoWrite )
still_talking = FALSE;
else
{
/* No, the device is still reading. The mouth must have */
/* changed, so we better redraw it: */
/* Draw the new mouth... */
}
}
/* We know that the Amiga has stopped speaking, */
/* and hence we do not have to wait for the */
/* narrator to finish reading. We should however */
/* check if we have successfully read the text: */
if( narrator_req->message.io_Error )
clean_up( "Error while reading!" );
5.6 EXAMPLES
Example 1
This very simple example demonstrates how to open the
translator library, translate a string, and finally close
the library before the program terminates.
Example 2
This example demonstrates how you can use a while loop to
translate parts of a string until the whole string has been
translated.
Example 3
This example demonstrates how to translate a string into a
phonetical string which is then read by the narrator device.
Example 4
This example very similar to the previous one, but this time
are we using a different voice. By altering the rate, pitch,
mode, sex and volume, you can produce very different sounds.
Example 5
This example demonstrates how you can let the Amiga read
small stories. By altering the rate, pitch, mode, sex and
volume parameters it can sound like several persons are
talking. It can also be used to express emotions and stress
important parts of the text.
This example is using some home made functions which makes
life a little bit easier. If you have to read a lot of text I
recommend you to use special functions like these. It will
then be much easier to write (and read) the program code.
Example6
This example demonstrates how to use the mouth request block
to draw a talking mouth.