content/browser/speech/speech_recognition_engine.h

   1 // Copyright (c) 2012 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 #ifndef CONTENT_BROWSER_SPEECH_SPEECH_RECOGNITION_ENGINE_H_
   6 #define CONTENT_BROWSER_SPEECH_SPEECH_RECOGNITION_ENGINE_H_
   7
   8 #include <string>
   9
  10 #include "base/basictypes.h"
  11 #include "content/common/content_export.h"
  12 #include "content/public/browser/speech_recognition_session_preamble.h"
  13 #include "content/public/common/speech_recognition_grammar.h"
  14 #include "content/public/common/speech_recognition_result.h"
  15
  16 namespace content {
  17
  18 class AudioChunk;
  19 struct SpeechRecognitionError;
  20
  21 // This interface models the basic contract that a speech recognition engine,
  22 // either working locally or relying on a remote web-service, must obey.
  23 // The expected call sequence for exported methods is:
  24 // StartRecognition      Mandatory at beginning of SR.
  25 //   TakeAudioChunk      For every audio chunk pushed.
  26 //   AudioChunksEnded    Finalize the audio stream (omitted in case of errors).
  27 // EndRecognition        Mandatory at end of SR (even on errors).
  28 // No delegate callbacks are allowed before StartRecognition or after
  29 // EndRecognition. If a recognition was started, the caller can free the
  30 // SpeechRecognitionEngine only after calling EndRecognition.
  31 class SpeechRecognitionEngine {
  32  public:
  33   // Interface for receiving callbacks from this object.
  34   class Delegate {
  35    public:
  36     // Called whenever a result is retrieved. It might be issued several times,
  37     // (e.g., in the case of continuous speech recognition engine
  38     // implementations).
  39     virtual void OnSpeechRecognitionEngineResults(
  40         const SpeechRecognitionResults& results) = 0;
  41     virtual void OnSpeechRecognitionEngineError(
  42         const SpeechRecognitionError& error) = 0;
  43
  44    protected:
  45     virtual ~Delegate() {}
  46   };
  47
  48   // Remote engine configuration.
  49   struct CONTENT_EXPORT Config {
  50     Config();
  51     ~Config();
  52
  53     std::string language;
  54     SpeechRecognitionGrammarArray grammars;
  55     bool filter_profanities;
  56     bool continuous;
  57     bool interim_results;
  58     uint32 max_hypotheses;
  59     std::string hardware_info;
  60     std::string origin_url;
  61     int audio_sample_rate;
  62     int audio_num_bits_per_sample;
  63     std::string auth_token;
  64     std::string auth_scope;
  65     scoped_refptr<SpeechRecognitionSessionPreamble> preamble;
  66   };
  67
  68   virtual ~SpeechRecognitionEngine() {}
  69
  70   // Set/change the recognition engine configuration. It is not allowed to call
  71   // this function while a recognition is ongoing.
  72   virtual void SetConfig(const Config& config) = 0;
  73
  74   // Called when the speech recognition begins, before any TakeAudioChunk call.
  75   virtual void StartRecognition() = 0;
  76
  77   // End any recognition activity and don't make any further callback.
  78   // Must be always called to close the corresponding StartRecognition call,
  79   // even in case of errors.
  80   // No further TakeAudioChunk/AudioChunksEnded calls are allowed after this.
  81   virtual void EndRecognition() = 0;
  82
  83   // Push a chunk of uncompressed audio data, where the chunk length agrees with
  84   // GetDesiredAudioChunkDurationMs().
  85   virtual void TakeAudioChunk(const AudioChunk& data) = 0;
  86
  87   // Notifies the engine that audio capture has completed and no more chunks
  88   // will be pushed. The engine, however, can still provide further results
  89   // using the audio chunks collected so far.
  90   virtual void AudioChunksEnded() = 0;
  91
  92   // Checks wheter recognition of pushed audio data is pending.
  93   virtual bool IsRecognitionPending() const = 0;
  94
  95   // Retrieves the desired duration, in milliseconds, of pushed AudioChunk(s).
  96   virtual int GetDesiredAudioChunkDurationMs() const = 0;
  97
  98   // set_delegate detached from constructor for lazy dependency injection.
  99   void set_delegate(Delegate* delegate) { delegate_ = delegate; }
 100
 101  protected:
 102   Delegate* delegate() const { return delegate_; }
 103
 104  private:
 105   Delegate* delegate_;
 106 };
 107
 108 // These typedefs are to workaround the issue with certain versions of
 109 // Visual Studio where it gets confused between multiple Delegate
 110 // classes and gives a C2500 error.
 111 typedef SpeechRecognitionEngine::Delegate SpeechRecognitionEngineDelegate;
 112 typedef SpeechRecognitionEngine::Config SpeechRecognitionEngineConfig;
 113
 114 }  // namespace content
 115
 116 #endif  // CONTENT_BROWSER_SPEECH_SPEECH_RECOGNITION_ENGINE_H_