From f69b61b49638c2ac9e344cd3096a19cf6a8582e9 Mon Sep 17 00:00:00 2001 From: Jean-Michel Trivi <> Date: Fri, 17 Apr 2009 11:22:35 -0700 Subject: [PATCH 01/72] AI 146751: Finalize AudioTrack javadoc. BUG=1795799 Automated import of CL 146751 --- media/java/android/media/AudioTrack.java | 111 ++++++++++++++--------- 1 file changed, 67 insertions(+), 44 deletions(-) diff --git a/media/java/android/media/AudioTrack.java b/media/java/android/media/AudioTrack.java index 4196ef398b65..3cd841de4145 100644 --- a/media/java/android/media/AudioTrack.java +++ b/media/java/android/media/AudioTrack.java @@ -32,22 +32,24 @@ import android.util.Log; * It allows to stream PCM audio buffers to the audio hardware for playback. This is * achieved by "pushing" the data to the AudioTrack object using one of the * {@link #write(byte[], int, int)} and {@link #write(short[], int, int)} methods. - *
An AudioTrack instance can operate under two modes: static of streaming.
- * The Streaming mode consists in continuously writing data to the AudioTrack, using one
- * of the write() methods. These are blocking and return when the data has been transferred
- * from the Java layer to the native layer, and is queued for playback. The streaming mode
+ *
+ *
An AudioTrack instance can operate under two modes: static or streaming.
+ * In Streaming mode, the application writes a continuous stream of data to the AudioTrack, using
+ * one of the write() methods. These are blocking and return when the data has been transferred
+ * from the Java layer to the native layer and queued for playback. The streaming mode
* is most useful when playing blocks of audio data that for instance are:
*
Upon creation, an AudioTrack object initializes its associated audio buffer.
* The size of this buffer, specified during the construction, determines how long an AudioTrack
* can play before running out of data.
@@ -66,11 +68,11 @@ public class AudioTrack
/** Maximum value for a channel volume */
private static final float VOLUME_MAX = 1.0f;
- /** state of an AudioTrack this is stopped */
+ /** indicates AudioTrack state is stopped */
public static final int PLAYSTATE_STOPPED = 1; // matches SL_PLAYSTATE_STOPPED
- /** state of an AudioTrack this is paused */
+ /** indicates AudioTrack state is paused */
public static final int PLAYSTATE_PAUSED = 2; // matches SL_PLAYSTATE_PAUSED
- /** state of an AudioTrack this is playing */
+ /** indicates AudioTrack state is playing */
public static final int PLAYSTATE_PLAYING = 3; // matches SL_PLAYSTATE_PLAYING
/**
@@ -85,7 +87,7 @@ public class AudioTrack
public static final int MODE_STREAM = 1;
/**
- * State of an AudioTrack that was not successfully initialized upon creation
+ * State of an AudioTrack that was not successfully initialized upon creation.
*/
public static final int STATE_UNINITIALIZED = 0;
/**
@@ -126,11 +128,11 @@ public class AudioTrack
// Events:
// to keep in sync with frameworks/base/include/media/AudioTrack.h
/**
- * Event id for when the playback head has reached a previously set marker.
+ * Event id denotes when playback head has reached a previously set marker.
*/
private static final int NATIVE_EVENT_MARKER = 3;
/**
- * Event id for when the previously set update period has passed during playback.
+ * Event id denotes when previously set update period has elapsed during playback.
*/
private static final int NATIVE_EVENT_NEW_POS = 4;
@@ -141,11 +143,11 @@ public class AudioTrack
// Member variables
//--------------------
/**
- * Indicates the state of the AudioTrack instance
+ * Indicates the state of the AudioTrack instance.
*/
private int mState = STATE_UNINITIALIZED;
/**
- * Indicates the play state of the AudioTrack instance
+ * Indicates the play state of the AudioTrack instance.
*/
private int mPlayState = PLAYSTATE_STOPPED;
/**
@@ -159,7 +161,7 @@ public class AudioTrack
*/
private OnPlaybackPositionUpdateListener mPositionListener = null;
/**
- * Lock to protect event listener updates against event notifications
+ * Lock to protect event listener updates against event notifications.
*/
private final Object mPositionListenerLock = new Object();
/**
@@ -167,11 +169,11 @@ public class AudioTrack
*/
private int mNativeBufferSizeInBytes = 0;
/**
- * Handler for marker events coming from the native code
+ * Handler for marker events coming from the native code.
*/
private NativeEventHandlerDelegate mEventHandlerDelegate = null;
/**
- * Looper associated with the thread that creates the AudioTrack instance
+ * Looper associated with the thread that creates the AudioTrack instance.
*/
private Looper mInitializationLooper = null;
/**
@@ -179,7 +181,7 @@ public class AudioTrack
*/
private int mSampleRate = 22050;
/**
- * The number of input audio channels (1 is mono, 2 is stereo)
+ * The number of input audio channels (1 is mono, 2 is stereo).
*/
private int mChannelCount = 1;
/**
@@ -194,7 +196,7 @@ public class AudioTrack
*/
private int mDataLoadMode = MODE_STREAM;
/**
- * The current audio channel configuration
+ * The current audio channel configuration.
*/
private int mChannelConfiguration = AudioFormat.CHANNEL_CONFIGURATION_MONO;
/**
@@ -209,7 +211,7 @@ public class AudioTrack
// Used exclusively by native code
//--------------------
/**
- * Accessed by native methods: provides access to C++ AudioTrack object
+ * Accessed by native methods: provides access to C++ AudioTrack object.
*/
@SuppressWarnings("unused")
private int mNativeTrackInJavaObj;
@@ -227,17 +229,14 @@ public class AudioTrack
/**
* Class constructor.
* @param streamType the type of the audio stream. See
-
* {@link AudioManager#STREAM_VOICE_CALL}, {@link AudioManager#STREAM_SYSTEM},
* {@link AudioManager#STREAM_RING}, {@link AudioManager#STREAM_MUSIC} and
* {@link AudioManager#STREAM_ALARM}
* @param sampleRateInHz the sample rate expressed in Hertz. Examples of rates are (but
* not limited to) 44100, 22050 and 11025.
* @param channelConfig describes the configuration of the audio channels.
-
* See {@link AudioFormat#CHANNEL_CONFIGURATION_MONO} and
* {@link AudioFormat#CHANNEL_CONFIGURATION_STEREO}
-
* @param audioFormat the format in which the audio data is represented.
* See {@link AudioFormat#ENCODING_PCM_16BIT} and
* {@link AudioFormat#ENCODING_PCM_8BIT}
@@ -245,6 +244,9 @@ public class AudioTrack
* from for playback. If using the AudioTrack in streaming mode, you can write data into
* this buffer in smaller chunks than this size. If using the AudioTrack in static mode,
* this is the maximum size of the sound that will be played for this instance.
+ * See {@link #getMinBufferSize(int, int, int)} to determine the minimum required buffer size
+ * for the successful creation of an AudioTrack instance in streaming mode. Using values
+ * smaller than getMinBufferSize() will result in an initialization failure.
* @param mode streaming or static buffer. See {@link #MODE_STATIC} and {@link #MODE_STREAM}
* @throws java.lang.IllegalArgumentException
*/
@@ -423,8 +425,8 @@ public class AudioTrack
}
/**
- * Returns the current playback rate in Hz. Note that this rate may differ from one set using
- * {@link #setPlaybackRate(int)} as the value effectively set is implementation-dependent.
+ * Returns the current playback rate in Hz. Note that this rate may differ from the one set
+ * with {@link #setPlaybackRate(int)} as the value effectively used is implementation-dependent.
*/
public int getPlaybackRate() {
return native_get_playback_rate();
@@ -470,6 +472,9 @@ public class AudioTrack
* AudioTrack instance has been created to check if it was initialized
* properly. This ensures that the appropriate hardware resources have been
* acquired.
+ * @see #STATE_INITIALIZED
+ * @see #STATE_NO_STATIC_DATA
+ * @see #STATE_UNINITIALIZED
*/
public int getState() {
return mState;
@@ -486,28 +491,28 @@ public class AudioTrack
}
/**
- * Returns the native frame count used by the hardware
+ * Returns the native frame count used by the hardware.
*/
protected int getNativeFrameCount() {
return native_get_native_frame_count();
}
/**
- * @return marker position in frames
+ * Returns marker position expressed in frames.
*/
public int getNotificationMarkerPosition() {
return native_get_marker_pos();
}
/**
- * @return update period in frames
+ * Returns the notification update period expressed in frames.
*/
public int getPositionNotificationPeriod() {
return native_get_pos_update_period();
}
/**
- * @return playback head position in frames
+ * Returns the playback head position expressed in frames
*/
public int getPlaybackHeadPosition() {
return native_get_position();
@@ -522,7 +527,9 @@ public class AudioTrack
/**
* Returns the minimum buffer size required for the successful creation of an AudioTrack
- * object to be created in the {@link #MODE_STREAM} mode.
+ * object to be created in the {@link #MODE_STREAM} mode. Note that this size doesn't
+ * guarantee a smooth playback under load, and higher values should be chosen according to
+ * the expected frequency at which the buffer will be refilled with additional data to play.
* @param sampleRateInHz the sample rate expressed in Hertz.
* @param channelConfig describes the configuration of the audio channels.
* See {@link AudioFormat#CHANNEL_CONFIGURATION_MONO} and
@@ -533,7 +540,7 @@ public class AudioTrack
* @return {@link #ERROR_BAD_VALUE} if an invalid parameter was passed,
* or {@link #ERROR} if the implementation was unable to query the hardware for its output
* properties,
- * or the minimum buffer size expressed in number of bytes.
+ * or the minimum buffer size expressed in bytes.
*/
static public int getMinBufferSize(int sampleRateInHz, int channelConfig, int audioFormat) {
int channelCount = 0;
@@ -577,13 +584,22 @@ public class AudioTrack
/**
* Sets the listener the AudioTrack notifies when a previously set marker is reached or
* for each periodic playback head position update.
+ * Notifications will be received in the same thread as the one in which the AudioTrack
+ * instance was created.
* @param listener
*/
public void setPlaybackPositionUpdateListener(OnPlaybackPositionUpdateListener listener) {
setPlaybackPositionUpdateListener(listener, null);
}
-
+ /**
+ * Sets the listener the AudioTrack notifies when a previously set marker is reached or
+ * for each periodic playback head position update.
+ * Use this method to receive AudioTrack events in the Handler associated with another
+ * thread than the one in which you created the AudioTrack instance.
+ * @param listener
+ * @param handler the Handler that will receive the event notification messages.
+ */
public void setPlaybackPositionUpdateListener(OnPlaybackPositionUpdateListener listener,
Handler handler) {
synchronized (mPositionListenerLock) {
@@ -636,13 +652,17 @@ public class AudioTrack
* the audio data will be consumed and played back, not the original sampling rate of the
* content. Setting it to half the sample rate of the content will cause the playback to
* last twice as long, but will also result result in a negative pitch shift.
- * The current implementation supports a maximum sample rate of twice the hardware output
- * sample rate (see {@link #getNativeOutputSampleRate(int)}). Use {@link #getSampleRate()} to
- * check the rate actually used in hardware after potential clamping.
- * @param sampleRateInHz
+ * The current implementation supports a maximum sample rate of 64kHz.
+ * Use {@link #getSampleRate()} to check the rate actually used in hardware after
+ * potential clamping.
+ * @param sampleRateInHz the sample rate expressed in Hz
* @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},
* {@link #ERROR_INVALID_OPERATION}
*/
+ // FIXME: the implementation should support twice the hardware output sample rate
+ // (see {@link #getNativeOutputSampleRate(int)}), but currently
+ // due to the representation of the sample rate in the native layer, the sample rate
+ // is limited to 65535Hz
public int setPlaybackRate(int sampleRateInHz) {
if (mState != STATE_INITIALIZED) {
return ERROR_INVALID_OPERATION;
@@ -656,7 +676,7 @@ public class AudioTrack
/**
- *
+ * Sets the position of the notification marker.
* @param markerInFrames marker in frames
* @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},
* {@link #ERROR_INVALID_OPERATION}
@@ -670,7 +690,8 @@ public class AudioTrack
/**
- * @param periodInFrames update period in frames
+ * Sets the period for the periodic notification event.
+ * @param periodInFrames update period expressed in frames
* @return error code or success, see {@link #SUCCESS}, {@link #ERROR_INVALID_OPERATION}
*/
public int setPositionNotificationPeriod(int periodInFrames) {
@@ -683,7 +704,7 @@ public class AudioTrack
/**
* Sets the playback head position. The track must be stopped for the position to be changed.
- * @param positionInFrames playback head position in frames
+ * @param positionInFrames playback head position expressed in frames
* @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},
* {@link #ERROR_INVALID_OPERATION}
*/
@@ -699,8 +720,8 @@ public class AudioTrack
/**
* Sets the loop points and the loop count. The loop can be infinite.
- * @param startInFrames loop start marker in frames
- * @param endInFrames loop end marker in frames
+ * @param startInFrames loop start marker expressed in frames
+ * @param endInFrames loop end marker expressed in frames
* @param loopCount the number of times the loop is looped.
* A value of -1 means infinite looping.
* @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},
@@ -797,7 +818,8 @@ public class AudioTrack
/**
* Writes the audio data to the audio hardware for playback.
* @param audioData the array that holds the data to play.
- * @param offsetInBytes the offset in audioData where the data to play starts.
+ * @param offsetInBytes the offset expressed in bytes in audioData where the data to play
+ * starts.
* @param sizeInBytes the number of bytes to read in audioData after the offset.
* @return the number of bytes that were written or {@link #ERROR_INVALID_OPERATION}
* if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
@@ -827,7 +849,8 @@ public class AudioTrack
/**
* Writes the audio data to the audio hardware for playback.
* @param audioData the array that holds the data to play.
- * @param offsetInShorts the offset in audioData where the data to play starts.
+ * @param offsetInShorts the offset expressed in shorts in audioData where the data to play
+ * starts.
* @param sizeInShorts the number of bytes to read in audioData after the offset.
* @return the number of shorts that were written or {@link #ERROR_INVALID_OPERATION}
* if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
--
GitLab
From 62200dd153cc5d0d1f3222f169a51007fdb17667 Mon Sep 17 00:00:00 2001
From: Dave Sparks <>
Date: Fri, 17 Apr 2009 11:29:35 -0700
Subject: [PATCH 02/72] AI 146754: Fix some problems in the SoundPool docs and
add additional text. BUG=1795461
Automated import of CL 146754
---
media/java/android/media/SoundPool.java | 133 +++++++++++++++++-------
1 file changed, 95 insertions(+), 38 deletions(-)
diff --git a/media/java/android/media/SoundPool.java b/media/java/android/media/SoundPool.java
index ab3274b1aa66..b13c2e6ace1e 100644
--- a/media/java/android/media/SoundPool.java
+++ b/media/java/android/media/SoundPool.java
@@ -46,6 +46,19 @@ import java.io.IOException;
* number of streams helps to cap CPU loading and reducing the likelihood that
* audio mixing will impact visuals or UI performance.
Sounds can be looped by setting a non-zero loop value. A value of -1 + * causes the sound to loop forever. In this case, the application must + * explicitly call the stop() function to stop the sound. Any other non-zero + * value will cause the sound to repeat the specified number of times, e.g. + * a value of 3 causes the sound to play a total of 4 times.
+ * + *The playback rate can also be changed. A playback rate of 1.0 causes + * the sound to play at its original frequency (resampled, if necessary, + * to the hardware output frequency). A playback rate of 2.0 causes the + * sound to play at twice its original frequency, and a playback rate of + * 0.5 causes it to play at half its original frequency. The playback + * rate range is 0.5 to 2.0.
+ * *Priority runs low to high, i.e. higher numbers are higher priority. * Priority is used when a call to play() would cause the number of active * streams to exceed the value established by the maxStreams parameter when @@ -72,6 +85,13 @@ import java.io.IOException; * adjusting the playback rate in real-time for doppler or synthesis * effects.
* + *Note that since streams can be stopped due to resource constraints, the + * streamID is a reference to a particular instance of a stream. If the stream + * is stopped to allow a higher priority stream to play, the stream is no + * longer be valid. However, the application is allowed to call methods on + * the streamID without error. This may help simplify program logic since + * the application need not concern itself with the stream lifecycle.
+ * *In our example, when the player has completed the level, the game * logic should call SoundPool.release() to release all the native resources * in use and then set the SoundPool reference to null. If the player starts @@ -104,10 +124,11 @@ public class SoundPool } /** - * Load the sound from the specified path - * + * Load the sound from the specified path. + * * @param path the path to the audio file - * @param priority the priority of the sound. Currently has no effect. + * @param priority the priority of the sound. Currently has no effect. Use + * a value of 1 for future compatibility. * @return a sound ID. This value can be used to play or unload the sound. */ public int load(String path, int priority) @@ -133,17 +154,18 @@ public class SoundPool } /** - * Load the sound from the specified APK resource + * Load the sound from the specified APK resource. * - *
Note that the extension is dropped. For example, if you want to load + * Note that the extension is dropped. For example, if you want to load * a sound from the raw resource file "explosion.mp3", you would specify * "R.raw.explosion" as the resource ID. Note that this means you cannot * have both an "explosion.wav" and an "explosion.mp3" in the res/raw - * directory.
+ * directory. * * @param context the application context * @param resId the resource ID - * @param priority the priority of the sound. Currently has no effect. + * @param priority the priority of the sound. Currently has no effect. Use + * a value of 1 for future compatibility. * @return a sound ID. This value can be used to play or unload the sound. */ public int load(Context context, int resId, int priority) { @@ -162,10 +184,11 @@ public class SoundPool } /** - * Load the sound from an asset file descriptor + * Load the sound from an asset file descriptor. * * @param afd an asset file descriptor - * @param priority the priority of the sound. Currently has no effect. + * @param priority the priority of the sound. Currently has no effect. Use + * a value of 1 for future compatibility. * @return a sound ID. This value can be used to play or unload the sound. */ public int load(AssetFileDescriptor afd, int priority) { @@ -181,16 +204,17 @@ public class SoundPool } /** - * Load the sound from a FileDescriptor + * Load the sound from a FileDescriptor. * - *This version is useful if you store multiple sounds in a single + * This version is useful if you store multiple sounds in a single * binary. The offset specifies the offset from the start of the file - * and the length specifies the length of the sound within the file.
+ * and the length specifies the length of the sound within the file. * * @param fd a FileDescriptor object * @param offset offset to the start of the sound * @param length length of the sound - * @param priority the priority of the sound. Currently has no effect. + * @param priority the priority of the sound. Currently has no effect. Use + * a value of 1 for future compatibility. * @return a sound ID. This value can be used to play or unload the sound. */ public int load(FileDescriptor fd, long offset, long length, int priority) { @@ -202,11 +226,11 @@ public class SoundPool private native final int _load(FileDescriptor fd, long offset, long length, int priority); /** - * Unload a sound from a sound ID + * Unload a sound from a sound ID. * - *Unloads the sound specified by the soundID. This is the value + * Unloads the sound specified by the soundID. This is the value * returned by the load() function. Returns true if the sound is - * successfully unloaded, false if the sound was already unloaded.
+ * successfully unloaded, false if the sound was already unloaded. * * @param soundID a soundID returned by the load() function * @return true if just unloaded, false if previously unloaded @@ -214,66 +238,77 @@ public class SoundPool public native final boolean unload(int soundID); /** - * Play a sound from a sound ID + * Play a sound from a sound ID. * - *Play the sound specified by the soundID. This is the value + * Play the sound specified by the soundID. This is the value * returned by the load() function. Returns a non-zero streamID * if successful, zero if it fails. The streamID can be used to * further control playback. Note that calling play() may cause * another sound to stop playing if the maximum number of active - * streams is exceeded.
+ * streams is exceeded. A loop value of -1 means loop forever, + * a value of 0 means don't loop, other values indicate the + * number of repeats, e.g. a value of 1 plays the audio twice. + * The playback rate allows the application to vary the playback + * rate (pitch) of the sound. A value of 1.0 means play back at + * the original frequency. A value of 2.0 means play back twice + * as fast, and a value of 0.5 means playback at half speed. * * @param soundID a soundID returned by the load() function + * @param leftVolume left volume value (range = 0.0 to 1.0) + * @param rightVolume right volume value (range = 0.0 to 1.0) + * @param priority stream priority (0 = lowest priority) + * @param loop loop mode (0 = no loop, -1 = loop forever) + * @param rate playback rate (1.0 = normal playback, range 0.5 to 2.0) * @return non-zero streamID if successful, zero if failed */ public native final int play(int soundID, float leftVolume, float rightVolume, int priority, int loop, float rate); /** - * Pause a playback stream + * Pause a playback stream. * - *Pause the stream specified by the streamID. This is the + * Pause the stream specified by the streamID. This is the * value returned by the play() function. If the stream is * playing, it will be paused. If the stream is not playing * (e.g. is stopped or was previously paused), calling this - * function will have no effect.
+ * function will have no effect. * * @param streamID a streamID returned by the play() function */ public native final void pause(int streamID); /** - * Resume a playback stream + * Resume a playback stream. * - *Resume the stream specified by the streamID. This + * Resume the stream specified by the streamID. This * is the value returned by the play() function. If the stream * is paused, this will resume playback. If the stream was not - * previously paused, calling this function will have no effect.
+ * previously paused, calling this function will have no effect. * * @param streamID a streamID returned by the play() function */ public native final void resume(int streamID); /** - * Stop a playback stream + * Stop a playback stream. * - *Stop the stream specified by the streamID. This + * Stop the stream specified by the streamID. This * is the value returned by the play() function. If the stream * is playing, it will be stopped. It also releases any native * resources associated with this stream. If the stream is not - * playing, it will have no effect.
+ * playing, it will have no effect. * * @param streamID a streamID returned by the play() function */ public native final void stop(int streamID); /** - * Set stream volume + * Set stream volume. * - *Sets the volume on the stream specified by the streamID. + * Sets the volume on the stream specified by the streamID. * This is the value returned by the play() function. The * value must be in the range of 0.0 to 1.0. If the stream does - * not exist, it will have no effect.
+ * not exist, it will have no effect. * * @param streamID a streamID returned by the play() function * @param leftVolume left volume value (range = 0.0 to 1.0) @@ -283,29 +318,51 @@ public class SoundPool float leftVolume, float rightVolume); /** - * Change stream priority + * Change stream priority. * - *Change the priority of the stream specified by the streamID. + * Change the priority of the stream specified by the streamID. * This is the value returned by the play() function. Affects the - * order in which streams are re-used to play new sounds. + * order in which streams are re-used to play new sounds. If the + * stream does not exist, it will have no effect. * * @param streamID a streamID returned by the play() function */ public native final void setPriority(int streamID, int priority); /** - * Change stream priority + * Set loop mode. * - *
Change the priority of the stream specified by the streamID. - * This is the value returned by the play() function. Affects the - * order in which streams are re-used to play new sounds. + * Change the loop mode. A loop value of -1 means loop forever, + * a value of 0 means don't loop, other values indicate the + * number of repeats, e.g. a value of 1 plays the audio twice. + * If the stream does not exist, it will have no effect. * * @param streamID a streamID returned by the play() function + * @param loop loop mode (0 = no loop, -1 = loop forever) */ public native final void setLoop(int streamID, int loop); + /** + * Change playback rate. + * + * The playback rate allows the application to vary the playback + * rate (pitch) of the sound. A value of 1.0 means playback at + * the original frequency. A value of 2.0 means playback twice + * as fast, and a value of 0.5 means playback at half speed. + * If the stream does not exist, it will have no effect. + * + * @param streamID a streamID returned by the play() function + * @param rate playback rate (1.0 = normal playback, range 0.5 to 2.0) + */ public native final void setRate(int streamID, float rate); + /** + * Release the SoundPool resources. + * + * Release all memory and native resources used by the SoundPool + * object. The SoundPool can no longer be used and the reference + * should be set to null. + */ public native final void release(); private native final void native_setup(Object mediaplayer_this, -- GitLab From a9a66950d6827cbd6cb94ca56fcf9db656bad5a5 Mon Sep 17 00:00:00 2001 From: Jean-Michel Trivi <> Date: Mon, 20 Apr 2009 10:45:02 -0700 Subject: [PATCH 03/72] AI 146937: Finalize AudioRecord javadoc. BUG=1797606 Automated import of CL 146937 --- media/java/android/media/AudioRecord.java | 81 +++++++++++++---------- 1 file changed, 46 insertions(+), 35 deletions(-) diff --git a/media/java/android/media/AudioRecord.java b/media/java/android/media/AudioRecord.java index a49bd67b772a..3346bed93e30 100644 --- a/media/java/android/media/AudioRecord.java +++ b/media/java/android/media/AudioRecord.java @@ -40,7 +40,7 @@ import android.util.Log; *
Upon creation, an AudioRecord object initializes its associated audio buffer that it will * fill with the new audio data. The size of this buffer, specified during the construction, * determines how long an AudioRecord can record before "over-running" data that has not - * been read yet. Data should be from the audio hardware in chunks of sizes inferior to + * been read yet. Data should be read from the audio hardware in chunks of sizes inferior to * the total recording buffer size. */ public class AudioRecord @@ -49,20 +49,20 @@ public class AudioRecord // Constants //-------------------- /** - * State of an AudioRecord that was not successfully initialized upon creation + * indicates AudioRecord state is not successfully initialized. */ public static final int STATE_UNINITIALIZED = 0; /** - * State of an AudioRecord that is ready to be used + * indicates AudioRecord state is ready to be used */ public static final int STATE_INITIALIZED = 1; /** - * State of an AudioRecord this is not recording + * indicates AudioRecord recording state is not recording */ public static final int RECORDSTATE_STOPPED = 1; // matches SL_RECORDSTATE_STOPPED /** - * State of an AudioRecord this is recording + * indicates AudioRecord recording state is recording */ public static final int RECORDSTATE_RECORDING = 3;// matches SL_RECORDSTATE_RECORDING @@ -94,11 +94,11 @@ public class AudioRecord // Events: // to keep in sync with frameworks/base/include/media/AudioRecord.h /** - * Event id for when the recording head has reached a previously set marker. + * Event id denotes when record head has reached a previously set marker. */ private static final int NATIVE_EVENT_MARKER = 2; /** - * Event id for when the previously set update period has passed during recording. + * Event id denotes when previously set update period has elapsed during recording. */ private static final int NATIVE_EVENT_NEW_POS = 3; @@ -188,7 +188,7 @@ public class AudioRecord */ private int mNativeBufferSizeInBytes = 0; - + //--------------------------------------------------------- // Constructor, Finalize //-------------------- @@ -206,7 +206,9 @@ public class AudioRecord * {@link AudioFormat#ENCODING_PCM_8BIT} * @param bufferSizeInBytes the total size (in bytes) of the buffer where audio data is written * to during the recording. New audio data can be read from this buffer in smaller chunks - * than this size. + * than this size. See {@link #getMinBufferSize(int, int, int)} to determine the minimum + * required buffer size for the successful creation of an AudioRecord instance. Using values + * smaller than getMinBufferSize() will result in an initialization failure. * @throws java.lang.IllegalArgumentException */ public AudioRecord(int audioSource, int sampleRateInHz, int channelConfig, int audioFormat, @@ -319,11 +321,13 @@ public class AudioRecord mNativeBufferSizeInBytes = audioBufferSize; } - - + + /** * Releases the native AudioRecord resources. + * The object can no longer be used and the reference should be set to null + * after a call to release() */ public void release() { try { @@ -334,7 +338,7 @@ public class AudioRecord native_release(); mState = STATE_UNINITIALIZED; } - + @Override protected void finalize() { @@ -404,24 +408,27 @@ public class AudioRecord public int getRecordingState() { return mRecordingState; } - + /** - * @return marker position in frames + * Returns the notification marker position expressed in frames. */ public int getNotificationMarkerPosition() { return native_get_marker_pos(); } /** - * @return update period in frames + * Returns the notification update period expressed in frames. */ public int getPositionNotificationPeriod() { return native_get_pos_update_period(); } - + /** * Returns the minimum buffer size required for the successful creation of an AudioRecord * object. + * Note that this size doesn't guarantee a smooth recording under load, and higher values + * should be chosen according to the expected frequency at which the AudioRecord instance + * will be polled for new data. * @param sampleRateInHz the sample rate expressed in Hertz. * @param channelConfig describes the configuration of the audio channels. * See {@link AudioFormat#CHANNEL_CONFIGURATION_MONO} and @@ -432,7 +439,7 @@ public class AudioRecord * hardware, or an invalid parameter was passed, * or {@link #ERROR} if the implementation was unable to query the hardware for its * output properties, - * or the minimum buffer size expressed in of bytes. + * or the minimum buffer size expressed in bytes. */ static public int getMinBufferSize(int sampleRateInHz, int channelConfig, int audioFormat) { int channelCount = 0; @@ -516,7 +523,7 @@ public class AudioRecord /** * Reads audio data from the audio hardware for recording into a buffer. * @param audioData the array to which the recorded audio data is written. - * @param offsetInBytes index in audioData from which the data is written. + * @param offsetInBytes index in audioData from which the data is written expressed in bytes. * @param sizeInBytes the number of requested bytes. * @return the number of bytes that were read or or {@link #ERROR_INVALID_OPERATION} * if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if @@ -540,9 +547,9 @@ public class AudioRecord /** * Reads audio data from the audio hardware for recording into a buffer. * @param audioData the array to which the recorded audio data is written. - * @param offsetInShorts index in audioData from which the data is written. + * @param offsetInShorts index in audioData from which the data is written expressed in shorts. * @param sizeInShorts the number of requested shorts. - * @return the number of bytes that were read or or {@link #ERROR_INVALID_OPERATION} + * @return the number of shorts that were read or or {@link #ERROR_INVALID_OPERATION} * if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if * the parameters don't resolve to valid data and indexes. * The number of shorts will not exceed sizeInShorts. @@ -595,8 +602,15 @@ public class AudioRecord public void setRecordPositionUpdateListener(OnRecordPositionUpdateListener listener) { setRecordPositionUpdateListener(listener, null); } - + /** + * Sets the listener the AudioRecord notifies when a previously set marker is reached or + * for each periodic record head position update. + * Use this method to receive AudioRecord events in the Handler associated with another + * thread than the one in which you created the AudioTrack instance. + * @param listener + * @param handler the Handler that will receive the event notification messages. + */ public void setRecordPositionUpdateListener(OnRecordPositionUpdateListener listener, Handler handler) { synchronized (mPositionListenerLock) { @@ -616,8 +630,8 @@ public class AudioRecord } } - - + + /** * Sets the marker position at which the listener is called, if set with * {@link #setRecordPositionUpdateListener(OnRecordPositionUpdateListener)} or @@ -629,8 +643,8 @@ public class AudioRecord public int setNotificationMarkerPosition(int markerInFrames) { return native_set_marker_pos(markerInFrames); } - - + + /** * Sets the period at which the listener is called, if set with * {@link #setRecordPositionUpdateListener(OnRecordPositionUpdateListener)} or @@ -648,7 +662,9 @@ public class AudioRecord //-------------------- /** * Interface definition for a callback to be invoked when an AudioRecord has - * reached a notification marker set by setNotificationMarkerPosition(). + * reached a notification marker set by {@link AudioRecord#setNotificationMarkerPosition(int)} + * or for periodic updates on the progress of the record head, as set by + * {@link AudioRecord#setPositionNotificationPeriod(int)}. */ public interface OnRecordPositionUpdateListener { /** @@ -663,10 +679,9 @@ public class AudioRecord */ void onPeriodicNotification(AudioRecord recorder); } - - - + + //--------------------------------------------------------- // Inner classes //-------------------- @@ -678,12 +693,12 @@ public class AudioRecord private class NativeEventHandler extends Handler { private final AudioRecord mAudioRecord; - + NativeEventHandler(AudioRecord recorder, Looper looper) { super(looper); mAudioRecord = recorder; } - + @Override public void handleMessage(Message msg) { OnRecordPositionUpdateListener listener = null; @@ -779,7 +794,3 @@ public class AudioRecord } - - - - -- GitLab From 26dea0f211c433f2d3a12dcc85bb069664112a03 Mon Sep 17 00:00:00 2001 From: Jean-Michel Trivi <> Date: Mon, 20 Apr 2009 16:29:19 -0700 Subject: [PATCH 04/72] AI 147032: Finalize JetPlayer javadoc. BUG=1801229 Automated import of CL 147032 --- media/java/android/media/JetPlayer.java | 173 ++++++++++++++++++++++-- 1 file changed, 165 insertions(+), 8 deletions(-) diff --git a/media/java/android/media/JetPlayer.java b/media/java/android/media/JetPlayer.java index c9efac5cdb19..4fb0ead7ff59 100644 --- a/media/java/android/media/JetPlayer.java +++ b/media/java/android/media/JetPlayer.java @@ -30,8 +30,29 @@ import android.util.Log; /** * JetPlayer provides access to JET content playback and control. - *
- * Use JetPlayer.getJetPlayer()
to get an instance of this class.
+ *
+ *
Please refer to the JET Creator User Manual for a presentation of the JET interactive + * music concept and how to use the JetCreator tool to create content to be player by JetPlayer. + * + *
Use of the JetPlayer class is based around the playback of a number of JET segments + * sequentially added to a playback FIFO queue. The rendering of the MIDI content stored in each + * segment can be dynamically affected by two mechanisms: + *
If you've just downloaded the SDK, then continue with -Installing the Android SDK.
+Installing the Android SDK.If you're upgrading from a previously installed version, then refer to the -Upgrading guide.
+Upgrading guide.Once you've completed the SDK installation, you can start learning about
development on the Android framework by reading the
Date: Mon, 20 Apr 2009 21:53:32 -0700
Subject: [PATCH 06/72] AI 147081: Add document describing AVDs and usage. (doc
change only) BUG=1790234
Automated import of CL 147081
---
docs/html/guide/developing/tools/avd.jd | 496 ++++++++++++++++++++++++
1 file changed, 496 insertions(+)
create mode 100644 docs/html/guide/developing/tools/avd.jd
diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd
new file mode 100644
index 000000000000..7ba79685eef7
--- /dev/null
+++ b/docs/html/guide/developing/tools/avd.jd
@@ -0,0 +1,496 @@
+page.title=Android Virtual Devices
+@jd:body
+
+ Android Virtual Devices (AVDs) are configurations of emulator options that let
+you better model an actual device. Each AVD is made up of: You can create as many AVDs as you need, based on the types of devices you
+want to model and the Android platforms and external libraries you want to run
+your application on. In addition to the options in an AVD configuration, you can also
+specify emulator command-line options at launch or by using the emulator
+console to change behaviors or characteristics at run time. For a complete
+reference of emulator options, please see the Emulator
+documentation. To create and manage AVDs, you use the android tool provided in the Android
+SDK. For more information about how to work with AVDs from inside
+your development environment, see Developing in Eclipse with
+ADT or Developing in
+Other IDEs, as appropriate for your environment. To create an AVD, you use the android tool, a command-line utility
+available in the To create each AVD, you issue the command Here's the command-line usage for creating an AVD: You can use any name you want for the AVD, but since you are likely to be
+creating multiple AVDs, you should choose a name that lets you recognize the
+general characteristics offered by the AVD. As shown in the usage above, you must use the
+
+ To specify the system image to use, you refer to its target ID
+— an integer — as assigned by the android tool. The target ID is not
+derived from the system image name, version, or API Level, or other attribute,
+so you need to have the android tool list the available system images and the
+target ID of each, as described in the next section. You should do this
+before you run the To generate a list of system image targets, use this command: The android tool scans the Once you have generated the list of targets available, you can look at the
+characteristics of each system image — name, API Level, external
+libraries, and so on — and determine which target is appropriate for the
+new AVD. Keep these points in mind when you are selecting a system image target for
+your AVD: When you've selected the target you want to use and made a note of its ID,
+use the If the target you selected was a standard Android system image ("Type:
+platform"), the android tool next asks you whether you want to create a custom
+hardware profile. If you want to set custom hardware emulation options for the AVD, enter
+"yes" and set values as needed. If you want to use the default hardware
+emulation options for the AVD, just press the return key (the default is "no").
+The android tool creates the AVD with name and system image mapping you
+requested, with the options you specified.
+
+ If you are creating an AVD whose target is an SDK add-on,
+the android tool does not allow you to set hardware emulation options. It
+assumes that the provider of the add-on has set emulation options appropriately
+for the device that the add-on is modeling, and so prevents you from resetting
+the options. For a list of options you can use in the When are creating a new AVD that uses a standard Android system image ("Type:
+platform"), the android tool lets you set hardware emulation options for virtual
+device. The table below lists the options available and the default values, as
+well as the names of properties that store the emulated hardware options in the AVD's
+configuration file (the config.ini file in the AVD's local directory). AVD quickview
+
+
+ In this document
+
+
+ See Also
+
+
+
+
+
+Creating an AVD
+
+<sdk>/tools/
directory. Managing AVDs is one
+of the two main function of the android tool (the other is creating and updating
+Android projects). Open a terminal window and change to the
+<sdk>/tools/
directory, if neededandroid avd create
,
+with options that specify a name for the new AVD and the system image you want
+to run on the emulator when the AVD is invoked. You can specify other options on
+the command line also, such as to create an emulated SD card for the new AVD, set
+the emulator skin to use, or set a custom location for the AVD's files.android -n <name> -t <targetID> [-<option> <value>] ...
+
+-t
(or
+--target
) argument when creating a new AVD. The argument sets up a
+mapping between the AVD and the system image that you want to use whenever the
+AVD is invoked. You can specify any Android system image that is available in
+your local SDK — it can be the system image of a standard Android platform
+version or that of any SDK add-on. Later, when applications use the AVD, they'll
+be running on the system that you specify in the -t
argument.android create avd
command.
+Listing targets
+
+android list targets
+
+<sdk>/platforms
and
+<sdk>/add-ons
directories looking for valid system images and
+then generates the list of targets. Here's an example of the command output:
+Available Android targets:
+id:1
+ Name: Android 1.1
+ Type: platform
+ API level: 2
+ Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
+id:2
+ Name: Android 1.5
+ Type: platform
+ API level: 3
+ Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P
+id:3
+ Name: Google APIs
+ Type: add-on
+ Vendor: Google Inc.
+ Description: Android + Google APIs
+ Based on Android 1.5 (API level 3)
+ Libraries:
+ * com.google.android.maps (maps.jar)
+ API for Google Maps
+ Skins: HVGA (default), HVGA-L, QVGA-P, HVGA-P, QVGA-L
+
+Selecting a target
+
+
+
+
+minSdkVersion
attribute of
+the application's manifest file. For more information about the relationship
+between system API Level and application minSdkVersion
, see Specifying
+Minimum System API Version.
+uses-library
element in its
+manifest file, the application can only run on a system image in which that
+external library is present. If you want your application to run on the AVD you
+are creating, check the application's uses-library
element and
+select a system image target that includes that library.
+
+Creating the AVD
+
+android create avd
command to create the AVD, supplying the
+target ID as the -t
argument. Here's an example that creates an
+AVD with name "my_android1.5" and target ID "2" (the standard Android 1.5
+system image in the list above): android create avd -n my_android1.5 -t 2
+
+Android 1.5 is a basic Android platform.
+Do you wish to create a custom hardware profile [no]
+
+android create avd
+command, see the table in Command-line options for AVDs,
+at the bottom of
+this page. Setting hardware emulation options
+
+
Characteristic | +Description | +Property | +
---|---|---|
Device ram size | +The amount of physical RAM on the device, in megabytes. Default value is "96". + | hw.ramSize | +
Touch-screen support | +Whether there is a touch screen or not on the device. Default value is "yes". | +hw.touchScreen + + + |
Trackball support | +Whether there is a trackball on the device. Default value is "yes". | +hw.trackBall | +
Keyboard support | +Whether the device has a QWERTY keyboard. Default value is "yes". | +hw.keyboard | +
DPad support | +Whether the device has DPad keys. Default value is "yes". | +hw.dPad | +
GSM modem support | +Whether there is a GSM modem in the device. Default value is "yes". | +hw.gsmModem | +
Camera support | +Whether the device has a camera. Default value is "no". | +hw.camera | +
Maximum horizontal camera pixels | +Default value is "640". | +hw.camera.maxHorizontalPixels | +
Maximum vertical camera pixels | +Default value is "480". | +hw.camera.maxVerticalPixels | +
GPS support | +Whether there is a GPS in the device. Default value is "yes". | +hw.gps | +
Battery support | +Whether the device can run on a battery. Default value is "yes". | +hw.battery | +
Accelerometer | +Whether there is an accelerometer in the device. Default value is "yes". | +hw.accelerometer | +
Audio recording support | +Whether the device can record audio. Default value is "yes". | +hw.audioInput | +
Audio playback support | +Whether the device can play audio. Default value is "yes". | +hw.audioOutput | +
SD Card support | +Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes". | +hw.sdCard | +
Cache partition support | +Whether we use a /cache partition on the device. Default value is "yes". | +disk.cachePartition | +
Cache partition size | +Default value is "66MB". | +disk.cachePartition.size | +
When you create an AVD, the android tool creates a dedicated directory for it +on your development computer. The directory contains the AVD configuration file, +the user data image and SD card image (if available), and any other files +associated with the device. Note that the directory does not contain a system +image — instead, the AVD configuration file contains a mapping to the +system image, which it loads when the AVD is launched.
+ +The android tool also creates a <AVD name>.ini file for the AVD at the +root of the .android/avd directory on your computer. The file specifies the +location of the AVD directory and always remains at the root the .android +directory.
+ +By default, the android tool creates the AVD directory inside
+~/.android/avd/
(on Linux/Mac), C:\Documents and
+Settings\<user>\.android\
on Windows XP, and
+C:\Users\<user>\.android\
on Windows Vista.
+If you want to use a custom location for the AVD directory, you
+can do so by using the -p <path>
option when
+you create the AVD:
android create avd -n my_android1.5 -t 2 -p path/to/my/avd+ +
If the .android directory is hosted on a network drive, we recommend using
+the -p
option to place the AVD directory in another location.
+The AVD's .ini file remains in the .android directory on the network
+drive, regardless of the location of the AVD directory.
If you want to move or rename an AVD, you can do so using this command:
+ +android move avd -n <name> [-<option> <value>] ...+ +
The options for this command are listed in Command-line +options for AVDs at the bottom of this page.
+ +If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this case, the android list targets
command will produce this output:
+
+
The following Android Virtual Devices could not be loaded: +Name: foo +Path: <path>/.android/avd/foo.avd +Error: Invalid value in image.sysdir. Run 'android update avd -n foo'+ +
To fix this error, use the android update avd
command to recompute the path to the system images.
You can use the android tool to delete an AVD. Here is the command usage:
+ +android delete avd -n <name>+ +
When you issue the command, the android tool looks for an AVD matching the +specified name deletes the AVD's directory and files.
+ + +The table below lists the command-line options you can use with the +android tool.
+ + +Action | +Option | +Description | +Comments | +
---|---|---|---|
list avds |
+ + | List all known AVDs, with name, path, target, and skin. | ++ |
create avd |
+ -n <name> or |
+ The name for the AVD. | +Required | +
-t <targetID> |
+ Target ID of the system image to use with the new AVD. | +Required. To obtain a list of available targets, use android list
+ targets . |
+|
-c <path> or + -c <size>[K|M] |
+ The path to the SD card image to use with this AVD or the size of a new SD + card image to create for this AVD. | +Examples: -c path/to/sdcard or -c 1000M |
+|
-f |
+ Force creation of the AVD | +By default, if the name of the AVD being created matches that of an
+ existing AVD, the android tool will not create the new AVD or overwrite
+ the existing AVD. If you specify the -f option, however, the
+ android tool will automatically overwrite any existing AVD that has the
+ same name as the new AVD. The files and data of the existing AVD are
+ deleted. |
+|
-p <path> |
+ Path to the location at which to create the directory for this AVD's +files. | ++ | |
-s <name> or + -s <dimensions> |
+ The skin to use for this AVD, identified by name or dimensions. | +The android tool scans for a matching skin by name or dimension in the
+skins/ directory of the target referenced in the -t
+<targetID> argument. Example: -s HVGA-L |
+|
delete avd |
+ -n <name> |
+ Delete the specified AVD. | +Required | +
move avd |
+ -n <name> |
+ The name of the AVD to move. | +Required | +
-p <path> |
+ The path to the new location for the AVD. | ++ | |
-r <new-name> |
+ Rename the AVD. | ++ | |
update avds |
+ + | Recompute the paths to all system images. | ++ |
NOTE: The parameter pkg must refer to the package identifier of the + * package hosting the activity to be launched, which is specified in the AndroidManifest.xml + * file. This is not necessarily the same as the java package name. * * @param pkg The package hosting the activity to be launched. * @param activityCls The activity class to launch. @@ -82,6 +86,11 @@ public class InstrumentationTestCase extends TestCase { /** * Utility method for launching an activity with a specific Intent. + * + *
NOTE: The parameter pkg must refer to the package identifier of the
+ * package hosting the activity to be launched, which is specified in the AndroidManifest.xml
+ * file. This is not necessarily the same as the java package name.
+ *
* @param pkg The package hosting the activity to be launched.
* @param activityCls The activity class to launch.
* @param intent The intent to launch with
diff --git a/test-runner/android/test/ActivityInstrumentationTestCase.java b/test-runner/android/test/ActivityInstrumentationTestCase.java
index e5a9991ae557..f6b31ad208f7 100644
--- a/test-runner/android/test/ActivityInstrumentationTestCase.java
+++ b/test-runner/android/test/ActivityInstrumentationTestCase.java
@@ -40,7 +40,11 @@ public abstract class ActivityInstrumentationTestCase Additional Metadata for search suggestions. If you have defined a content provider
+ * Additional metadata for search suggestions. If you have defined a content provider
* to generate search suggestions, you'll need to publish it to the system, and you'll need to
* provide a bit of additional XML metadata in order to configure communications with it.
*
@@ -880,7 +880,7 @@ import android.view.KeyEvent;
*
*
*
- * Additional Metadata for search action keys. For each action key that you would like to
+ * Additional metadata for search action keys. For each action key that you would like to
* define, you'll need to add an additional element defining that key, and using the attributes
* discussed in Action Keys. A simple example is shown here:
*
@@ -956,6 +956,84 @@ import android.view.KeyEvent;
*
*
*
+ * Additional metadata for enabling voice search. To enable voice search for your
+ * activity, you can add fields to the metadata that enable and configure voice search. When
+ * enabled (and available on the device), a voice search button will be displayed in the
+ * Search UI. Clicking this button will launch a voice search activity. When the user has
+ * finished speaking, the voice search phrase will be transcribed into text and presented to the
+ * searchable activity as if it were a typed query.
+ *
+ * Elements of search metadata that support voice search:
+ *
+ *
+ *
+ *
+ *
*
*
+ *
+ *
+ * Attribute Description Required?
+ *
+ * android:voiceSearchMode
+ * If provided and non-zero, enables voice search. (Voice search may not be
+ * provided by the device, in which case these flags will have no effect.) The
+ * following mode bits are defined:
+ *
+ *
+ *
+ *
+ * showVoiceSearchButton
+ * If set, display a voice search button. This only takes effect if voice
+ * search is available on the device. If set, then launchWebSearch or
+ * launchRecognizer must also be set.
+ *
+ * launchWebSearch
+ * If set, the voice search button will take the user directly to a
+ * built-in voice web search activity. Most applications will not use this
+ * flag, as it will take the user away from the activity in which search
+ * was invoked.
+ *
+ *
+ * launchRecognizer
+ * If set, the voice search button will take the user directly to a
+ * built-in voice recording activity. This activity will prompt the user
+ * to speak, transcribe the spoken text, and forward the resulting query
+ * text to the searchable activity, just as if the user had typed it into
+ * the search UI and clicked the search button.
+ * No
+ *
+ *
+ * android:voiceLanguageModel
+ * If provided, this specifies the language model that should be used by the voice
+ * recognition system.
+ * See {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL}
+ * for more information. If not provided, the default value
+ * {@link android.speech.RecognizerIntent#LANGUAGE_MODEL_FREE_FORM} will be used.
+ * No
+ *
+ *
+ * android:voicePromptText
+ * If provided, this specifies a prompt that will be displayed during voice input.
+ * (If not provided, a default prompt will be displayed.)
+ * No
+ *
+ *
+ * android:voiceLanguage
+ * If provided, this specifies the spoken language to be expected. This is only
+ * needed if it is different from the current value of
+ * {@link java.util.Locale#getDefault()}.
+ *
+ * No
+ *
+ *
+ *
+ * android:voiceMaxResults
+ * If provided, enforces the maximum number of results to return, including the "best"
+ * result which will always be provided as the SEARCH intent's primary query. Must be
+ * one or greater. Use {@link android.speech.RecognizerIntent#EXTRA_RESULTS}
+ * to get the results from the intent. If not provided, the recognizer will choose
+ * how many results to return.
+ * No
+ * Passing Search Context
*
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index 425880419348..88b8316022bf 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -2703,12 +2703,13 @@
To help you model and test your application, the emulator lets your application -use the services of the Android platform to invoke other applications, access the -network, play audio and video, store and retrieve data, notify the user, and render -graphical transitions and themes.
+To let you model and test your application more easily, the emulator supports +Android Virtual Device (AVD) configurations. AVDs let you specify the Android +platform that you want to run on the emulator, as well as the hardware options +and emulator skin files tht you want to use. Once your application is running on +the emulator, it can use the services of the Android platform to invoke other +applications, access the network, play audio and video, store and retrieve data, +notify the user, and render graphical transitions and themes.
The emulator also includes a variety of debug capabilities, such as a console from which you can log kernel output, simulate application interrupts (such as arriving SMS messages or phone calls), and simulate latency effects and dropouts on the data channel.
- - -The Android emulator is a QEMU-based application that provides a virtual ARM -mobile device on which you can run your Android applications. It provides a full -Android system stack, down to the kernel level, and includes a set of +mobile device on which you can run your Android applications. It runs a full +Android system stack, down to the kernel level, that includes a set of preinstalled applications (such as the dialer) that you can access from your -applications. It provides a skinnable mobile device UI, customizable key -mappings, and a variety of commands and options for controlling the behaviors of -the emulated environment.
+applications. You can choose what version of the Android system you want to +run in the emulator by configuring AVDs, and you can also customize the +mobile device skin and key mappings. When launching the emulator and at runtime, +you can use a variety of commands and options to control the its behaviors. +The Android system image distributed in the SDK contains ARM machine code for the Android Linux kernel, the native libraries, the Dalvik VM, and the various @@ -132,9 +136,9 @@ it for developing Android applications.
During development and testing of your application, you install and run your application in the Android emulator. You can launch the emulator as a standalone application, from a command line, or you can use it as part of your Eclipse -development environment. In either case, you can specify the startup options -described in this document to control the emulator. -
+development environment. In either case, you specify the AVD configuration to +load and any startup options you want to use, as described in this document. +You can run your application on a single instance of the emulator or, depending on your needs, you can start multiple emulator instances and run your @@ -146,9 +150,14 @@ Emulation, SMS Emulation, and Emulator Networking
To start an instance of the emulator from the command line, change to the
-tools/
folder of the SDK and enter emulator
or
-./emulator
. This initializes the Android system and you will see
-the emulator window appear on your screen.
tools/
folder of the SDK. Enter emulator
command
+like this:
+
+emulator -avd <avd_name>+ +
This initializes the emulator and loads an AVD configuration (see the next +section for more information about AVDs). You will see the emulator window +appear on your screen.
If you are working in Eclipse, the ADT plugin for Eclipse installs your application and starts the emulator automatically, when you run or debug @@ -163,6 +172,27 @@ on the Emulator for information about how to install your application.
+ + +To use the emulator, you first must create one or more AVD configurations. In each +configuration, you specify an Android platform to run in the emulator and the set of hardware +options and emulator skin you want to use. Then, when you launch the emulator, you specify +the AVD configuration that you want to load.
+ +To specify the AVD you want to load when starting the emulator, you use the
+-avd
argument, as shown in the previous section.
Each AVD functions as an independent device, with its own private storage for +user data, SD card, and so on. When you launch the emulator with an AVD configuration, +it automatically loads the user data and SD card data from the AVD directory. By default, +the emulator stores the user data, SD card data, and cache in the AVD directory.
+ +To create and manage AVDs you use the android tool, a command-line utility +included in the SDK. For complete information about how to set up AVDs, see Android Virtual Devices.
+You can use emulator startup options and when launching the emulator, to control its appearance or behavior. Here's the command-line usage for launching the emulator with options:
-emulator [-<option> [<value>]] ... [-<qemu args>]+
emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]
The table below summarizes the available options.
@@ -292,7 +322,7 @@ Here's the command-line usage for launching the emulator with options:-help
-help-virtual-device
-avd <avd_name>
or @<avd_name>
-cache <filepath>
-data
is not used, the emulator looks for a file named "userdata-qemu.img"
- in the directory specified in <datadir>. ~/.android/SDK-1.0 (on Linux/Mac) or
- C:\Documents and Settings\<user>\Local Settings\Application Data\Android\SDK-1.0 (on Windows).
- If you use -data <filepath>
but the file does not exist, the emulator creates
- a file at that location using the specified name.
See Running Multiple Emulator Instances for information about how
- to use -data
to let multiple emulator instances preserve their user data across sessions.
For more information on disk images, use -help-disk-images
.
-avd
).
-initdata <filepath>
-wipe-data
), copy the contents
of this file to the new user-data disk image. By default, the emulator copies the <system>/userdata.img
.-wipe-data
. For more information on disk images, use -help-disk-images
.
-nocache
Optionally, you can specify a path relative to the current working directory. For more information on disk images, use -help-disk-images
.
-wipe-data
-datadir
and
@@ -679,7 +722,8 @@ scale in direct relationship with <delay> values.
-skin <skinID>
To run properly, the emulator requires access to a specific set of disk image -files. The Android SDK includes default versions of the required images, stored -in predetermined locations in the SDK directory structure. At startup, the -emulator looks for and reads the image files, using their default names and -storage locations.
+files. By default, the Emulator always looks for the disk images in the +private storage area of the AVD in use. If no images exist there when +the Emulator is launched, it creates the images in the AVD directory based on +default versions stored in the SDK. + +Note: The default storage location for
+AVDs is in ~/.android/avd
on OS X and Linux, C:\Documents and
+Settings\<user>\.android\
on Windows XP, and
+C:\Users\<user>\.android\
+on Windows Vista.
To let you use alternate or custom versions of the image files, the emulator provides startup options that override the default locations and filenames of @@ -713,32 +763,26 @@ the image files. When you use the options, the emulator searches for the image file under the image name or location that you specify; if it can not locate the image, it reverts to using the default names and location.
-The emulator uses three types of image files: system image files, runtime +
The emulator uses three types of image files: default image files, runtime image files, and temporary image files. The sections below describe how to override the location/name of each type of file.
- -System images contain system data and default settings without which the -emulator can not run. The image files are read-only — the emulator reads -the images at startup and does not modify them during the session.
- -All of the system image files are stored in a single directory. By default,
-the system images are stored in the lib/images
' under the
-emulator's program location.
When the emulator launches but does not find an existing user data image in +the active AVD's storage area, it creates a new one from a default version +included in the SDK. The default user data image is read-only. The image +files are read-only.
The emulator provides the -system <dir>
startup option to
-let you override the location under which the emulator looks for the system
-images files.
The emulator also provides startup options that let you override the names of
-the system images, as described in the table below. When you use one of the
-options, the emulator looks in the default directory, or in a custom location
-(if you specified -system <dir>
). Note that, if you provide
-alternate system image file, it must contain the same type of data as the
-default. For example, your override of the system.img file must point to a disk
-image containing an Android system.
The emulator also provides a startup option that lets you override the name
+of the default user data image, as described in the table below. When you use the
+option, the emulator looks in the default directory, or in a custom location
+(if you specified -system <dir>
).
Comments | +|
---|---|
userdata.img |
The initial user-data disk image | @@ -784,13 +829,7 @@ partition and removable storage media on actual device.