Commit 5267a417 authored by Samuel Thibault's avatar Samuel Thibault

Remove generated files

parent eaadcf1b
%% This LaTeX-file was created by <pagel> Fri Apr 7 15:39:55 2000
%% LyX 0.12 (C) 1995-1998 by Matthias Ettrich and the LyX Team
%% Do not edit this file unless you know what you are doing.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
\par {\raggedleft \begin{tabular}{l}\ignorespaces
\title{MBROLA }
\date{(Multi-Band Resynthesis OverLap Add)}
\date{System documentation}
\date{Edition 7.0 - Mbrola release 3.02}
\date{March 12th, 2000}
\char`\"{}It would be a considerable invention indeed, that of a machine able
to mimic speech, with its sounds and articulations. I think it is not impossible.\char`\"{}
Leonhard Euler (1761)
\lyxrightaddress{by Vincent Pagel and Thierry Dutoit\\
\section{MBROLA Sources General condition of use}
The source code of MBROLA may only be used to produce the object code sold by
your company. It is confidential and should remain safely locked, as well as
its documentation.
\section{A brief description of MBROLA}
MBROLA v3.01 is a speech synthesizer based on the concatenation of diphones.
One synthesis channel takes a list of phonemes as input, together with prosodic
information (duration of phonemes and a piecewise linear description of pitch),
and produces speech samples on 16 bits (linear), at the sampling frequency of
the diphone database. It is therefore \noun{not} a Text-To-Speech synthesizer,
since it does not accept raw text as input.
It is distributed as a ZIP file whose name respect the format \emph{\char`\"{}\char`\"{}}
where \emph{XXXX} represent the version number (e.g. \emph{""}).\\
It may be compiled in 3 modes depending on which stream drives the process:
\item Driven by the input phonetic file: it is compiled as a standalone program named
\char`\"{}synth\char`\"{} which outputs audio in a file or a pipe. This mode
is a good choice under Unix platforms for end-user applications. In the following
we call this mode \textbf{\char`\"{}}\textbf{\emph{standalone mode}}\char`\"{}.
\item Driven by the audio output: compiled as a library, which outputs audio data
into buffers of the size, requested by the main program. This allows you to
easily include MBROLA inside your TTS application without temporary file mechanisms.
In the following we call this mode \char`\"{}\textbf{\emph{library mode}}\char`\"{}.
\item Same as above, included in a DLL for Windows95-98/NT (which is of course the
preferred mode for Windows platforms). In the following we call this mode \char`\"{}\textbf{\emph{DLL
While using \emph{library} or \emph{DLL} mode, we now differentiate one channel
and multi channel mbrola. In the first mode, one database is associated to one
and only one synthesis channel, which generally fits for end-user applications.
In the second mode, one can run many synthesis channel instantiations with one
or more Database instances and many phonetic input streams. This second solution
is adapted to multi channel telecom TTS applications.
In all those compilation modes MBROLA requires a language/voice database to
run properly. For your internal use (i.e. non-commercial) you can test the voices
made available on the MBROLA project homepage:
Refer to your contract to check your rights for commercial exploitation of the
different Diphone Databases.
Since release 3.01, Mbrola has been transformed into pure ANSI/C code, and object
like programming with a strong encapsulation of data (strong because we have
respected the fences we put!). One file in the distribution is generally equivalent
to one object (pointer on struct). You can find an exhaustive description in
the programmer's section 6.
This distribution of MBROLA contains the following files:
\item [Makefile:]Unix makefile for Gnu Make (gmake command)
\item [~]~
\item [DOCUMENTATION/Programmer/documentation302:]this document
\item [DOCUMENTATION/Programmer/HISTORY.txt:]history of revisions
\item [DOCUMENTATION/User/readme.txt:]standalone version manual
\item [~]~
\item [Database:]handling of different database formats
\item [Database/database.c:]functions to read diphones in the speech database
\item [Database/database.h]~
\item [Database/database\_bacon.c:]functions to read compressed diphone databases
\item [Database/database\_bacon.h]~
\item [Database/database\_old.c:]functions to read diphone databases older than 2.06
\item [Database/database\_old.h]~
\item [~]~
\item [Database/diphone\_info.c:]description of the diphone structures
\item [Database/diphone\_info.h]~
\item [~]~
\item [Database/hash\_tab.c:]hash table of DiphoneInfo (access to the diphone database)
\item [Database/hash\_tab.h]~
\item [~]~
\item [Database/little\_big.c:]handles the little and big endian numeric conversions
\item [Database/little\_big.h]~
\item [~]~
\item [Database/rename\_list.c:]list of phoneme pairs (used for renaming and cloning)
\item [Database/rename\_list.h]~
\item [~]~
\item [Parser:]functions to read phonemes in the input stream
\item [Parser/fifo.c:]First In First Out with chars
\item [Parser/fifo.h]~
\item [Parser/input.h:]define abstract input stream
\item [Parser/input\_fifo.c:]\textbf{i}nstantiation of input.h with Fifo
\item [Parser/input\_fifo.h]~
\item [Parser/input\_file.c:]instantiation of input.h with File
\item [Parser/input\_file.h]~
\item [Parser/parser.h:]define abstract phoneme parser
\item [Parser/parser\_input.c:]instantiation of parser.h with Input
\item [Parser/parser\_input.h]~
\item [Parser/phonbuff.c:]handle a phoneme buffer for pitch interpolation
\item [Parser/phonbuff.h]~
\item [Parser/phone.c:]phoneme type
\item [Parser/phone.h]~
\item [~]~
\item [Engine:]Mbrola synthesis engine
\item [Engine/diphone.c:]diphone with info for synthesis
\item [Engine/diphone.h]~
\item [Engine/mbrola.c:]mbrola algorithm (Ola, Smoothing...)
\item [Engine/mbrola.h]~
\item [~]~
\item [Misc:]Miscellaneous functions basically unrelated to synthesis
\item [Misc/audio.c:]audio output and audio file header (au, wav, aiff, raw)
\item [Misc/audio.h]~
\item [Misc/common.c:]useful little functions (uppercase, swab...)
\item [Misc/common.h]~
\item [Misc/g711.c:]G711 audio coding (ALAW and MULAW)
\item [Misc/g711.h]~
\item [Misc/incdll.h:]external definitions used outside of the Mbrola package
\item [Misc/mbralloc.c:]memory allocators are here and ONLY here
\item [Misc/mbralloc.h]~
\item [Misc/vp\_error.c:]deals with fatal error and warnings
\item [Misc/vp\_error.h:]macros for debugging purposes
\item [~]~
\item [Standalone:]Standalone compilation front-end
\item [Standalone/Posix]~
\item [Standalone/Posix/getopt.c:]provided for non-POSIX Unixes
\item [Standalone/Posix/getopt.h]~
\item [Standalone/synth.c:]front-end for the compilation in the standalone mode. Main()
\item [Standalone/synth.h]~
\item [LibOneChannel:]library providing one MBROLA synthesis channel
\item [LibOneChannel/demo1.c:]small demonstration program running with the library
\item [LibOneChannel/demo1b.c:]small demo showing error handling with the library
\item [LibOneChannel/onechannel.c:]library providing one mbrola channel at a time
\item [LibOneChannel/onechannel.h]~
\item [LibOneChannel/lib1.c:]wrapper file to build the library lib1.c (mono channel)
\item [~]~
\item [LibMultiChannel:]library for multi MBROLA synthesis channel for telecom
\item [LibMultiChannel/multichannel.c:]many synthesis channel from one dba
\item [LibMultiChannel/multichannel.h]~
\item [LibMultiChannel/demo2.c:]demo using lib2
\item [LibMultiChannel/lib2.c:]wrapper file to build the library lib2.c (multi channel)
\item [~]~
\item [VisualC++:]compilation projects for Microsoft Visual C++
\item [VisualC++/DLL:]Visual C++ project to build the DLL
\item [VisualC++/DLL\_USE:]sample program using the DLL
\item [VisualC++/Standalone:]Visual C++ project to build a standalone binary
\item [~]~
\item [Bin:]directory containing the output of the compilation with Make under Unix
\section{Installation and Tests~ }
\subsection{On Unix}
You must first unzip the distribution file where XXXX stand for
the version number:
\item [unzip]
\item [Mbrola]can be compiled with the 'gmake' (gnu make) command on the following
\item SUN Sparc 5/S5R4 (Solaris2.4)
\item HPUX9.0 and HPUX10.0
\item VAX/VMS V6.2 (V5.5-2 won't work)
\item AlphaStation 200 4/233
\item AlphaStation 200 4/166
\item IBM RS6000 Aix 4.12
\item PC/LINUX 1.2.11
\item PCPentium120/Solaris2.4
\item OS/2
\item BeBox
\item QNX OS
Though, as Mbrola is written in standard ANSI/C, we also support POSIX compliant
UNIX Platforms. Please send acknowledgment when Mbrola works on a machine/system
not listed here. Before you compile anything you must define some symbols depending
on the architecture you're working with:
\item [LITTLE\_ENDIAN] 80x86 based platforms
\item [BIG\_ENDIAN] motorola or HP based platforms
\item [VMS] VAX/VMS stations
\item [DOS] PC80x86 with Dos or Windows
\item [SUN4] old Sun4 stations (not Posix compliant)
\item [DEBUG] Huge debugging flag
\item [DEBUG\_HASH] Runs the database and print info about the hash table management
(used to tune the memory management of the database)
\item [According]to the compilation mode you wish, you can comment or uncomment following
lines of Makefile :
You can add any definitions to the CFLAGS (compilation flags) variable of the
Makefile, as in the following example:
\item [optimized]compilation on a Sun Station :
\item [debug]mode on a VAX/VMS :
By default the compiler is set with CC = gcc ; though on many platforms cc may
also work. As the hardware manufacturer generally provides cc, it is preferred
when possible since the object code performance can be higher by an order of
magnitude. You can type :
\item [\char`\"{}make\char`\"{}]or \char`\"{}make all\char`\"{} to generate the 'synth'
binary (standalone mode).
\item [\char`\"{}make]clean\char`\"{} removes the entire object files and binaries.
\item [\char`\"{}make]lib1\char`\"{} compiles lib1.c in the library mode (one channel
\item [\char`\"{}make]demo1\char`\"{} builds a demo exemplifying the use of lib1
\item [\char`\"{}make]lib2\char`\"{} compiles lib1.c in the library mode (multi channel
\item [\char`\"{}make]demo2\char`\"{} builds a demo exemplifying the use of lib2
\item [\char`\"{}make]tags\char`\"{} to build Emacs popular tags (helps finding your
way through the code with ESC-. ). SUN Workshop uses an internal btags program
for that purpose.
The intermediate object code goes into a Bin directory that is created on the
\subsection{On PCs/Dos}
On PC/Dos platforms, use \char`\"{}pkunzip\char`\"{} to restore
the files (don't forget to restore the embedded paths in the archive). Mbrola
can be compiled with Microsoft Visual C++ (4 .0 or higher), or Borland C++ (4
.5 or higher), on the following platforms:
\item PC486/DOS6 (but other PC/DOS should do, too)
\item PC486/Windows 3.1
\item PC486/Windows 95
\item PC-Pentium/Windows 98
\item PC-Pentium/Windows NT
Always check that in your project the following preprocessor directives are
defined: LITTLE\_ENDIAN and DOS. A project to build such a release with Visual
C++ is provided under VisualC++/Standalone.
\subsection{On PC/Windows}
First proceed like for the PC/DOS platforms. Once synthXXXX is installed you
can start building a DLL in the VisualC++\char`\\{}DLL directory. MbrolaDll.dsw
is a Microsoft VisualC++ 5.0 project file to build a DLL. In any project you
make to build a DLL with Mbrola don't forget to define the DLL, LITTLE\_ENDIAN,
DOS preprocessor definitions.
The Mbrola source files and a wrapper DLL interface is included in the project,
it should compile smoothly. In case you have to build a new project from scratch
remember that you should include only file from either LibOneChannel/ or LibMultiChannel/.
Never include files from Standalone/, as this directory is only relevant for
a standalone mode (see section above for an exe binary).
Several compilation modes are available, the \char`\"{}Win32 Bacon Static\char`\"{}
is a good one to start with (Bacon compression scheme is included, DLL are statically
In the directory VisualC++/DLL\_USE , little sample programs are given that
use the Mbrola DLL.
\subsubsection{Black magic}
There is a strange bug in Visual C++ 5.0, when you compile the project you sometime
nafxcw.lib(dllmodul.cbj) : error LNK2005: \_DllMain@12 already defined in LIBCMT.lib(dllmain.cbj)
nafxcw.lib(afxmem.cbj) : error LNK2005: \char`\"{}void {*} \_\_cdecl operator
new(unsigned int)\char`\"{} (??2@YAPAXI@Z) already defined in LIBCMT.lib(new.cbj)
nafxcw.lib(afxmem.cbj) : error LNK2005: \char`\"{}void \_\_cdecl operator delete(void
{*})\char`\"{} (??3@YAXPAX@Z) already defined in LIBCMT.lib(delete.cbj)
nafxcw.lib(dllmodul.cbj) : warning LNK4006: \_DllMain@12 already defined in
LIBCMT.lib(dllmain.cbj); second definition ignored
nafxcw.lib(afxmem.cbj) : warning LNK4006: \char`\"{}void {*} \_\_cdecl operator
new(unsigned int)\char`\"{} (??2@YAPAXI@Z) already defined in LIBCMT.lib(new.cbj);
second definition ignored
nafxcw.lib(afxmem.cbj) : warning LNK4006: \char`\"{}void \_\_cdecl operator
delete(void {*})\char`\"{} (??3@YAXPAX@Z) already defined in LIBCMT.lib(delete.cbj);
second definition ignored
Creating library MbrolaDl/Mbrola.lib and object MbrolaDl/Mbrola.exp
Output\char`\\{}Release\_Static\char`\\{}Mbrola.dll : fatal error LNK1169: one
or more multiply defined symbols found
Error executing link.exe.
Mbrola.dll - 4 error(s), 7 warning(s)
Solution: remove one file from the project and include it again in the list
of source files, and build the project again. The problem vanishes.
\subsection{Using the standalone binary}
You are now ready to test the program. First try: \char`\"{}synth\char`\"{}
to get an information screen about the copyright. Then, for a help screen on
how to use the standalone version of the software, try :
synth -h
You get a help screen like the following:
> USAGE: ./synth {[}COMMAND LINE OPTIONS{]} database pho\_file+ output\_file
>A - instead of pho\_file or output\_file means stdin or stdout
>Extension of output\_file ( raw, au, wav, aiff ) tells the wanted audio format
> Options can be any of the following:
> -i = display the database information if any
> -e = IGNORE fatal errors on unkown diphone
> -c CC = set COMMENT char (escape sequence in pho files)
> -F FC = set FLUSH command name
> -v VR = VOLUME ratio, float ratio applied to ouput samples
> -f FR = FREQ ratio, float ratio applied to pitch points
> -t TR = TIME ratio, float ratio applied to phone durations
> -l VF = VOICE freq, target freq for voice quality
> -R RL = Phoneme RENAME list of the form a A b B ...
> -C CL = Phoneme CLONE list of the form a A b B ...
> -I IF = Initialization file containing one command per line
> COMMENT, and IGNORE are available
Now in order to go further, you need to get a version of an MBROLA language/voice
database from the MBROLA project homepage. Let us assume you have copied the
FR1 database and referred to the accompanying fr1.txt file for its installation.
Then try:
synth fr1/fr1 fr1/TEST/bonjour.pho bonjour.wav
it uses the format:
synth diphone\_database command\_file1 command\_file2 ... output\_file
and creates a sound file for the word 'bonjour' (Hello! in French)
Basically the output file is composed of signed integer numbers on 16 bits,
corresponding to samples at the sampling frequency of the MBROLA voice/language
database (16 kHz for the diphone database supplied by the authors of MBROLA
: Fr1). MBROLA can produce different audio file formats: .au, .wav, .aiff, .aif,
and .raw files depending on the ouput\_file extension. If the extension is not
recognized, the format is RAW (no header). We recommend .wav for Windows, and
.au for Unix platforms. To display information about the phoneme set used by
the database, type:
synth -i fr1/fr1
It displays the phonetic alphabet as well as copyright information about the
Option -e makes Mbrola ignore wrong or missing diphone sequences (replaced by
silence) which can be quite useful when debugging your TTS. Equivalent to \char`\"{}IGNORE\char`\"{}
directive in the initialization file (N.B replace the obsolete ;;E=OFF , unsupported
in .pho file).
\subsubsection{Changing the pitch}
Optional parameters let you shorten or lengthen synthetic speech and transpose
it by providing optional time and frequency ratios:
synth -t 1.2 -f 0.8 -v 0.7 fr1/fr1 TEST/bonjour.pho bonjour.wav
or its equivalent in the initialization file:
TIME 1.2
FREQ 0.8
for instance, will result in a RIFF Wav file bonjour.wav 1.2 times longer than
the previous one (slower rate), and containing speech in which all fundamental
frequency values have been multiplied by 0.8 (sounds lower). You can also set
the values of these coefficients directly in a .pho file by adding special escape
sequence like :
;; F=0.8
;; T=1.2
You can change the voice characteristics with the -l parameter. If the sampling
rate of your database is 16000, indicating -l 18000 allows you to shorten the
vocal tract by a ratio 16/18 (children voice, or women voice depending on the
voice you're working on). With -l 10000,you can lengthen the vocal tract by
a ratio 18/10 (namely the voice of a Troll). The same command in an initialization
file becomes \char`\"{}VOICE 10000\char`\"{}.
Option \textbf{-v} gives a VolumeRatio that multiplies each output sample. In
the example below, each sample is multiplied by 0.7 (the loudness goes down).
Warning: setting VolumeRatio too high generates saturation.
synth -v 0.7 fr1/fr1 TEST/bonjour.pho bonjour.wav
or add the line \textbf{\char`\"{}VOLUME 0.7\char`\"{}} in an initialization
The \textbf{-c} option lets you specify which symbol will be used as an escape
sequence for comments and commands in .pho files. The default value is the semi-colon
';', but you may want to change this if your phonetic alphabet use this symbol,
like in:
synth -c ! fr1/fr1 TEST/test1.pho test2.pho test.wav
equivalent to \char`\"{}\textbf{COMMENT !}\char`\"{} in an initialization file
The \textbf{-F} option lets you specify which symbol will be used to Flush the
audio output. The default value is \textbf{\#}, you may want to change the symbol
like in:
mbrola -F FLUSH\_COMMAND fr1/fr1 test.pho test.wav
equivalent to \char`\"{}\textbf{FLUSH FLUSH\_COMMAND}\char`\"{} in the initialization
\subsubsection{Using Pipes}
A - instead of command\_file or output\_file means stdin or stdout. On multitasking
machines, it is easy to run the synthesizer in real time to obtain audio output
from the audio device, by using pipes.
\subsubsection{Renaming and Cloning phonemes}
It may happen that the language-processing module connected to MBROLA doesn't
use the same phonemic alphabet as the voice used. The Renaming and Cloning mechanisms
help you to quickly solve such problems (without adding extra CPU load). The
only limitation about phoneme names is that they can't contain blank characters.
If, for instance, phoneme a in the mbrola voice you use is called my\_a in your
alphabet, and phoneme b is called my\_b, then the following command solves the
synth -R \char`\"{}a my\_a b my\_b\char`\"{} fr1/fr1 test.pho test.wav
You can give as many renaming pairs as you want. Circular definition is not
a problem. E.g. \char`\"{}\textbf{a b b c}\char`\"{} will rename original \emph{{[}a{]}}
into {[}b{]} and original \emph{{[}b{]}} into \emph{{[}c{]}} independently \emph{({[}a{]}}
won't be renamed to \emph{{[}c{]}}).
LIMITATION: you can't rename a phoneme into another that already exists.
The cloning mechanism does exactly the same thing, though the old phoneme still
exists after renaming. This is useful if you have 2 allophones in your alphabet,
but the Mbrola voice only provides one.
Imagine for instance, that you make the distinction between the voiced {[}r{]}
and its unvoiced counterpart {[}r0{]} and that you are using a syllabic version
{[}r={]}. If as a first approximation using {[}r{]} for both is OK, then you
may use an Mbrola voice that only provides one version of {[}r{]} by running:
synth -C \char`\"{}r r0 r r=\char`\"{} fr1/fr1 test.pho test.wav
which tells the synthesizer that {[}r0{]} and {[}r={]} should be both synthesized
as {[}r{]}. You can write a long cloning list of phoneme pairs to fit your needs.
Renaming and cloning eats CPU since the complete diphone hash table has to be
rebuilt, but once the renaming or cloning has occurred there is absolutely NO
RELATED PERFORMANCE DROP. So using this feature is more efficient than a pre-processor
is, though a simple phoneme mapping cannot always solve incompatibilities.
Before renaming anything as \textbf{\#}, check section 5.1.2
When one has long cloning and renaming lists, you can conveniently write them
into an initialization file according to the following format:
RENAME a my\_a
RENAME b my\_b
CLONE r r0
CLONE r r=
The obsolete \char`\"{}\textbf{;; RENAME a my\_a}\char`\"{} can't be used in
.pho file anymore, but is correctly parsed in initialization files. Note to
EN1 and MRPA users: the consequence of the change above is that you must change
the previous call format \char`\"{}\emph{mbrola en1 en1mrpa...}\char`\"{} into
\char`\"{}\emph{mbrola -I en1mrpa en1 ...}\char`\"{}.
\subsection{Machine dependant hints for best using Mbrola}
\subsubsection{On MSDOS}
With the standalone version, generating wav files is easier:
synth fr1/fr1 TEST/bonjour.pho bonjour.wav
Then you can play the RIFF Wav file with your favorite DOS or Windows sound
utility. On OS/2 pipes may be used just like below.
\subsubsection{On modern Unix systems such as Solaris or HPUX or Linux}
synth fr1 bonjour.pho | audioplay
where audioplay is your audio file player ({*} the name vary with the platform,
e.g. splayer for HPUX {*}).
If your audioplayer has problems with sun .AU files, try with .wav or .raw.
Never use .wav format when you pipe the output (mbrola can't rewind the file
to write the audio size in the header). Wav format was not developed for Unix
(on the contrary Au format let you specify in the header \char`\"{}we're on
a pipe, read until end of file\char`\"{}).
NOTE FOR LINUX: you can use the GPL rawplay program provided at
\subsubsection{On Sun4 ( old audio interface )}
Those machines are now quite old and only provide a mulaw 8Khz output. A hack
synth fr1 input.pho - | sox -t raw -sw -r 16000 - -t raw -Ub -r 8000 - > /dev/audio
Provided you have the public domain sox utility developed by Ircam, you should
hear \emph{'bonjour'} without the need to create intermediate files. Note that
we strongly recommend that you DON'T use SOX, since its resampling method (linear
interpolation) will permanently damage the sound.
Other solution: The UTILITY.ZIP file available from the MBROLA homepage provides
RAW2SUN that does this conversion.
\subsubsection{On VAX or AXP workstations}
To make it easier for users to find MBROLA, you should add the following command
to your system startup procedure:
where \char`\"{}disk:{[}dir{]}\char`\"{} is the name of the directory you created
for the MBROLA\_DIR files. You could also add the following command to your
system login command procedure:
to use the decsound device:
\$ MCR DECSOUND - volume 40 -play
See also the MBR\_OLA.COM batch file in the UTILITY.ZIP file available from
the MBROLA Homepage if you cannot play 16 bits sound files on your machine.
\subsection{Default Parser Manual}
The default parser is the parser that was provided before release 3.01. Implicitly
it means that you can replace it with your own one, thanks to the setParser\_MBR
function. Basically the work of the parser is to return to Mbrola a phoneme
with a length, and its pitch points.
We provide a default parser that allows you to give optional pitch points, the
intonation curve being linearly interpolated between those points.
\subsubsection{Input file format}
Example of a command line :
synth fr1/fr1 bonjour.pho bonjour.wav
For example the phonetic input file bonjour.pho simply contains :
; \textbf{Bonjour}
\_ \textbf{51 25 114}
b \textbf{62 }
o\~{} \textbf{127 48 170.42}
Z \textbf{110 53.5 116 }
u \textbf{211 }
R \textbf{150 50 91 }
\_ \textbf{91}