From 76b02e4e14f5326a0cf507ae27525be575ab42ba Mon Sep 17 00:00:00 2001
From: Marc Wilson <marcwilson@google.com>
Date: Tue, 10 Sep 2013 15:29:00 +0100
Subject: [PATCH] Update documentation for speech APIs.

Makes it clear that the intent and service APIs are likely to stream
audio over the network and notes that impact this has on bandwidth and
battery life.
Also clarifies that the service API should not be used for continuous
recognition as a result. The intent API only runs when the activity is
in the foreground so I didn't mention continuous recognition for it.

Bug: 10674392
Change-Id: Ib5e0c16b3124f4b7d892ef5bd4167f23662d2ca3
(cherry picked from commit 2921cee3048f7e64ba6645d50a1c1705ef9658f8)
---
 core/java/android/speech/RecognizerIntent.java |  5 ++++-
 core/java/android/speech/SpeechRecognizer.java | 10 ++++++++--
 2 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/core/java/android/speech/RecognizerIntent.java b/core/java/android/speech/RecognizerIntent.java
index 457e66c6dbddb..e991d84807c18 100644
--- a/core/java/android/speech/RecognizerIntent.java
+++ b/core/java/android/speech/RecognizerIntent.java
@@ -55,7 +55,10 @@ public class RecognizerIntent {
      * <p>Starting this intent with just {@link Activity#startActivity(Intent)} is not supported.
      * You must either use {@link Activity#startActivityForResult(Intent, int)}, or provide a
      * PendingIntent, to receive recognition results.
-     * 
+     *
+     * <p>The implementation of this API is likely to stream audio to remote servers to perform
+     * speech recognition which can use a substantial amount of bandwidth.
+     *
      * <p>Required extras:
      * <ul>
      *   <li>{@link #EXTRA_LANGUAGE_MODEL}
diff --git a/core/java/android/speech/SpeechRecognizer.java b/core/java/android/speech/SpeechRecognizer.java
index 8fee41d1bcb7f..94aedbdf1d6a3 100644
--- a/core/java/android/speech/SpeechRecognizer.java
+++ b/core/java/android/speech/SpeechRecognizer.java
@@ -39,8 +39,14 @@ import java.util.Queue;
  * This class provides access to the speech recognition service. This service allows access to the
  * speech recognizer. Do not instantiate this class directly, instead, call
  * {@link SpeechRecognizer#createSpeechRecognizer(Context)}. This class's methods must be
- * invoked only from the main application thread. Please note that the application must have
- * {@link android.Manifest.permission#RECORD_AUDIO} permission to use this class.
+ * invoked only from the main application thread. 
+ *
+ * <p>The implementation of this API is likely to stream audio to remote servers to perform speech
+ * recognition. As such this API is not intended to be used for continuous recognition, which would
+ * consume a significant amount of battery and bandwidth.
+ *
+ * <p>Please note that the application must have {@link android.Manifest.permission#RECORD_AUDIO}
+ * permission to use this class.
  */
 public class SpeechRecognizer {
     /** DEBUG value to enable verbose debug prints */