diff options
author | Volker Hilsheimer <volker.hilsheimer@qt.io> | 2022-05-21 16:04:00 +0200 |
---|---|---|
committer | Volker Hilsheimer <volker.hilsheimer@qt.io> | 2022-05-25 07:27:31 +0200 |
commit | 52defa27a3e26f66854b0428dc3b3f36f51f5b6b (patch) | |
tree | 427a3a889da7c86106bf8dceea46530ce69596ae | |
parent | e7cd43feab9cb4c516151ad80a49ac87662c07cc (diff) |
Add engine specific documentation
Without going too much into implementation details, document which
engines are available, which dependencies they have, and which
engine-specific configuration parameters they support.
Change-Id: I2e787444a5841e1eaefc4ba156f1b71303b6dcab
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Axel Spoerl <axel.spoerl@qt.io>
-rw-r--r-- | src/tts/doc/src/qt6-changes.qdoc | 43 | ||||
-rw-r--r-- | src/tts/doc/src/qttexttospeech-engines.qdoc | 146 | ||||
-rw-r--r-- | src/tts/doc/src/qttexttospeech-index.qdoc | 1 | ||||
-rw-r--r-- | src/tts/qtexttospeech.cpp | 4 |
4 files changed, 156 insertions, 38 deletions
diff --git a/src/tts/doc/src/qt6-changes.qdoc b/src/tts/doc/src/qt6-changes.qdoc index cd4a37f..99b30fa 100644 --- a/src/tts/doc/src/qt6-changes.qdoc +++ b/src/tts/doc/src/qt6-changes.qdoc @@ -43,42 +43,12 @@ \section1 Available Engines - The following engines are available in Qt 6.4: + All engines that were available in Qt 5 are also available in Qt 6.4. For a + complete list of available engines in Qt 6.4, see \l{Qt TextToSpeech Engines}. - \table - \header - \li Engine name - \li Platform - \li Dependency - \row - \li sapi - \li Windows - \li Windows SDK (SAPI 5.3) - \row - \li winrt - \li Windows - \li Windows SDK (not available with MinGW) - \row - \li android - \li Android - \li TextToSpeech package - \row - \li ios - \li macOS 10.15+, iOS - \li macOS 10.15 SDK - \row - \li macos - \li macOS 10.14+ - \li macOS 10.15 SDK - \row - \li speechd - \li Linux - \li libspeechd 0.9 and speech-dispatcher daemon - \row - \li flite - \li Linux - \li flite 2.2 - \endtable + Engines can now receive additional configuration parameters. When constructing + a QTextToSpeech instance, pass a QVariantMap with engine-specific key/value + pairs. \section1 API changes @@ -87,8 +57,7 @@ \section2 The QTextToSpeech class - Existing code using the QTextToSpeech class continues to work as before. - The new {QTextToSpeech::engine} property allows changing of the engine on an + The new \l{QTextToSpeech::}{engine} property allows changing of the engine on an initialized QTextToSpeech object. \section2 The QVoice class diff --git a/src/tts/doc/src/qttexttospeech-engines.qdoc b/src/tts/doc/src/qttexttospeech-engines.qdoc new file mode 100644 index 0000000..a45c3aa --- /dev/null +++ b/src/tts/doc/src/qttexttospeech-engines.qdoc @@ -0,0 +1,146 @@ +/**************************************************************************** +** +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qttexttospeech-engines.html + \title Qt TextToSpeech Engines + \brief Engine specific documentation + + Qt TextToSpeech supports several engine implementations for different platforms, and + with different tradeoffs between capabilities, availability, and runtime cost. + + An engine can be selected when a QTextToSpeech instance is constructed, or on an already + instantiated object by setting the \l {QTextToSpeech::}{engine} property. If no engine + is specified, the preferred engine for the current platform will be used. Call + \l{QTextToSpeech::}{availableEngines()} to get the list of engines that can be used on + the current system. This will include a "mock" engine that is used for testing, and that + should not be deployed to target systems. + + When setting the engine, applications can pass a QVariantMap with key/value pairs of + engine specific parameters through to the engine. The following sections list the + configuration parameters supported for each engine. Parameters that are not supported + by the engine will be silently ignored. + + \section1 WinRT + + The "winrt" engine uses the APIs from the \l{https://docs.microsoft.com/en-us/uwp/api/windows.media.speechsynthesis} + {Windows.Media.SpeechSynthesis Namespace}. It requires a recent Windows SDK, and + is not available when using the MinGW compiler. The engine provides access to all + voices available for installation on current Windows versions. + + The implementation uses QAudioSink from \l{Qt Multimedia} to play the PCM data + stream generated by the synthesizer to an audio device. + + \table + \header + \li Name + \li Type + \li Remarks + \row + \li audioDevice + \li QAudioDevice + \li + \endtable + + \section1 SAPI + + The "sapi" engine uses the \l{https://docs.microsoft.com/en-us/previous-versions/windows/desktop/ms723627(v=vs.85)} + {SAPI 5.3} framework that is included in the Windows SDK. It provides a limited selection + of voices, with reduced quality compared to the "winrt" engine. + + The SAPI engine does not support any engine specific parameters. + + \section1 iOS + + The "ios" engine uses the \l{https://developer.apple.com/documentation/avfoundation/speech_synthesis?language=objc} + {AVFoundation} framework that is available on iOS devices and on macOS 10.15. The + documentation of the framework states support for macOS 10.14 as well, but by default + no voices are available on that platform. + + The iOS engine does not support any engine specific parameters. + + \section1 macOS + + The "macos" engine uses the \l{https://developer.apple.com/documentation/appkit/nsspeechsynthesizer?language=objc} + {NSSpeechDispatcher} framework from AppKit. It is only available on macOS systems, but + works out of the box on macOS 10.14. The number of available voices is limited compared + to the iOS engine. + + The macOS engine does not support any engine specific parameters. + + \section1 Android + + The "android" engine is the only engine available on the Android platform. It uses the + \l{https://developer.android.com/reference/android/speech/tts/TextToSpeech}{TextToSpeech} + package, which in turn supports multiple engine backends. + + \table + \header + \li Name + \li Type + \li Remarks + \row + \li androidEngine + \li QString + \li There is no API in Qt to get the list of installed engines. + \endtable + + + \section1 Flite + + The "flite" engine uses the \l{https://github.com/festvox/flite}{flite} synthesizer. + The engine's small footprint makes it particularly useful for embedded environments. + The plugin requires at least Flite 2.2, and uses \l QAudioSink from \l{Qt Multimedia} + to render the generated PCM data stream. + + The engine plugin searches for voice libraries in the directories listed in the + \c LD_LIBRARY_PATH environment variable, and falls back to search common library + locations such as \c {/usr/lib}, \c {/usr/lib64}, and \c {/usr/lib/x86_64-linux-gnu}. + + If Flite is used as a static library, then the desired voice libraries also need to + be statically linked into the engine plugin. There is currently not build system API + implemented for selecting such voice libraries when configuring Qt. + + \table + \header + \li Name + \li Type + \li Remarks + \row + \li audioDevice + \li QAudioDevice + \li + \endtable + + \section1 speech-dispatcher + + The "speechd" engine communicates with the + \l{https://htmlpreview.github.io/?https://github.com/brailcom/speechd/blob/master/doc/speech-dispatcher.html#Top} + {speech-dispatcher} daemon, and requires at least libspeechd 0.9. + + The speech-dispatcher engine does not support any engine specific parameters. +*/ diff --git a/src/tts/doc/src/qttexttospeech-index.qdoc b/src/tts/doc/src/qttexttospeech-index.qdoc index 94693c7..6f63a1d 100644 --- a/src/tts/doc/src/qttexttospeech-index.qdoc +++ b/src/tts/doc/src/qttexttospeech-index.qdoc @@ -80,5 +80,6 @@ \li \l{Qt TextToSpeech QML Types}{QML Types} \li \l{Qt TextToSpeech C++ Classes}{C++ Classes} \li \l{Qt TextToSpeech Examples}{Examples} + \li \l{Qt TextToSpeech Engines}{Engine Documentation} \endlist */ diff --git a/src/tts/qtexttospeech.cpp b/src/tts/qtexttospeech.cpp index ef41e8e..a8b1721 100644 --- a/src/tts/qtexttospeech.cpp +++ b/src/tts/qtexttospeech.cpp @@ -289,7 +289,8 @@ QTextToSpeech::QTextToSpeech(const QString &engine, QObject *parent) If \a engine is empty, the default engine plug-in is used. The default engine is platform-specific. Which key/value pairs in \a params are supported - depends on the engine. Unsupported entries will be ignored. + depends on the engine. See \l{Qt TextToSpeech Engines}{the engine documentation} + for details. Unsupported entries will be ignored. If the engine initializes correctly, the \l state of the engine will be set to QTextToSpeech::Ready. If the plugin fails to load, or if the engine fails to @@ -331,6 +332,7 @@ QTextToSpeech::~QTextToSpeech() \return whether \a engine could be set successfully. Which key/value pairs in \a params are supported depends on the engine. + See \l{Qt TextToSpeech Engines}{the engine documentation} for details. Unsupported entries will be ignored. */ bool QTextToSpeech::setEngine(const QString &engine, const QVariantMap ¶ms) |