chrome/common/extensions/api/hotword_private.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // The <code>chrome.hotwordPrivate</code> API allows extensions to access and
   6 // mutate the preference for enabling hotword search. It also provides
   7 // information on whether the hotword search is available. This API provides an
   8 // event interface to transmit to the extension a signal that the preference fo
   9 // hotword search has change.
  10 //
  11 // For an FYI, visit http://goo.gl/AyHbkH
  12
  13 namespace hotwordPrivate {
  14
  15   dictionary StatusDetails {
  16     // Whether the hotword preference has been set.
  17     boolean enabledSet;
  18
  19     // If the hotword extension is enabled. Will always be false if |available|
  20     // is false.
  21     boolean enabled;
  22
  23     // Whether the hotword extension is available to be enabled
  24     // Optional field, only valid when getStatus() is called with
  25     // |getOptionalFields| = true. Otherwise, set to false.
  26     boolean available;
  27
  28     // Whether always-on is available to be enabled
  29     // Optional field, only valid when getStatus() is called with
  30     // |getOptionalFields| = true. Otherwise, set to false.
  31     boolean alwaysOnAvailable;
  32
  33     // Whether the sound of "Ok, Google" plus a few seconds before is sent
  34     // back to Google.
  35     boolean audioLoggingEnabled;
  36
  37     // Whether always-on hotwording is enabled.
  38     boolean alwaysOnEnabled;
  39
  40     // Whether training mode is enabled.
  41     boolean trainingEnabled;
  42
  43     // Whether the user corresponding to this profile is the active user.
  44     boolean userIsActive;
  45
  46     // Whether hotword hardware is available if requested.
  47     boolean hotwordHardwareAvailable;
  48   };
  49
  50   dictionary LaunchState {
  51     // TODO(kcarattini): Consider adding more variables here,
  52     // such as the available state of the hotword service.
  53
  54     // The mode that the Hotword Audio Verification app was launched in.
  55     long launchMode;
  56   };
  57
  58   dictionary LogDetails {
  59     // Number of audio channels. i.e. 1 = mono, 2 = stereo
  60     long channels;
  61
  62     // Bytes per sample per channel.
  63     long bytes_per_sample;
  64
  65     // Sample rate. Usually 32000 or 44100, but may be any integer.
  66     long sample_rate;
  67
  68     // Array containing audio data. Length is
  69     // (channels * bytes_per_sample * sample_rate * <seconds of log>).
  70     ArrayBuffer buffer;
  71   };
  72
  73   dictionary AudioHistoryState {
  74     // Whether the call to set or get this state was successful.
  75     boolean success;
  76
  77     // The current value of the audio history opt-in state after this
  78     // call.
  79     boolean enabled;
  80   };
  81
  82   // The type of the recognized hotword. Right now it only has 'search' but
  83   // could be expanded to other types of actions in the future.
  84   enum HotwordType { search };
  85
  86   callback GenericDoneCallback = void ();
  87   callback LaunchStateCallback = void(LaunchState result);
  88   callback LocalizeStringsCallback = void(object result);
  89   callback StatusDetailsCallback = void(StatusDetails result);
  90   callback AudioHistoryCallback = void(AudioHistoryState result);
  91
  92   interface Functions {
  93     // Sets the current enabled state of hotword search.
  94     // True: enable hotword search. False: disable hotword search.
  95     static void setEnabled(boolean state,
  96                            optional GenericDoneCallback callback);
  97
  98     // Retrieves the current state of hotword search.
  99     // The result is put into a StatusDetails object.
 100     // |getOptionalFields|: If true, fills in fields tagged as optional in
 101     // StatusDetails with valid values. These fields are not valid by default
 102     // since their current implementations may cause blocking operations.
 103     static void getStatus(optional boolean getOptionalFields,
 104                           StatusDetailsCallback callback);
 105
 106     // Retrieves a dictionary mapping names to localized resource strings.
 107     static void getLocalizedStrings(LocalizeStringsCallback callback);
 108
 109     // Sets the current enabled state of audio logging in the extension.
 110     // True: logging enabled. False: no logging.
 111     static void setAudioLoggingEnabled(boolean state,
 112                                        optional GenericDoneCallback callback);
 113
 114     // Sets the current enabled state of hotword-always-on-search pref.
 115     // True: enable hotword always on search.
 116     // False: disable hotword always on search.
 117     static void setHotwordAlwaysOnSearchEnabled(boolean state,
 118         optional GenericDoneCallback callback);
 119
 120     // Sets the current state of the browser-requested hotword session.
 121     static void setHotwordSessionState(boolean started,
 122                                        optional GenericDoneCallback callback);
 123
 124     // Notifies that a hotword has been recognized in the browser-requested
 125     // hotword session.
 126     static void notifyHotwordRecognition(HotwordType type,
 127                                          optional LogDetails log,
 128                                          optional GenericDoneCallback callback);
 129
 130     // Retrieves the state that the Hotword Audio Verification app was
 131     // launched in. The result is put into a LaunchState object.
 132     static void getLaunchState(LaunchStateCallback callback);
 133
 134     // Starts the speaker model training.
 135     static void startTraining(optional GenericDoneCallback callback);
 136
 137     // Finalizess the speaker model.
 138     static void finalizeSpeakerModel(optional GenericDoneCallback callback);
 139
 140     // Notifies that the speaker model has been saved.
 141     static void notifySpeakerModelSaved(optional GenericDoneCallback callback);
 142
 143     // Stops the speaker model training.
 144     static void stopTraining(optional GenericDoneCallback callback);
 145
 146     // Sets the audio history opt-in state.
 147     static void setAudioHistoryEnabled(boolean enabled,
 148                                        optional AudioHistoryCallback callback);
 149
 150     // Gets the audio history opt-in state.
 151     static void getAudioHistoryEnabled(optional AudioHistoryCallback callback);
 152
 153     // Sends the result of whether a speaker model exists to the browser.
 154     static void speakerModelExistsResult(boolean exists,
 155                                          optional GenericDoneCallback callback);
 156   };
 157
 158   interface Events {
 159     // Fired when the hotword detector enabled state should be changed.
 160     // This can be from various sources, e.g. a pref change or training
 161     // a speaker model.
 162     static void onEnabledChanged();
 163
 164     // Fired when the browser wants to start a hotword session.
 165     static void onHotwordSessionRequested();
 166
 167     // Fired when the browser wants to stop the requested hotword session.
 168     static void onHotwordSessionStopped();
 169
 170     // Fired when the speaker model should be finalized.
 171     static void onFinalizeSpeakerModel();
 172
 173     // Fired when the speaker model has been saved.
 174     static void onSpeakerModelSaved();
 175
 176     // Fired when a hotword has triggered.
 177     static void onHotwordTriggered();
 178
 179     // Fired when the speaker model should be deleted.
 180     static void onDeleteSpeakerModel();
 181
 182     // Fired when the browser wants to find out whether the speaker model
 183     // exists.
 184     static void onSpeakerModelExists();
 185
 186     // Fired when the microphone state changes.
 187     static void onMicrophoneStateChanged(boolean enabled);
 188   };
 189 };