Refactoring of chrome speech recognition architecture (CL1.3)

content/browser/speech/speech_recognition_engine.h

Index: content/browser/speech/speech_recognition_engine.h
diff --git a/content/browser/speech/speech_recognition_engine.h b/content/browser/speech/speech_recognition_engine.h
new file mode 100644
index 0000000000000000000000000000000000000000..31443784a3c33cf30f848bb66be8c7195219ffd5
--- /dev/null
+++ b/content/browser/speech/speech_recognition_engine.h
@@ -0,0 +1,87 @@
+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CONTENT_BROWSER_SPEECH_SPEECH_RECOGNITION_ENGINE_H_
+#define CONTENT_BROWSER_SPEECH_SPEECH_RECOGNITION_ENGINE_H_
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "base/basictypes.h"
+#include "content/public/common/speech_recognition_result.h"
+
+namespace content {
+struct SpeechRecognitionResult;
+struct SpeechRecognitionError;
+}
+
+namespace speech {
+
+class AudioChunk;
+
+// This interface models the basic contract that a speech recognition engine,
+// either working locally or relying on a remote web-service, must obey.
+// The expected call sequence for exported methods is:
+// Initialize            Mandatory at beginning of SR.

[Satish, 2012/03/21 13:29:48]

Do you allow SpeechRecognitionEngine to be reused for multiple recognitions,
i.e. call Initialize>...>Cleanup and then do the same again later? If yes, seems
like Initialize/Cleanup should be renamed Start/StopRecognition to indicate they
are not object level initialization to be done once. If however the idea is to
create an engine object each time you want a new recognition to happen, then
Initialize/Cleanup should probably be part of the constructor and destructor.

[Primiano Tucci (use gerrit), 2012/03/22 11:20:41]

Done.

+//   TakeAudioChunk      For every audio chunk pushed.
+//   AudioChunksEnded    Finalize the audio stream (omitted in case of errors).
+// Cleanup               Mandatory at end of SR (even on errors).
+// No delegate callback is allowed before Initialize() or after Cleanup().
+class SpeechRecognitionEngine {
+ public:
+  // Interface for receiving callbacks from this object.
+  class Delegate {
+   public:
+    virtual void OnSpeechEngineResult(

[Satish, 2012/03/21 13:29:48]

SpeechEngine -> SpeechRecognitionEngine.
Add comment describing when this is called, same for the next method

[Primiano Tucci (use gerrit), 2012/03/22 11:20:41]

Done.

+        const content::SpeechRecognitionResult& result) = 0;
+    virtual void OnSpeechEngineError(
+        const content::SpeechRecognitionError& error) = 0;
+   protected:

[Satish, 2012/03/21 13:29:48]

add newline above

[Primiano Tucci (use gerrit), 2012/03/22 11:20:41]

Done.

+    virtual ~Delegate() {}
+  };
+
+  virtual ~SpeechRecognitionEngine() {}
+
+  // Prepare for upcoming TakeAudioChunk() calls.

[Satish, 2012/03/21 13:29:48]

reword comment to explain this should be called when a new recognition process
is about to begin

[Primiano Tucci (use gerrit), 2012/03/22 11:20:41]

Done.

+  virtual void Initialize() = 0;
+
+  // End any recognition activity and don't make any further callback.
+  virtual void Cleanup() = 0;
+
+  // Push a chunk of uncompressed audio data, where the chunk length agrees with
+  // GetDesiredAudioChunkDurationMs(), and bytes_per_sample agrees to the engine

[Satish, 2012/03/21 13:29:48]

No need to mention this in the comment if they are DCHECKed in the code

[Primiano Tucci (use gerrit), 2012/03/22 11:20:41]

Removed the bytes_per_sample as it is DCHECKed. The DesiredAudioChunkDuration,
however, is not a strong requirement (e.g. it is violated in the last frame).
On 2012/03/21 13:29:48, Satish wrote:

+  // configuration.
+  virtual void TakeAudioChunk(const AudioChunk& data) = 0;
+
+  // Notifies the engine that audio capture has completed and no more chunks
+  // will be pushed. The engine, however, can still provide further results
+  // using the audio chunks collected so far.
+  virtual void AudioChunksEnded() = 0;
+
+  // Checks wheter recognition of pushed audio data is pending.
+  virtual bool IsRecognitionPending() const = 0;
+
+  // Retrieves the desired duration, in milliseconds, of pushed AudioChunk(s).
+  virtual int GetDesiredAudioChunkDurationMs() const = 0;
+
+  // set_delegate detached from constructor for lazy dependency injection.
+  void set_delegate(Delegate* delegate) { delegate_ = delegate; }
+
+ protected:
+  Delegate* delegate() const { return delegate_; }
+
+ private:
+  Delegate* delegate_;
+};
+
+// This typedef is to workaround the issue with certain versions of
+// Visual Studio where it gets confused between multiple Delegate
+// classes and gives a C2500 error. (I saw this error on the try bots -
+// the workaround was not needed for my machine).
+typedef SpeechRecognitionEngine::Delegate SpeechRecognitionEngineDelegate;
+
+}  // namespace speech
+
+#endif  // CONTENT_BROWSER_SPEECH_SPEECH_RECOGNITION_ENGINE_H_