Merge pull request #112 from pettarin/devel

Docs for v1.6.0

aeneas/cewsubprocess.py

@@ -36,7 +36,7 @@
 #. https://groups.google.com/d/msg/aeneas-forced-alignment/NLbtSRf2_vg/mMHuTQiFEgAJ
 #. https://sourceforge.net/p/espeak/mailman/message/34861696/
 
-.. warning:: This module might be removed in a future version
+.. warning:: This module might be removed in a future version.
 
 .. versionadded:: 1.5.0
 """

aeneas/runtimeconfiguration.py

@@ -57,18 +57,20 @@ class RuntimeConfiguration(Configuration):
     otherwise, generate an error if the user attempts
     to use a language not listed.
 
-    Default: ``True``.
+    Default: ``False``.
 
     .. versionadded:: 1.4.1
     """
 
     C_EXTENSIONS = "c_extensions"
     """
-    If ``True`` and Python C extensions are available, use them.
-    Otherwise, use pure Python code.
+    If ``True`` and the Python C/C++ extensions
+    are available, use them.
+    Otherwise, use the pure Python code.
 
     This option is equivalent to
-    setting ``CDTW``, ``CEW``, and ``CMFCC`` to ``True`` at once.
+    setting ``CDTW``, ``CEW``, ``CFW``,
+    and ``CMFCC`` to ``True`` or ``False`` at once.
 
     Default: ``True``.
 
@@ -77,8 +79,9 @@ class RuntimeConfiguration(Configuration):
 
     CDTW = "cdtw"
     """
-    If ``True`` and Python C extension ``cdtw`` is available, use it.
-    Otherwise, use pure Python code.
+    If ``True`` and the Python C extension ``cdtw``
+    is available, use it.
+    Otherwise, use the pure Python code.
 
     Default: ``True``.
 
@@ -87,8 +90,9 @@ class RuntimeConfiguration(Configuration):
 
     CEW = "cew"
     """
-    If ``True`` and Python C extension ``cew`` is available, use it.
-    Otherwise, use pure Python code.
+    If ``True`` and the Python C extension ``cew``
+    is available, use it.
+    Otherwise, use the pure Python code.
 
     Default: ``True``.
 
@@ -97,8 +101,9 @@ class RuntimeConfiguration(Configuration):
 
     CFW = "cfw"
     """
-    If ``True`` and Python C extension ``cfw`` is available, use it.
-    Otherwise, use pure Python code.
+    If ``True`` and the Python C++ extension ``cfw``
+    is available, use it.
+    Otherwise, use the pure Python code.
 
     Default: ``True``.
 
@@ -107,7 +112,10 @@ class RuntimeConfiguration(Configuration):
 
     CEW_SUBPROCESS_ENABLED = "cew_subprocess_enabled"
     """
-    If ``True``, calls to ``aeneas.cew`` will be done via ``subprocess``.
+    If ``True``, calls to ``aeneas.cew``
+    will be done via ``subprocess``, using the
+    :class:`~aeneas.cewsubprocess.CEWSubprocess`
+    helper class.
 
     Default: ``False``.
 
@@ -128,8 +136,9 @@ class RuntimeConfiguration(Configuration):
 
     CMFCC = "cmfcc"
     """
-    If ``True`` and Python C extension ``cmfcc`` is available, use it.
-    Otherwise, use pure Python code.
+    If ``True`` and the Python C extension ``cmfcc``
+    is available, use it.
+    Otherwise, use the pure Python code.
 
     Default: ``True``.
 
@@ -371,6 +380,10 @@ class RuntimeConfiguration(Configuration):
     Important: this feature is experimental, use at your own risk.
     It is recommended not to use this TTS at word-level granularity,
     as it will create many requests, hence it will be expensive.
+    If you still want to use it, you can enable
+    the TTS caching mechanism by setting
+    :data:`~aeneas.runtimeconfiguration.RuntimeConfiguration.TTS_CACHE`
+    to ``True``.
 
     .. versionadded:: 1.5.0
     """
@@ -384,6 +397,10 @@ class RuntimeConfiguration(Configuration):
     Important: this feature is experimental, use at your own risk.
     It is recommended not to use this TTS at word-level granularity,
     as it will create many requests, hence it will be expensive.
+    If you still want to use it, you can enable
+    the TTS caching mechanism by setting
+    :data:`~aeneas.runtimeconfiguration.RuntimeConfiguration.TTS_CACHE`
+    to ``True``.
 
     .. versionadded:: 1.5.0
     """
@@ -458,22 +475,29 @@ class RuntimeConfiguration(Configuration):
     The default value is
     :data:`~aeneas.synthesizer.Synthesizer.ESPEAK` (``espeak``)
     which will use the built-in eSpeak TTS wrapper.
+    You might need to provide a ``/full/path/to/your/espeak`` value
+    to the
+    :data:`~aeneas.runtimeconfiguration.RuntimeConfiguration.TTS_PATH`
+    parameter if the command ``espeak`` is not available in
+    one of the directories listed in your ``PATH`` environment variable.
 
     Specify the value
     :data:`~aeneas.synthesizer.Synthesizer.ESPEAKNG` (``espeak-ng``)
