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