From 0fc6bc4cac6391f048f0f2748b3e979effe0924b Mon Sep 17 00:00:00 2001
From: James Dong <jdong@google.com>
Date: Fri, 26 Feb 2010 19:36:35 -0800
Subject: [PATCH] Clean up MediaRecorder for public Java SDK - update comments
 and fix a check in setAudioChannels()

bug - 2362412
---
 api/current.xml                               |  52 +++++++++
 media/java/android/media/MediaRecorder.java   | 109 ++++++++++--------
 media/jni/android_media_MediaRecorder.cpp     |   6 +-
 .../functional/MediaRecorderTest.java         |  12 +-
 4 files changed, 122 insertions(+), 57 deletions(-)

diff --git a/api/current.xml b/api/current.xml
index eae20e7764ba5..212e66192b1aa 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -83843,6 +83843,19 @@
  visibility="public"
 >
 </method>
+<method name="setAudioChannels"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="numChannels" type="int">
+</parameter>
+</method>
 <method name="setAudioEncoder"
  return="void"
  abstract="false"
@@ -83858,6 +83871,32 @@
 <exception name="IllegalStateException" type="java.lang.IllegalStateException">
 </exception>
 </method>
+<method name="setAudioEncodingBitRate"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="bitRate" type="int">
+</parameter>
+</method>
+<method name="setAudioSamplingRate"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="samplingRate" type="int">
+</parameter>
+</method>
 <method name="setAudioSource"
  return="void"
  abstract="false"
@@ -84015,6 +84054,19 @@
 <exception name="IllegalStateException" type="java.lang.IllegalStateException">
 </exception>
 </method>
+<method name="setVideoEncodingBitRate"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="bitRate" type="int">
+</parameter>
+</method>
 <method name="setVideoFrameRate"
  return="void"
  abstract="false"
diff --git a/media/java/android/media/MediaRecorder.java b/media/java/android/media/MediaRecorder.java
index 15e3501062700..2c5cbf6e215a3 100644
--- a/media/java/android/media/MediaRecorder.java
+++ b/media/java/android/media/MediaRecorder.java
@@ -225,46 +225,6 @@ public class MediaRecorder
         public static final int MPEG_4_SP = 3;
     }
 
-
-    /**
-     * @hide Defines the audio sampling rate. This must be set before
-     * setAudioEncoder() or it will be ignored.
-     * This parameter is used with
-     * {@link MediaRecorder#setParameters(String)}.
-     */
-    public final class AudioParamSamplingRate {
-      /* Do not change these values without updating their counterparts
-       * in include/media/mediarecorder.h!
-       */
-        private AudioParamSamplingRate() {}
-        public static final String AUDIO_PARAM_SAMPLING_RATE_KEY = "audio-param-sampling-rate=";
-    }
-
-     /**
-     * @hide Defines the audio number of channels. This must be set before
-     * setAudioEncoder() or it will be ignored.
-     * This parameter is used with
-     * {@link MediaRecorder#setParameters(String)}.
-     */
-    public final class AudioParamChannels {
-      /* Do not change these values without updating their counterparts
-       * in include/media/mediarecorder.h!
-       */
-        private AudioParamChannels() {}
-        public static final String AUDIO_PARAM_NUMBER_OF_CHANNELS = "audio-param-number-of-channels=";
-    }
-
-     /**
-     * @hide Defines the audio encoding bitrate. This must be set before
-     * setAudioEncoder() or it will be ignored.
-     * This parameter is used with
-     * {@link MediaRecorder#setParameters(String)}.
-     */
-    public final class AudioParamEncodingBitrate{
-        private AudioParamEncodingBitrate() {}
-        public static final String AUDIO_PARAM_ENCODING_BITRATE = "audio-param-encoding-bitrate=";
-    }
-
     /**
      * Sets the audio source to be used for recording. If this method is not
      * called, the output file will not contain an audio track. The source needs
@@ -399,14 +359,69 @@ public class MediaRecorder
             throws IllegalStateException;
 
     /**
-     * @hide Sets a parameter in the author engine.
+     * Sets the audio sampling rate for recording. Call this method before prepare().
+     * Prepare() may perform additional checks on the parameter to make sure whether
+     * the specified audio sampling rate is applicable. The sampling rate really depends
+     * on the format for the audio recording, as well as the capabilities of the platform.
+     * For instance, the sampling rate supported by AAC audio coding standard ranges
+     * from 8 to 96 kHz. Please consult with the related audio coding standard for the
+     * supported audio sampling rate.
      *
-     * @param params the parameter to set.
-     * @see android.media.MediaRecorder.AudioParamSamplingRate
-     * @see android.media.MediaRecorder.AudioParamChannels
-     * @see android.media.MediaRecorder.AudioParamEncodingBitrate
+     * @param samplingRate the sampling rate for audio in samples per second.
      */
