// Copyright 2021 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// The <code>chrome.speechRecognitionPrivate</code> API allows internal
// extensions to use either network-based or on-device speech recognition.
[platforms=("chromeos"), implemented_in="chrome/browser/ash/extensions/speech/speech_recognition_private_api.h"]

namespace speechRecognitionPrivate {
  // Possible types of speech recognition.
  enum SpeechRecognitionType {
    onDevice,
    network
  };

  // Interface for an onStop event.
  dictionary SpeechRecognitionStopEvent {
    // Optional client ID.
    long? clientId;
  };

  // Interface for a speech recognition result event.
  dictionary SpeechRecognitionResultEvent {
    // Optional client ID.
    long? clientId;
    // The recognized phrase or sentence.
    DOMString transcript;
    // Whether the result is a final or an interim result.
    boolean isFinal;
  };

  // Interface for a speech recognition error event.
  dictionary SpeechRecognitionErrorEvent {
    // Optional client ID.
    long? clientId;
    // A message describing the error.
    DOMString message;
  };

  // Interface for options used when starting speech recognition.
  dictionary StartOptions {
    // An optional ID to specify the client.
    long? clientId;
    // The locale, in BCP-47 format e.g. "en-US", to use for speech recognition.
    DOMString? locale;
    // Whether interim speech results should be returned.
    boolean? interimResults;
  };

  // Interface for options used when stopping speech recognition.
  dictionary StopOptions {
    // An optional ID to specify the client. This must match the clientId
    // used when starting speech recognition to work as intended.
    long? clientId;
  };

  // Called when speech recognition has begun listening to the user's audio.
  // The callback's parameter specifies which type of speech recognition
  // is being used.
  callback OnStartCallback = void(SpeechRecognitionType type);
  // Called when speech recognition has stopped listening to the user's audio.
  callback OnStopCallback = void();

  interface Functions {
    // Starts listening to audio from the user. The callback is invoked when
    // speech recognition has started. If speech recognition is already active
    // when calling start(), the callback is run with an error.
    static void start(
        StartOptions options,
        OnStartCallback callback);

    // Stops listening to audio from the user. The callback is invoked when
    // speech recognition has stopped. If speech recognition has already stopped
    // when calling stop(), the callback is run with an error.
    static void stop(
        StopOptions options,
        OnStopCallback callback);
  };

  interface Events {
    // Fired when speech recognition stops.
    static void onStop(SpeechRecognitionStopEvent event);
    // Fired when a speech recognition result is returned.
    static void onResult(SpeechRecognitionResultEvent event);
    // Fired when a speech recognition error occurs.
    static void onError(SpeechRecognitionErrorEvent event);
  };
};