// 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]
interface SpeechToText {
  // Starts capturing speech from the microphone.
  1: BeginCapture(TranscriptionListener transcription_listener);

  // Begins hotword detection. Detected hotword utterances are reported on the
  // given listener.
  2: 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).
interface 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.
  1: 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.
  2: 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).
  4: 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.
  3: OnError();
};

// Listens for hotwords. Each detected hotword utterance triggers |OnHotword|.
// Closure of this handle by the speech service indicates an error.
interface 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.
  1: OnReady();

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