Merge "AudioTrack: moar annotations and getters" (cc0e77b1) · Commits · e / os / android_frameworks_base

api/current.txt

+15 −12

Original line number	Diff line number	Diff line
		@@ -23575,8 +23575,8 @@ package android.media {
		method @NonNull public android.media.AudioAttributes getAudioAttributes();
		method public int getAudioFormat();
		method public int getAudioSessionId();
		method public int getBufferCapacityInFrames();
		method public int getBufferSizeInFrames();
		method @IntRange(from=0) public int getBufferCapacityInFrames();
		method @IntRange(from=0) public int getBufferSizeInFrames();
		method public int getChannelConfiguration();
		method public int getChannelCount();
		method @NonNull public android.media.AudioFormat getFormat();
		@@ -23587,6 +23587,8 @@ package android.media {
		method @Deprecated protected int getNativeFrameCount();
		method public static int getNativeOutputSampleRate(int);
		method public int getNotificationMarkerPosition();
		method @IntRange(from=0) public int getOffloadDelay();
		method @IntRange(from=0) public int getOffloadPadding();
		method public int getPerformanceMode();
		method public int getPlayState();
		method public int getPlaybackHeadPosition();
		@@ -23601,6 +23603,7 @@ package android.media {
		method public boolean getTimestamp(android.media.AudioTimestamp);
		method public int getUnderrunCount();
		method public static boolean isDirectPlaybackSupported(@NonNull android.media.AudioFormat, @NonNull android.media.AudioAttributes);
		method public boolean isOffloadedPlayback();
		method public void pause() throws java.lang.IllegalStateException;
		method public void play() throws java.lang.IllegalStateException;
		method public void registerStreamEventCallback(@NonNull java.util.concurrent.Executor, @NonNull android.media.AudioTrack.StreamEventCallback);
		@@ -23608,13 +23611,13 @@ package android.media {
		method public int reloadStaticData();
		method public void removeOnRoutingChangedListener(android.media.AudioRouting.OnRoutingChangedListener);
		method @Deprecated public void removeOnRoutingChangedListener(android.media.AudioTrack.OnRoutingChangedListener);
		method public int setAuxEffectSendLevel(float);
		method public int setBufferSizeInFrames(int);
		method public int setLoopPoints(int, int, int);
		method public int setAuxEffectSendLevel(@FloatRange(from=0.0) float);
		method public int setBufferSizeInFrames(@IntRange(from=0) int);
		method public int setLoopPoints(@IntRange(from=0) int, @IntRange(from=0) int, @IntRange(from=0xffffffff) int);
		method public int setNotificationMarkerPosition(int);
		method public void setOffloadDelayPadding(int, int);
		method public void setOffloadDelayPadding(@IntRange(from=0) int, @IntRange(from=0) int);
		method public void setOffloadEndOfStream();
		method public int setPlaybackHeadPosition(int);
		method public int setPlaybackHeadPosition(@IntRange(from=0) int);
		method public void setPlaybackParams(@NonNull android.media.PlaybackParams);
		method public void setPlaybackPositionUpdateListener(android.media.AudioTrack.OnPlaybackPositionUpdateListener);
		method public void setPlaybackPositionUpdateListener(android.media.AudioTrack.OnPlaybackPositionUpdateListener, android.os.Handler);
		@@ -23659,10 +23662,10 @@ package android.media {
		method @NonNull public android.media.AudioTrack build() throws java.lang.UnsupportedOperationException;
		method @NonNull public android.media.AudioTrack.Builder setAudioAttributes(@NonNull android.media.AudioAttributes) throws java.lang.IllegalArgumentException;
		method @NonNull public android.media.AudioTrack.Builder setAudioFormat(@NonNull android.media.AudioFormat) throws java.lang.IllegalArgumentException;
		method @NonNull public android.media.AudioTrack.Builder setBufferSizeInBytes(int) throws java.lang.IllegalArgumentException;
		method @NonNull public android.media.AudioTrack.Builder setBufferSizeInBytes(@IntRange(from=0) int) throws java.lang.IllegalArgumentException;
		method @NonNull public android.media.AudioTrack.Builder setOffloadedPlayback(boolean);
		method @NonNull public android.media.AudioTrack.Builder setPerformanceMode(int);
		method @NonNull public android.media.AudioTrack.Builder setSessionId(int) throws java.lang.IllegalArgumentException;
		method @NonNull public android.media.AudioTrack.Builder setSessionId(@IntRange(from=1) int) throws java.lang.IllegalArgumentException;
		method @NonNull public android.media.AudioTrack.Builder setTransferMode(int) throws java.lang.IllegalArgumentException;
		}

		@@ -23686,9 +23689,9 @@ package android.media {

		public abstract static class AudioTrack.StreamEventCallback {
		ctor public AudioTrack.StreamEventCallback();
		method public void onDataRequest(android.media.AudioTrack, int);
		method public void onPresentationEnded(android.media.AudioTrack);
		method public void onTearDown(android.media.AudioTrack);
		method public void onDataRequest(@NonNull android.media.AudioTrack, int);
		method public void onPresentationEnded(@NonNull android.media.AudioTrack);
		method public void onTearDown(@NonNull android.media.AudioTrack);
		}

		public class CallbackDataSourceDesc extends android.media.DataSourceDesc {

media/java/android/media/AudioTrack.java

+71 −12

Original line number	Diff line number	Diff line
		@@ -17,7 +17,9 @@
		package android.media;

		import android.annotation.CallbackExecutor;
		import android.annotation.FloatRange;
		import android.annotation.IntDef;
		import android.annotation.IntRange;
		import android.annotation.NonNull;
		import android.annotation.Nullable;
		import android.annotation.UnsupportedAppUsage;
		@@ -389,6 +391,14 @@ public class AudioTrack extends PlayerBase
		* Indicates whether the track is intended to play in offload mode.
		*/
		private boolean mOffloaded = false;
		/**
		* When offloaded track: delay for decoder in frames
		*/
		private int mOffloadDelayFrames = 0;
		/**
		* When offloaded track: padding for decoder in frames
		*/
		private int mOffloadPaddingFrames = 0;

		//--------------------------------
		// Used exclusively by native code
		@@ -827,7 +837,7 @@ public class AudioTrack extends PlayerBase
		* @return the same Builder instance.
		* @throws IllegalArgumentException
		*/
		public @NonNull Builder setBufferSizeInBytes(int bufferSizeInBytes)
		public @NonNull Builder setBufferSizeInBytes(@IntRange(from = 0) int bufferSizeInBytes)
		throws IllegalArgumentException {
		if (bufferSizeInBytes <= 0) {
		throw new IllegalArgumentException("Invalid buffer size " + bufferSizeInBytes);
		@@ -865,7 +875,7 @@ public class AudioTrack extends PlayerBase
		* @return the same Builder instance.
		* @throws IllegalArgumentException
		*/
		public @NonNull Builder setSessionId(int sessionId)
		public @NonNull Builder setSessionId(@IntRange(from = 1) int sessionId)
		throws IllegalArgumentException {
		if ((sessionId != AudioManager.AUDIO_SESSION_ID_GENERATE) && (sessionId < 1)) {
		throw new IllegalArgumentException("Invalid audio session ID " + sessionId);
		@@ -1007,7 +1017,8 @@ public class AudioTrack extends PlayerBase
		* @param paddingInFrames number of frames to be ignored at the end of the stream. A value of 0
		* of 0 indicates no delay is to be applied.
		*/
		public void setOffloadDelayPadding(int delayInFrames, int paddingInFrames) {
		public void setOffloadDelayPadding(@IntRange(from = 0) int delayInFrames,
		@IntRange(from = 0) int paddingInFrames) {
		if (paddingInFrames < 0) {
		throw new IllegalArgumentException("Illegal negative padding");
		}
		@@ -1020,9 +1031,47 @@ public class AudioTrack extends PlayerBase
		if (mState == STATE_UNINITIALIZED) {
		throw new IllegalStateException("Uninitialized track");
		}
		mOffloadDelayFrames = delayInFrames;
		mOffloadPaddingFrames = paddingInFrames;
		native_set_delay_padding(delayInFrames, paddingInFrames);
		}

		/**
		* Return the decoder delay of an offloaded track, expressed in frames, previously set with
		* {@link #setOffloadDelayPadding(int, int)}, or 0 if it was never modified.
		* <p>This delay indicates the number of frames to be ignored at the beginning of the stream.
		* This value can only be queried on a track successfully initialized with
		* {@link AudioTrack.Builder#setOffloadedPlayback(boolean)}.
		* @return decoder delay expressed in frames.
		*/
		public @IntRange(from = 0) int getOffloadDelay() {
		if (!mOffloaded) {
		throw new IllegalStateException("Illegal query of delay on non-offloaded track");
		}
		if (mState == STATE_UNINITIALIZED) {
		throw new IllegalStateException("Illegal query of delay on uninitialized track");
		}
		return mOffloadDelayFrames;
		}

		/**
		* Return the decoder padding of an offloaded track, expressed in frames, previously set with
		* {@link #setOffloadDelayPadding(int, int)}, or 0 if it was never modified.
		* <p>This padding indicates the number of frames to be ignored at the end of the stream.
		* This value can only be queried on a track successfully initialized with
		* {@link AudioTrack.Builder#setOffloadedPlayback(boolean)}.
		* @return decoder padding expressed in frames.
		*/
		public @IntRange(from = 0) int getOffloadPadding() {
		if (!mOffloaded) {
		throw new IllegalStateException("Illegal query of padding on non-offloaded track");
		}
		if (mState == STATE_UNINITIALIZED) {
		throw new IllegalStateException("Illegal query of padding on uninitialized track");
		}
		return mOffloadPaddingFrames;
		}

		/**
		* Declares that the last write() operation on this track provided the last buffer of this
		* stream.
		@@ -1039,6 +1088,15 @@ public class AudioTrack extends PlayerBase
		native_set_eos();
		}

		/**
		* Returns whether the track was built with {@link Builder#setOffloadedPlayback(boolean)} set
		* to {@code true}.
		* @return true if the track is using offloaded playback.
		*/
		public boolean isOffloadedPlayback() {
		return mOffloaded;
		}

		/**
		* Returns whether direct playback of an audio format with the provided attributes is
		* currently supported on the system.
		@@ -1491,7 +1549,7 @@ public class AudioTrack extends PlayerBase
		* @return current size in frames of the <code>AudioTrack</code> buffer.
		* @throws IllegalStateException if track is not initialized.
		*/
		public int getBufferSizeInFrames() {
		public @IntRange (from = 0) int getBufferSizeInFrames() {
		return native_get_buffer_size_frames();
		}

		@@ -1518,7 +1576,7 @@ public class AudioTrack extends PlayerBase
		* {@link #ERROR_BAD_VALUE}, {@link #ERROR_INVALID_OPERATION}
		* @throws IllegalStateException if track is not initialized.
		*/
		public int setBufferSizeInFrames(int bufferSizeInFrames) {
		public int setBufferSizeInFrames(@IntRange (from = 0) int bufferSizeInFrames) {
		if (mDataLoadMode == MODE_STATIC \|\| mState == STATE_UNINITIALIZED) {
		return ERROR_INVALID_OPERATION;
		}
		@@ -1547,7 +1605,7 @@ public class AudioTrack extends PlayerBase
		* @return maximum size in frames of the <code>AudioTrack</code> buffer.
		* @throws IllegalStateException if track is not initialized.
		*/
		public int getBufferCapacityInFrames() {
		public @IntRange (from = 0) int getBufferCapacityInFrames() {
		return native_get_buffer_capacity_frames();
		}

		@@ -2054,7 +2112,7 @@ public class AudioTrack extends PlayerBase
		* @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},
		* {@link #ERROR_INVALID_OPERATION}
		*/
		public int setPlaybackHeadPosition(int positionInFrames) {
		public int setPlaybackHeadPosition(@IntRange (from = 0) int positionInFrames) {
		if (mDataLoadMode == MODE_STREAM \|\| mState == STATE_UNINITIALIZED \|\|
		getPlayState() == PLAYSTATE_PLAYING) {
		return ERROR_INVALID_OPERATION;
		@@ -2096,7 +2154,8 @@ public class AudioTrack extends PlayerBase
		* @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},
		* {@link #ERROR_INVALID_OPERATION}
		*/
		public int setLoopPoints(int startInFrames, int endInFrames, int loopCount) {
		public int setLoopPoints(@IntRange (from = 0) int startInFrames,
		@IntRange (from = 0) int endInFrames, @IntRange (from = -1) int loopCount) {
		if (mDataLoadMode == MODE_STREAM \|\| mState == STATE_UNINITIALIZED \|\|
		getPlayState() == PLAYSTATE_PLAYING) {
		return ERROR_INVALID_OPERATION;
		@@ -2849,7 +2908,7 @@ public class AudioTrack extends PlayerBase
		* @return error code or success, see {@link #SUCCESS},
		* {@link #ERROR_INVALID_OPERATION}, {@link #ERROR}
		*/
		public int setAuxEffectSendLevel(float level) {
		public int setAuxEffectSendLevel(@FloatRange(from = 0.0) float level) {
		if (mState == STATE_UNINITIALIZED) {
		return ERROR_INVALID_OPERATION;
		}
		@@ -3095,21 +3154,21 @@ public class AudioTrack extends PlayerBase
		* gets invalidated by the system to prevent any other offload.
		* @param track the {@link AudioTrack} on which the event happened.
		*/
		public void onTearDown(AudioTrack track) { }
		public void onTearDown(@NonNull AudioTrack track) { }
		/**
		* Called when all the buffers of an offloaded track that were queued in the audio system
		* (e.g. the combination of the Android audio framework and the device's audio hardware)
		* have been played after {@link AudioTrack#stop()} has been called.
		* @param track the {@link AudioTrack} on which the event happened.
		*/
		public void onPresentationEnded(AudioTrack track) { }
		public void onPresentationEnded(@NonNull AudioTrack track) { }
		/**
		* Called when more audio data can be written without blocking on an offloaded track.
		* @param track the {@link AudioTrack} on which the event happened.
		* @param sizeInFrames the number of frames available to write without blocking.
		* Note that the frame size of a compressed stream is 1 byte.
		*/
		public void onDataRequest(AudioTrack track, int sizeInFrames) { }
		public void onDataRequest(@NonNull AudioTrack track, int sizeInFrames) { }
		}

		/**