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     boolean available;
  25
  26     // Whether the sound of "Ok, Google" plus a few seconds before is sent
  27     // back to Google.
  28     boolean audioLoggingEnabled;
  29
  30     // Whether experimental hotwording functionality is enabled. Mirrors the
  31     // "enable-experimental-hotwording" flag.
  32     boolean experimentalHotwordEnabled;
  33
  34     // Whether always-on hotwording is enabled.
  35     boolean alwaysOnEnabled;
  36
  37     // Whether training mode is enabled.
  38     boolean trainingEnabled;
  39
  40     // Whether the user corresponding to this profile is the active user.
  41     boolean userIsActive;
  42   };
  43
  44   dictionary LaunchState {
  45     // TODO(kcarattini): Consider adding more variables here,
  46     // such as the available state of the hotword service.
  47
  48     // The mode that the Hotword Audio Verification app was launched in.
  49     long launchMode;
  50   };
  51
  52   dictionary LogDetails {
  53     // Number of audio channels. i.e. 1 = mono, 2 = stereo
  54     long channels;
  55
  56     // Bytes per sample per channel.
  57     long bytes_per_sample;
  58
  59     // Sample rate. Usually 32000 or 44100, but may be any integer.
  60     long sample_rate;
  61
  62     // Array containing audio data. Length is
  63     // (channels * bytes_per_sample * sample_rate * <seconds of log>).
  64     ArrayBuffer buffer;
  65   };
  66
  67   dictionary AudioHistoryState {
  68     // Whether the call to set or get this state was successful.
  69     boolean success;
  70
  71     // The current value of the audio history opt-in state after this
  72     // call.
  73     boolean enabled;
  74   };
  75
  76   // The type of the recognized hotword. Right now it only has 'search' but
  77   // could be expanded to other types of actions in the future.
  78   enum HotwordType { search };
  79
  80   callback GenericDoneCallback = void ();
  81   callback LaunchStateCallback = void(LaunchState result);
  82   callback LocalizeStringsCallback = void(object result);
  83   callback StatusDetailsCallback = void(StatusDetails result);
  84   callback AudioHistoryCallback = void(AudioHistoryState result);
  85
  86   interface Functions {
  87     // Sets the current enabled state of hotword search.
  88     // True: enable hotword search. False: disable hotword search.
  89     static void setEnabled(boolean state,
  90                            optional GenericDoneCallback callback);
  91
  92     // Retrieves the current state of hotword search.
  93     // The result is put into a StatusDetails object.
  94     static void getStatus(StatusDetailsCallback callback);
  95
  96     // Retrieves a dictionary mapping names to localized resource strings.
  97     static void getLocalizedStrings(LocalizeStringsCallback callback);
  98
  99     // Sets the current enabled state of audio logging in the extension.
 100     // True: logging enabled. False: no logging.
 101     static void setAudioLoggingEnabled(boolean state,
 102                                        optional GenericDoneCallback callback);
 103
 104     // Sets the current enabled state of hotword-always-on-search pref.
 105     // True: enable hotword always on search.
 106     // False: disable hotword always on search.
 107     static void setHotwordAlwaysOnSearchEnabled(boolean state,
 108         optional GenericDoneCallback callback);
 109
 110     // Sets the current state of the browser-requested hotword session.
 111     static void setHotwordSessionState(boolean started,
 112                                        optional GenericDoneCallback callback);
 113
 114     // Notifies that a hotword has been recognized in the browser-requested
 115     // hotword session.
 116     static void notifyHotwordRecognition(HotwordType type,
 117                                          optional LogDetails log,
 118                                          optional GenericDoneCallback callback);
 119
 120     // Retrieves the state that the Hotword Audio Verification app was
 121     // launched in. The result is put into a LaunchState object.
 122     static void getLaunchState(LaunchStateCallback callback);
 123
 124     // Starts the speaker model training.
 125     static void startTraining(optional GenericDoneCallback callback);
 126
 127     // Finalizess the speaker model.
 128     static void finalizeSpeakerModel(optional GenericDoneCallback callback);
 129
 130     // Notifies that the speaker model has been saved.
 131     static void notifySpeakerModelSaved(optional GenericDoneCallback callback);
 132
 133     // Stops the speaker model training.
 134     static void stopTraining(optional GenericDoneCallback callback);
 135
 136     // Sets the audio history opt-in state.
 137     static void setAudioHistoryEnabled(boolean enabled,
 138                                        optional AudioHistoryCallback callback);
 139
 140     // Gets the audio history opt-in state.
 141     static void getAudioHistoryEnabled(optional AudioHistoryCallback callback);
 142   };
 143
 144   interface Events {
 145     // Fired when the hotword detector enabled state should be changed.
 146     // This can be from various sources, e.g. a pref change or training
 147     // a speaker model.
 148     static void onEnabledChanged();
 149
 150     // Fired when the browser wants to start a hotword session.
 151     static void onHotwordSessionRequested();
 152
 153     // Fired when the browser wants to stop the requested hotword session.
 154     static void onHotwordSessionStopped();
 155
 156     // Fired when the speaker model should be finalized.
 157     static void onFinalizeSpeakerModel();
 158
 159     // Fired when the speaker model has been saved.
 160     static void onSpeakerModelSaved();
 161
 162     // Fired when a hotword has triggered.
 163     static void onHotwordTriggered();
 164
 165     // Fired when the speaker model should be deleted.
 166     static void onDeleteSpeakerModel();
 167   };
 168 };