-    public native void setParameters(String params);
+    public void setAudioSamplingRate(int samplingRate) {
+        if (samplingRate <= 0) {
+            throw new IllegalArgumentException("Audio sampling rate is not positive");
+        }
+        setParameter(String.format("audio-param-sampling-rate=%d", samplingRate));
+    }
+
+    /**
+     * Sets the number of audio channels for recording. Call this method before prepare().
+     * Prepare() may perform additional checks on the parameter to make sure whether the
+     * specified number of audio channels are applicable.
+     *
+     * @param numChannels the number of audio channels. Usually it is either 1 (mono) or 2
+     * (stereo).
+     */
+    public void setAudioChannels(int numChannels) {
+        if (numChannels <= 0) {
+            throw new IllegalArgumentException("Number of channels is not positive");
+        }
+        setParameter(String.format("audio-param-number-of-channels=%d", numChannels));
+    }
+
+    /**
+     * Sets the audio encoding bit rate for recording. Call this method before prepare().
+     * Prepare() may perform additional checks on the parameter to make sure whether the
+     * specified bit rate is applicable, and sometimes the passed bitRate will be clipped
+     * internally to ensure the audio recording can proceed smoothly based on the
+     * capabilities of the platform.
+     *
+     * @param bitRate the audio encoding bit rate in bits per second.
+     */
+    public void setAudioEncodingBitRate(int bitRate) {
+        if (bitRate <= 0) {
+            throw new IllegalArgumentException("Audio encoding bit rate is not positive");
+        }
+        setParameter(String.format("audio-param-encoding-bitrate=%d", bitRate));
+    }
+
+    /**
+     * Sets the video encoding bit rate for recording. Call this method before prepare().
+     * Prepare() may perform additional checks on the parameter to make sure whether the
+     * specified bit rate is applicable, and sometimes the passed bitRate will be
+     * clipped internally to ensure the video recording can proceed smoothly based on
+     * the capabilities of the platform.
+     *
+     * @param bitRate the video encoding bit rate in bits per second.
+     */
+    public void setVideoEncodingBitRate(int bitRate) {
+        if (bitRate <= 0) {
+            throw new IllegalArgumentException("Video encoding bit rate is not positive");
+        }
+        setParameter(String.format("video-param-encoding-bitrate=%d", bitRate));
+    }
 
     /**
      * Pass in the file descriptor of the file to be written. Call this after
@@ -670,6 +685,8 @@ public class MediaRecorder
 
     private native final void native_finalize();
 
+    private native void setParameter(String nameValuePair);
+
     @Override
     protected void finalize() { native_finalize(); }
 }
diff --git a/media/jni/android_media_MediaRecorder.cpp b/media/jni/android_media_MediaRecorder.cpp
index 3063f15823023..00af3a2868360 100644
--- a/media/jni/android_media_MediaRecorder.cpp
+++ b/media/jni/android_media_MediaRecorder.cpp
@@ -223,9 +223,9 @@ android_media_MediaRecorder_setAudioEncoder(JNIEnv *env, jobject thiz, jint ae)
 }
 
 static void
-android_media_MediaRecorder_setParameters(JNIEnv *env, jobject thiz, jstring params)
+android_media_MediaRecorder_setParameter(JNIEnv *env, jobject thiz, jstring params)
 {
-    LOGV("setParameters()");
+    LOGV("setParameter()");
     if (params == NULL)
     {
         LOGE("Invalid or empty params string.  This parameter will be ignored.");
@@ -455,7 +455,7 @@ static JNINativeMethod gMethods[] = {
     {"setOutputFormat",      "(I)V",                            (void *)android_media_MediaRecorder_setOutputFormat},
     {"setVideoEncoder",      "(I)V",                            (void *)android_media_MediaRecorder_setVideoEncoder},
     {"setAudioEncoder",      "(I)V",                            (void *)android_media_MediaRecorder_setAudioEncoder},
-    {"setParameters",        "(Ljava/lang/String;)V",           (void *)android_media_MediaRecorder_setParameters},
+    {"setParameter",         "(Ljava/lang/String;)V",           (void *)android_media_MediaRecorder_setParameter},
     {"_setOutputFile",       "(Ljava/io/FileDescriptor;JJ)V",   (void *)android_media_MediaRecorder_setOutputFileFD},
     {"setVideoSize",         "(II)V",                           (void *)android_media_MediaRecorder_setVideoSize},
     {"setVideoFrameRate",    "(I)V",                            (void *)android_media_MediaRecorder_setVideoFrameRate},
diff --git a/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaRecorderTest.java b/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaRecorderTest.java
index 39caccdce8d21..a52fd76acdbc1 100644
--- a/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaRecorderTest.java
+++ b/media/tests/MediaFrameworkTest/src/com/android/mediaframeworktest/functional/MediaRecorderTest.java
@@ -141,14 +141,10 @@ public class MediaRecorderTest extends ActivityInstrumentationTestCase<MediaFram
             mMediaRecorder.setOutputFile(filename);
             mMediaRecorder.setVideoFrameRate(videoFps);
             mMediaRecorder.setVideoSize(videoWidth, videoHeight);
-            mMediaRecorder.setParameters(String.format("video-param-encoding-bitrate=%d",
-                    videoBitrate));
-            mMediaRecorder.setParameters(String.format("audio-param-encoding-bitrate=%d",
-                    audioBitrate));
-            mMediaRecorder.setParameters(String.format("audio-param-number-of-channels=%d",
-                    audioChannels));
-            mMediaRecorder.setParameters(String.format("audio-param-sampling-rate=%d",
-                    audioSamplingRate));
+            mMediaRecorder.setVideoEncodingBitRate(videoBitrate);
+            mMediaRecorder.setAudioEncodingBitRate(audioBitrate);
+            mMediaRecorder.setAudioChannels(audioChannels);
+            mMediaRecorder.setAudioSamplingRate(audioSamplingRate);
             mMediaRecorder.setVideoEncoder(videoEncoder);
             mMediaRecorder.setAudioEncoder(audioEncoder);
             mMediaRecorder.setPreviewDisplay(mSurfaceHolder.getSurface());