// Copyright 2017 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.

library fuchsia.speech;

[Discoverable]
protocol SpeechToText {
    // Starts capturing speech from the microphone.
    BeginCapture(TranscriptionListener transcription_listener);

    // Begins hotword detection. Detected hotword utterances are reported on the
    // given listener.
    ListenForHotword(HotwordListener hotword_listener);
};

// Represents an active transcription session. Either side may close this
// interface to indicate that transcription should stop. If the transcription is
// unexpectedly closed before |OnReady| is called, the implementer should treat
// it as an error (in such cases, |OnError| is called).
protocol TranscriptionListener {
    // Indicates that capture has begun. Prior to this, parts of the system may
    // not have been initialized and audio may have been dropped. No calls to
    // |OnTranscriptUpdate| will occur before |OnReady| is called.
    OnReady();

    // Receives updated transcripts. Each call receives the most likely
    // transcription of the entire utterance at that time. Previously transcribed
    // text may mutate in response to later input.
    OnTranscriptUpdate(string spoken_text);

    // Provides periodic updates on the user's speech signal power, when the
    // microphone is open and streaming to the backend.
    // |speech_level| is instantaneous speech power, in decibels (negative).
    OnSpeechLevelUpdate(float32 speech_level);

    // An error occurred before or during transcription. Depending on the nature
    // of the error, this may occur before |OnReady| is called, and |OnReady| may
    // never be called. This binding will be closed immediately after sending this
    // message.
    OnError();
};

// Listens for hotwords. Each detected hotword utterance triggers |OnHotword|.
// Closure of this handle by the speech service indicates an error.
protocol HotwordListener {
    // Indicates that capture has begun. Prior to this, parts of the system may
    // not have been initialized and audio may have been dropped. No calls to
    // |OnHotword| will occur before |OnReady| is called.
    OnReady();

    // Called for each detected hotword utterance.
    OnHotword();
};