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