// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=11)
library fuchsia.accessibility.tts;

using fuchsia.intl;

/// Error codes for TTS operations.
type Error = strict enum {
    /// The underlying TTS engine does not support this operation.
    NOT_IMPLEMENTED = 1;
    /// The value is out of range for a particular TTS parameter.
    OUT_OF_RANGE = 2;
    /// The operation is impossible to be completed.
    BAD_STATE = 3;
    /// This operation can not be completed because the TTS service is in use.
    BUSY = 4;
};

/// Parameters of a voice.
/// TODO(https://fxbug.dev/42090141): Add extra voice parameters such as speech rate and  pitch.
type VoiceParameters = table {
    /// The current selected language.
    1: language fuchsia.intl.LocaleId;
};

/// An utterance holds information about its message and how it should be spoken.
type Utterance = table {
    /// The message to be spoken.
    /// Clients should pay attention to the FIDL maximum size for a message,
    /// splitting when necessary into several utterances.
    1: message string;
    /// Parameters that control the speech output.
    2: params VoiceParameters;
};

/// An interface to produce speech output.
/// Assistive technology use an Engine to start producing speech output and
/// set configuration parameters that control the speech.
/// TODO(https://fxbug.dev/42091290): Implement pause, stop and resume.
@discoverable
closed protocol Engine {
    /// Enqueues  an utterance to be spoken. Speech is not started until Speak
    /// is called.
    strict Enqueue(struct {
        utterance Utterance;
    }) -> () error Error;

    /// Speaks all enqueued utterances. The method returns the value when they
    /// are all finished playing.
    strict Speak() -> () error Error;

    /// Cancels current speech and also empties the queue.
    strict Cancel() -> ();
};