Merge "media: clarify the use of profiles for MediaCodec encoders" am: 933a0c09f8 (17b3833c) · Commits · e / os / android_frameworks_base

media/java/android/media/MediaCodec.java

+45 −0

Original line number	Original line	Diff line number	Diff line
	@@ -359,6 +359,51 @@ import java.util.concurrent.locks.ReentrantLock;
	codec to use a previously created {@linkplain #createPersistentInputSurface persistent input		codec to use a previously created {@linkplain #createPersistentInputSurface persistent input
	surface} by calling {@link #setInputSurface}.		surface} by calling {@link #setInputSurface}.

			<h4 id=EncoderProfiles><a name="EncoderProfiles"></a>Encoder Profiles</h4>
			<p>
			When using an encoder, it is recommended to set the desired codec {@link MediaFormat#KEY_PROFILE
			profile} during {@link #configure configure()}. (This is only meaningful for
			{@link MediaFormat#KEY_MIME media formats} for which profiles are defined.)
			<p>
			If a profile is not specified during {@code configure}, the encoder will choose a profile for the
			session based on the available information. We will call this value the <i>default profile</i>.
			The selection of the default profile is device specific and may not be deterministic
			(could be ad hoc or even experimental). The encoder may choose a default profile that is not
			suitable for the intended encoding session, which may result in the encoder ultimately rejecting
			the session.
			<p>
			The encoder may reject the encoding session if the configured (or default if unspecified) profile
			does not support the codec input (mainly the {@link MediaFormat#KEY_COLOR_FORMAT color format} for
			video/image codecs, or the {@link MediaFormat#KEY_PCM_ENCODING sample encoding} and the {@link
			MediaFormat#KEY_CHANNEL_COUNT number of channels} for audio codecs, but also possibly
			{@link MediaFormat#KEY_WIDTH width}, {@link MediaFormat#KEY_HEIGHT height},
			{@link MediaFormat#KEY_FRAME_RATE frame rate}, {@link MediaFormat#KEY_BIT_RATE bitrate} or
			{@link MediaFormat#KEY_SAMPLE_RATE sample rate}.)
			Alternatively, the encoder may choose to (but is not required to) convert the input to support the
			selected (or default) profile - or adjust the chosen profile based on the presumed or detected
			input format - to ensure a successful encoding session. <b>Note</b>: Converting the input to match
			an incompatible profile will in most cases result in decreased codec performance.
			<p>
			To ensure backward compatibility, the following guarantees are provided by Android:
			<ul>
			<li>The default video encoder profile always supports 8-bit YUV 4:2:0 color format ({@link
			CodecCapabilities#COLOR_FormatYUV420Flexible COLOR_FormatYUV420Flexible} and equivalent
			{@link CodecCapabilities#colorFormats supported formats}) for both Surface and ByteBuffer modes.
			<li>The default video encoder profile always supports the default 8-bit RGBA color format in
			Surface mode even if no such formats are enumerated in the {@link CodecCapabilities#colorFormats
			supported formats}.
			</ul>
			<p class=note>
			<b>Note</b>: the accepted profile can be queried through the {@link #getOutputFormat output
			format} of the encoder after {@code configure} to allow applications to set up their
			codec input to a format supported by the encoder profile.
			<p>
			<b>Implication:</b>
			<ul>
			<li>Applications that want to encode 4:2:2, 4:4:4, 10+ bit or HDR video input <b>MUST</b> configure
			a suitable profile for encoders.
			</ul>

	<h4 id=CSD><a name="CSD"></a>Codec-specific Data</h4>		<h4 id=CSD><a name="CSD"></a>Codec-specific Data</h4>
	<p>		<p>
	Some formats, notably AAC audio and MPEG4, H.264 and H.265 video formats require the actual data		Some formats, notably AAC audio and MPEG4, H.264 and H.265 video formats require the actual data

media/java/android/media/MediaFormat.java

+4 −1

Original line number	Original line	Diff line number	Diff line
	@@ -1097,11 +1097,14 @@ public final class MediaFormat {
	* may fail if other parameters are not compatible with the desired		* may fail if other parameters are not compatible with the desired
	* profile or if the desired profile is not supported, but it may also		* profile or if the desired profile is not supported, but it may also
	* fail silently (where the encoder ends up using a different, compatible profile.)		* fail silently (where the encoder ends up using a different, compatible profile.)
			* <p>
			* It is recommended that the profile is set for all encoders. For more information, see
			* the <i>Encoder Profiles</i> section of the {@link MediaCodec} API reference.
	* <p class="note">		* <p class="note">
	* <strong>Note:</strong> Codecs are free to use all the available		* <strong>Note:</strong> Codecs are free to use all the available
	* coding tools at the specified profile, but may ultimately choose to not do so.		* coding tools at the specified profile, but may ultimately choose to not do so.
	* <p class="note">		* <p class="note">
	* <strong>Note:</strong> When configuring video encoders, profile must be		* <strong>Note:</strong> When configuring video encoders, profile (if set) must be
	* set together with {@link #KEY_LEVEL level}.		* set together with {@link #KEY_LEVEL level}.
	*		*
	* @see MediaCodecInfo.CodecCapabilities#profileLevels		* @see MediaCodecInfo.CodecCapabilities#profileLevels