From 04065187d994bf4e10266cdccdffffd26288c2fd Mon Sep 17 00:00:00 2001 From: Andy Hung Date: Wed, 27 May 2015 18:57:54 -0700 Subject: Clarify AudioFormat sample rate and encoding documentation Bug: 21476142 Change-Id: I74fa3fcced5cc197a4cee6a7c10f3ed4690b0af1 --- media/java/android/media/AudioFormat.java | 89 +++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 4 deletions(-) (limited to 'media/java') diff --git a/media/java/android/media/AudioFormat.java b/media/java/android/media/AudioFormat.java index ee6d661..c29ec0d 100644 --- a/media/java/android/media/AudioFormat.java +++ b/media/java/android/media/AudioFormat.java @@ -18,16 +18,19 @@ package android.media; import android.annotation.IntDef; import android.annotation.NonNull; + import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.util.Arrays; /** - * The AudioFormat class is used to access a number of audio format and + * The {@link AudioFormat} class is used to access a number of audio format and * channel configuration constants. They are for instance used * in {@link AudioTrack} and {@link AudioRecord}, as valid values in individual parameters of * constructors like {@link AudioTrack#AudioTrack(int, int, int, int, int, int)}, where the fourth * parameter is one of the AudioFormat.ENCODING_* constants. + * The AudioFormat constants are also used in {@link MediaFormat} to specify + * audio related values commonly used in media, such as for {@link MediaFormat#KEY_CHANNEL_MASK}. *

The {@link AudioFormat.Builder} class can be used to create instances of * the AudioFormat format class. * Refer to @@ -39,6 +42,9 @@ import java.util.Arrays; *

  • encoding *
  • channel masks * + *

    Closely associated with the AudioFormat is the notion of an + * audio frame, which is used throughout the documentation + * to represent the minimum size complete unit of audio data. * *

    Sample rate

    *

    Expressed in Hz, the sample rate in an AudioFormat instance expresses the number @@ -48,10 +54,69 @@ import java.util.Arrays; * can be played on a device operating at a sample rate of 48000Hz; the sample rate conversion is * automatically handled by the platform, it will not play at 6x speed. * + *

    As of API {@link android.os.Build.VERSION_CODES#MNC}, + * sample rates up to 192kHz are supported + * for AudioRecord and AudioTrack, with sample rate conversion + * performed as needed. + * To improve efficiency and avoid lossy conversions, it is recommended to match the sample rate + * for AudioRecord and AudioTrack to the endpoint device + * sample rate, and limit the sample rate to no more than 48kHz unless there are special + * device capabilities that warrant a higher rate. + * *

    Encoding

    - *

    For PCM audio, audio encoding is used to describe the bit representation of an audio data - * sample; for example, the size as 8 bit, 16 bit, and the representation as integer or float. - *
    For compressed formats, audio encoding is used to describe the compression scheme being used. + *

    Audio encoding is used to describe the bit representation of audio data, which can be + * either linear PCM or compressed audio, such as AC3 or DTS. + *

    For linear PCM, the audio encoding describes the sample size, 8 bits, 16 bits, or 32 bits, + * and the sample representation, integer or float. + *

    + *

    For compressed audio, the encoding specifies the method of compression, + * for example {@link #ENCODING_AC3} and {@link #ENCODING_DTS}. The compressed + * audio data is typically stored as bytes in + * a byte array or ByteBuffer. When a compressed audio encoding is specified + * for an AudioTrack, it creates a direct (non-mixed) track + * for output to an endpoint (such as HDMI) capable of decoding the compressed audio. + * For (most) other endpoints, which are not capable of decoding such compressed audio, + * you will need to decode the data first, typically by creating a {@link MediaCodec}. + * Alternatively, one may use {@link MediaPlayer} for playback of compressed + * audio files or streams. + *

    When compressed audio is sent out through a direct AudioTrack, + * it need not be written in exact multiples of the audio access unit; + * this differs from MediaCodec input buffers. * *

    Channel mask

    *

    Channel masks are used in AudioTrack and AudioRecord to describe @@ -127,6 +192,22 @@ import java.util.Arrays; * about position it corresponds to, in which case the channel index mask is 0xC. * Multichannel AudioRecord sessions should use channel index masks. * + *

    Audio Frame

    + *

    For linear PCM, an audio frame consists of a set of samples captured at the same time, + * whose count and + * channel association are given by the channel mask, + * and whose sample contents are specified by the encoding. + * For example, a stereo 16 bit PCM frame consists of + * two 16 bit linear PCM samples, with a frame size of 4 bytes. + * For compressed audio, an audio frame may alternately + * refer to an access unit of compressed data bytes that is logically grouped together for + * decoding and bitstream access (e.g. {@link MediaCodec}), + * or a single byte of compressed data (e.g. {@link AudioTrack#getBufferSizeInFrames() + * AudioTrack.getBufferSizeInFrames()}), + * or the linear PCM frame result from decoding the compressed data + * (e.g.{@link AudioTrack#getPlaybackHeadPosition() + * AudioTrack.getPlaybackHeadPosition()}), + * depending on the context where audio frame is used. */ public class AudioFormat { -- cgit v1.1