dom/media/webspeech/synth/nsISpeechService.idl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 /**
   9  * A callback is implemented by the service.
  10  */
  11 [scriptable, uuid(c576de0c-8a3d-4570-be7e-9876d3e5bed2)]
  12 interface nsISpeechTaskCallback : nsISupports
  13 {
  14   /**
  15    * The user or application has paused the speech.
  16    */
  17   void onPause();
  18
  19   /**
  20    * The user or application has resumed the speech.
  21    */
  22   void onResume();
  23
  24   /**
  25    * The user or application has canceled the speech.
  26    */
  27   void onCancel();
  28
  29   /**
  30    * The user or application has changed the volume of this speech.
  31    */
  32   void onVolumeChanged(in float aVolume);
  33 };
  34
  35
  36 /**
  37  * A task is associated with a single utterance. It is provided by the browser
  38  * to the service in the speak() method.
  39  */
  40 [scriptable, builtinclass, uuid(ad59949c-2437-4b35-8eeb-d760caab75c5)]
  41 interface nsISpeechTask : nsISupports
  42 {
  43   /**
  44    * Prepare browser for speech.
  45    *
  46    * @param aCallback callback object for mid-speech operations.
  47    */
  48   void setup(in nsISpeechTaskCallback aCallback);
  49
  50   /**
  51    * Dispatch start event.
  52    */
  53   void dispatchStart();
  54
  55   /**
  56    * Dispatch end event.
  57    *
  58    * @param aElapsedTime time in seconds since speech has started.
  59    * @param aCharIndex   offset of spoken characters.
  60    */
  61   void dispatchEnd(in float aElapsedTime, in unsigned long aCharIndex);
  62
  63   /**
  64    * Dispatch pause event.
  65    *
  66    * @param aElapsedTime time in seconds since speech has started.
  67    * @param aCharIndex   offset of spoken characters.
  68    */
  69   void dispatchPause(in float aElapsedTime, in unsigned long aCharIndex);
  70
  71   /**
  72    * Dispatch resume event.
  73    *
  74    * @param aElapsedTime time in seconds since speech has started.
  75    * @param aCharIndex   offset of spoken characters.
  76    */
  77   void dispatchResume(in float aElapsedTime, in unsigned long aCharIndex);
  78
  79   /**
  80    * Dispatch error event.
  81    *
  82    * @param aElapsedTime time in seconds since speech has started.
  83    * @param aCharIndex   offset of spoken characters.
  84    */
  85   void dispatchError(in float aElapsedTime, in unsigned long aCharIndex);
  86
  87   /**
  88    * Dispatch boundary event.
  89    *
  90    * @param aName        name of boundary, 'word' or 'sentence'
  91    * @param aElapsedTime time in seconds since speech has started.
  92    * @param aCharIndex   offset of spoken characters.
  93    * @param aCharLength  length of text in boundary event to be spoken.
  94    */
  95   [optional_argc] void dispatchBoundary(in AString aName, in float aElapsedTime,
  96                                         in unsigned long aCharIndex,
  97                                         [optional] in unsigned long aCharLength);
  98
  99   /**
 100    * Dispatch mark event.
 101    *
 102    * @param aName        mark identifier.
 103    * @param aElapsedTime time in seconds since speech has started.
 104    * @param aCharIndex   offset of spoken characters.
 105    */
 106   void dispatchMark(in AString aName, in float aElapsedTime, in unsigned long aCharIndex);
 107 };
 108
 109 /**
 110  * The main interface of a speech synthesis service.
 111  *
 112  * A service is responsible for outputting audio.
 113  * The service dispatches events, starting with dispatchStart() and ending with
 114  * dispatchEnd or dispatchError().
 115  * A service must also respond with the currect actions and events in response
 116  * to implemented callback methods.
 117  */
 118 [scriptable, uuid(9b7d59db-88ff-43d0-b6ee-9f63d042d08f)]
 119 interface nsISpeechService : nsISupports
 120 {
 121   /**
 122    * Speak the given text using the voice identified byu the given uri. See
 123    * W3C Speech API spec for information about pitch and rate.
 124    * https://dvcs.w3.org/hg/speech-api/raw-file/tip/speechapi.html#utterance-attributes
 125    *
 126    * @param aText   text to utter.
 127    * @param aUri    unique voice identifier.
 128    * @param aVolume volume to speak voice in. Only relevant for indirect audio.
 129    * @param aRate   rate to speak voice in.
 130    * @param aPitch  pitch to speak voice in.
 131    * @param aTask  task instance for utterance, used for sending events or audio
 132    *                 data back to browser.
 133    */
 134   void speak(in AString aText, in AString aUri,
 135              in float aVolume, in float aRate, in float aPitch,
 136              in nsISpeechTask aTask);
 137 };
 138
 139 %{C++
 140 // This is the service category speech services could use to start up as
 141 // a component.
 142 #define NS_SPEECH_SYNTH_STARTED "speech-synth-started"
 143 %}