diff --git a/media/java/android/media/SoundPool.java b/media/java/android/media/SoundPool.java
index 32413dc6e8415..6403aab08adc0 100644
--- a/media/java/android/media/SoundPool.java
+++ b/media/java/android/media/SoundPool.java
@@ -36,13 +36,20 @@ import java.util.concurrent.atomic.AtomicReference;
 /**
  * The SoundPool class manages and plays audio resources for applications.
  *
- * <p>A SoundPool is a collection of samples that can be loaded into memory
+ * <p>A SoundPool is a collection of sound samples that can be loaded into memory
  * from a resource inside the APK or from a file in the file system. The
- * SoundPool library uses the MediaPlayer service to decode the audio
- * into a raw 16-bit PCM mono or stereo stream. This allows applications
+ * SoundPool library uses the MediaCodec service to decode the audio
+ * into raw 16-bit PCM. This allows applications
  * to ship with compressed streams without having to suffer the CPU load
  * and latency of decompressing during playback.</p>
  *
+ * <p>Soundpool sounds are expected to be short as they are
+ * predecoded into memory. Each decoded sound is internally limited to one
+ * megabyte storage, which represents approximately 5.6 seconds at 44.1kHz stereo
+ * (the duration is proportionally longer at lower sample rates or
+ * a channel mask of mono). A decoded audio sound will be truncated if it would
+ * exceed the per-sound one megabyte storage space.</p>
+ *
  * <p>In addition to low-latency playback, SoundPool can also manage the number
  * of audio streams being rendered at once. When the SoundPool object is
  * constructed, the maxStreams parameter sets the maximum number of streams