// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page qttexttospeech-engines.html
    \title Qt TextToSpeech Engines
    \brief Engine specific documentation

    \l{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 Darwin

    The "darwin" 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 Darwin 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.

    \note The "macos" engine does not have the \l{QTextToSpeech::Capabilities}{Synthesize}
    capability. The "darwin" engine is the default and preferred engine on all macOS and
    iOS systems supported by Qt. The macOS engine should not be used anymore and will be
    removed in Qt 6.8.

    \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.

    \note The "android" engine does not have the \l{QTextToSpeech::Capabilities}
    {PauseResume} capability.

    \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.

    \note The speech-dispatcher engine does not have the \l {QTextToSpeech::Capabilities}
    {WordByWordProgress} or \l {QTextToSpeech::Capabilities}{Synthesize} capabilities.

    The speech-dispatcher engine does not support any engine specific parameters.
*/