-    to use the eSpeak-ng TTS wrapper;
-    you might need to provide the ``espeak-ng`` or ``/full/path/to/your/espeak-ng`` value
+    to use the eSpeak-ng TTS wrapper.
+    You might need to provide a ``/full/path/to/your/espeak-ng`` value
     to the
     :data:`~aeneas.runtimeconfiguration.RuntimeConfiguration.TTS_PATH`
-    parameter.
+    parameter if the command ``espeak-ng`` is not available in
+    one of the directories listed in your ``PATH`` environment variable.
 
     Specify the value
     :data:`~aeneas.synthesizer.Synthesizer.FESTIVAL` (``festival``)
-    to use the built-in Festival TTS wrapper;
-    you might need to provide the ``text2wave`` or ``/full/path/to/your/text2wave`` value
+    to use the built-in Festival TTS wrapper.
+    You might need to provide a ``/full/path/to/your/text2wave`` value
     to the
     :data:`~aeneas.runtimeconfiguration.RuntimeConfiguration.TTS_PATH`
-    parameter.
+    parameter if the command ``text2wave`` is not available in
+    one of the directories listed in your ``PATH`` environment variable.
 
     Specify the value
     :data:`~aeneas.synthesizer.Synthesizer.NUANCE` (``nuance``)
@@ -503,7 +527,8 @@ class RuntimeConfiguration(Configuration):
 
     The cache files will be removed after the synthesis is compled.
 
-    This option is useful when calling TTS engines via subprocess
+    This option is useful when calling TTS engines,
+    via subprocess or remote APIs,
     on text files with many identical fragments,
     for example when aligning at word-level granularity.
 
@@ -539,6 +564,8 @@ class RuntimeConfiguration(Configuration):
     If you specify this value, it will override the default voice code
     associated with the language of your text.
 
+    Default: ``None``.
+
     .. versionadded:: 1.5.0
     """
 
@@ -672,6 +699,7 @@ class RuntimeConfiguration(Configuration):
 
     # NOTE not using aliases just not to become confused
     #      about external (user rconf) and internal (lib code) key names
+    #      although the functionality might be useful in the future
     FIELDS = [
         (ALLOW_UNLISTED_LANGUAGES, (False, bool, [])),
 
@@ -796,7 +824,7 @@ def tts(self):
         :data:`~aeneas.runtimeconfiguration.RuntimeConfiguration.TTS`
         key stored in this configuration object.
 
-        :rtype: str
+        :rtype: string
         """
         return self[self.TTS]
 
@@ -807,7 +835,7 @@ def tts_path(self):
         :data:`~aeneas.runtimeconfiguration.RuntimeConfiguration.TTS_PATH`
         key stored in this configuration object.
 
-        :rtype: str
+        :rtype: string
         """
         return self[self.TTS_PATH]
 

aeneas/ttswrappers/festivalttswrapper.py

@@ -43,9 +43,11 @@ class FESTIVALTTSWrapper(BaseTTSWrapper):
     A wrapper for the ``Festival`` TTS engine.
 
     This wrapper supports calling the TTS engine
-    via ``subprocess`` or via Python C extension.
+    via ``subprocess`` or via Python C++ extension.
 
-    .. note:: The latter call method is experimental and probably works only on Linux at the moment.
+    .. warning::
+        The C++ extension call is experimental and
+        probably works only on Linux at the moment.
 
     In abstract terms, it performs one or more calls like ::
 

debian/changelog

@@ -5,12 +5,13 @@ aeneas (1.6.0) stable; urgency=medium
   * Added eSpeak-ng TTS wrapper
   * Added caching audio files for faster synthesis
   * The TTS engine can be selected per-level (text in multilevel format)
+  * Added cfw Python C++ extension for Festival (disabled by default)
   * Python C extension compilation can be disabled in setup.py via env vars
   * All Python code formatted according to PEP 8 (-E501)
   * All source files have AGPLv3 header
   * Code, test, and documentation improvements
 
- -- alberto <alberto@nievo>  Mon, 19 Sep 2016 14:35:01 +0200
+ -- alberto <alberto@nievo>  Mon, 26 Sep 2016 01:02:03 +0200
 
 aeneas (1.5.1) stable; urgency=medium
 

docs/source/changelog.rst

@@ -20,7 +20,7 @@ v1.6.0 (2016-09-26)
 #. When working on multilevel sync, user can specify a different TTS for each level
 #. Added an optional TTS caching mechanism to reduce subprocess/API calls to the TTS engine (closes #87)
 #. Added wrapper for eSpeak-ng (subprocess only)
-#. Added ``aeneas.cfw`` Python C++ Extension to call ``Festival`` via its C++ API, disabled by default (closes #109)
+#. Added ``cfw`` Python C++ Extension to call ``Festival`` via its C++ API, disabled by default (closes #106)
 #. Unified unit tests for eSpeak, eSpeak-ng, and Festival
 #. Python C extension compilation can be disabled/forced in setup.py via env vars
 #. Added check on head/process/tail length which should not exceed the audio file length (closes #80)