/usr/bin/phonemize

usage: phonemize [-h] [-V] [-v | -q] [-j <int>] [-o <file>] [--prepend-text [<str>]]
                 [--preserve-empty-lines] [-b <str>] [-L] [-l <str|file>] [-p <str>] [-w <str>]
                 [-s <str>] [--strip] [--espeak-library <library>] [--tie [<chr>]] [--with-stress]
                 [--language-switch {keep-flags,remove-flags,remove-utterance}]
                 [--words-mismatch {ignore,warn,remove}] [--festival-executable <executable>]
                 [--preserve-punctuation] [--punctuation-marks <str>]
                 [--punctuation-marks-is-regex]
                 [<file>]

Multilingual text to phonemes converter

The 'phonemize' program allows simple phonemization of words and texts
in many language using four backends: espeak, espeak-mbrola, festival
and segments.

- espeak is a text-to-speech software supporting multiple languages
  and IPA (International Phonetic Alphabet) output. See
  http://espeak.sourceforge.net or
  https://github.com/espeak-ng/espeak-ng

- espeak-mbrola uses the SAMPA phonetic alphabet, it requires mbrola to be
  installed as well as additional mbrola voices. It does not support word or
  syllable tokenization. See
  https://github.com/espeak-ng/espeak-ng/blob/master/docs/mbrola.md

- festival is also a text-to-speech software. Currently only American
  English is supported and festival uses a custom phoneset
  (http://www.festvox.org/bsv/c4711.html), but festival is the only
  backend supporting tokenization at the syllable
  level. See http://www.cstr.ed.ac.uk/projects/festival

- segments is a Unicode tokenizer that build a phonemization from a
  grapheme to phoneme mapping provided as a file by the user. See
  https://github.com/cldf/segments.

See the '--list-languages' option below for details on the languages
supported by each backend.

options:
  -h, --help            show this help message and exit
  -V, --version         show version information and exit.
  -v, --verbose         write all log messages to stderr (displays only warnings by default).
  -q, --quiet           do not display any log message, even warnings.
  -j <int>, --njobs <int>
                        number of parallel jobs, default is 1.

input/output:
  <file>                input text file to phonemize, if not specified read from stdin.
  -o <file>, --output <file>
                        output text file to write, if not specified write to stdout.
  --prepend-text [<str>]
                        prepend each line of the phonemized output text with its matching input
                        text. If a string is specified as option value, use it as field separator,
                        else use one of "|", "||", "|||", "||||" by selecting the first one that
                        is not configured as a token separator (see -p/-s/-w options).
  --preserve-empty-lines
                        preserve the empty lines in the phonemized output, default is to remove
                        them.

backends:
  -b <str>, --backend <str>
                        the phonemization backend, must be 'espeak', 'espeak-mbrola', 'festival'
                        or 'segments'. Default is 'espeak'.
  -L, --list-languages  list available languages (and exit) for the specified backend, or for all
                        backends if none selected.

language:
  -l <str|file>, --language <str|file>
                        the language code of the input text, use '--list-languages' for a list of
                        supported languages. Default is en-us.

token separators:
  -p <str>, --phone-separator <str>
                        phone separator, default is "".
  -w <str>, --word-separator <str>
                        word separator, not valid for espeak-mbrola backend, default is " ".
  -s <str>, --syllable-separator <str>
                        syllable separator, only valid for festival backend, this option has no
                        effect if another backend is used. Default is "".
  --strip               removes the end separators in phonemized tokens.

specific to espeak backend:
  --espeak-library <library>
                        the path to the espeak shared library to use (*.so on Linux, *.dylib on
                        Mac and *.dll on Windows, useful to overload the default espeak version
                        installed on the system). Default to None. This path can also be specified
                        using the PHONEMIZER_ESPEAK_LIBRARY environment variable.
  --tie [<chr>]         when the option is set, use a tie character within multi-letter phoneme
                        names, default to U+361 (as in d͡ʒ), 'z' means ZWJ character, only
                        compatible with espeak>1.48 and incompatible with the -p/--phone-separator
                        option
  --with-stress         when the option is set, the stresses on phonemes are present (stresses
                        characters are ˈ'ˌ). By default stresses are removed.
  --language-switch {keep-flags,remove-flags,remove-utterance}
                        espeak can pronounce some words in another language (typically English)
                        when phonemizing a text. This option setups the policy to use when such a
                        language switch occurs. Three values are available: 'keep-flags' (the
                        default), 'remove-flags' or 'remove-utterance'. The 'keep-flags' policy
                        keeps the language switching flags, for example (en) or (jp), in the
                        output. The 'remove-flags' policy removes them and the 'remove-utterance'
                        policy removes the whole line of text including a language switch.
  --words-mismatch {ignore,warn,remove}
                        espeak can join two consecutive words or drop some words, yielding a word
                        count mismatch between orthographic and phonemized text. This option
                        setups the policy to use when such a words count mismatch occurs. Three
                        values are available: 'ignore' (the default) which do nothing, 'warn'
                        which issue a warning for each mismatched line, and 'remove' which remove
                        the mismatched lines from the output.

specific to festival backend:
  --festival-executable <executable>
                        the path to the festival executable to use (useful to overload the default
                        festival installed on the system). Default to None. This path can also be
                        specified using the PHONEMIZER_FESTIVAL_EXECUTABLE environment variable.

punctuation processing:
  not available for espeak-mbrola backend

  --preserve-punctuation
                        preserve the punctuation marks in the phonemized output, default is to
                        remove them.
  --punctuation-marks <str>
                        the marks to consider during punctuation processing (either for removal or
                        preservation). Default is ;:,.!?¡¿—…"«»“”(){}[].
  --punctuation-marks-is-regex
                        interpret the '--punctuation-marks' parameter as a regex. Default is to
                        interpret as a string.

Examples:

* Phonemize a US English text with espeak

   $ echo 'hello world' | phonemize -l en-us -b espeak
   həloʊ wɜːld

* Phonemize a US English text with festival

   $ echo 'hello world' | phonemize -l en-us -b festival
   hhaxlow werld

* Phonemize a Japanese text with segments

  $ echo 'konnichiwa tsekai' | phonemize -l japanese -b segments
  konnitʃiwa t͡sekai

* Add a separator between phones

  $ echo 'hello world' | phonemize -l en-us -b festival -p '-' --strip
  hh-ax-l-ow w-er-l-d

* Phonemize some French text file using espeak

  $ phonemize -l fr-fr -b espeak text.txt -o phones.txt