Merge "media: document format keys for MediaMuxer" into nyc-dev
diff --git a/media/java/android/media/MediaMuxer.java b/media/java/android/media/MediaMuxer.java
index 7117fbd..e481aa1 100644
--- a/media/java/android/media/MediaMuxer.java
+++ b/media/java/android/media/MediaMuxer.java
@@ -266,6 +266,121 @@
/**
* Adds a track with the specified format.
+ * <p>
+ * The following table summarizes support for specific format keys across android releases.
+ * Keys marked with '+:' are required.
+ *
+ * <table style="width: 0%">
+ * <thead>
+ * <tr>
+ * <th rowspan=2>OS Version(s)</th>
+ * <td colspan=3>{@code MediaFormat} keys used for</th>
+ * </tr><tr>
+ * <th>All Tracks</th>
+ * <th>Audio Tracks</th>
+ * <th>Video Tracks</th>
+ * </tr>
+ * </thead>
+ * <tbody>
+ * <tr>
+ * <td>{@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2}</td>
+ * <td rowspan=7>+: {@link MediaFormat#KEY_MIME}</td>
+ * <td rowspan=3>+: {@link MediaFormat#KEY_SAMPLE_RATE},<br>
+ * +: {@link MediaFormat#KEY_CHANNEL_COUNT},<br>
+ * +: <strong>codec-specific data<sup>AAC</sup></strong></td>
+ * <td rowspan=5>+: {@link MediaFormat#KEY_WIDTH},<br>
+ * +: {@link MediaFormat#KEY_HEIGHT},<br>
+ * no {@code KEY_ROTATION},
+ * use {@link #setOrientationHint setOrientationHint()}<sup>.mp4</sup>,<br>
+ * +: <strong>codec-specific data<sup>AVC, MPEG4</sup></strong></td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#KITKAT}</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#KITKAT_WATCH}</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#LOLLIPOP}</td>
+ * <td rowspan=4>as above, plus<br>
+ * +: <strong>codec-specific data<sup>Vorbis & .webm</sup></strong></td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1}</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#M}</td>
+ * <td>as above, plus<br>
+ * {@link MediaFormat#KEY_BIT_RATE}<sup>AAC</sup></td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#N}</td>
+ * <td>as above, plus<br>
+ * <!-- {link MediaFormat#KEY_MAX_BIT_RATE}<sup>AAC, MPEG4</sup>,<br> -->
+ * {@link MediaFormat#KEY_BIT_RATE}<sup>MPEG4</sup>,<br>
+ * {@link MediaFormat#KEY_HDR_STATIC_INFO}<sup>#, .webm</sup>,<br>
+ * {@link MediaFormat#KEY_COLOR_STANDARD}<sup>#</sup>,<br>
+ * {@link MediaFormat#KEY_COLOR_TRANSFER}<sup>#</sup>,<br>
+ * {@link MediaFormat#KEY_COLOR_RANGE}<sup>#</sup>,<br>
+ * +: <strong>codec-specific data<sup>HEVC</sup></strong>,<br>
+ * codec-specific data<sup>VP9</sup></td>
+ * </tr>
+ * <tr>
+ * <td colspan=4>
+ * <p class=note><strong>Notes:</strong><br>
+ * #: storing into container metadata.<br>
+ * .mp4, .webm…: for listed containers<br>
+ * MPEG4, AAC…: for listed codecs
+ * </td>
+ * </tr><tr>
+ * <td colspan=4>
+ * <p class=note>Note that the codec-specific data for the track must be specified using
+ * this method. Furthermore, codec-specific data must not be passed/specified via the
+ * {@link #writeSampleData writeSampleData()} call.
+ * </td>
+ * </tr>
+ * </tbody>
+ * </table>
+ *
+ * <p>
+ * The following table summarizes codec support for containers across android releases:
+ *
+ * <table style="width: 0%">
+ * <thead>
+ * <tr>
+ * <th rowspan=2>OS Version(s)</th>
+ * <td colspan=3>Codec support</th>
+ * </tr><tr>
+ * <th>{@linkplain OutputFormat#MUXER_OUTPUT_MPEG_4 MP4}</th>
+ * <th>{@linkplain OutputFormat#MUXER_OUTPUT_WEBM WEBM}</th>
+ * </tr>
+ * </thead>
+ * <tbody>
+ * <tr>
+ * <td>{@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2}</td>
+ * <td rowspan=6>{@link MediaFormat#MIMETYPE_AUDIO_AAC AAC},<br>
+ * {@link MediaFormat#MIMETYPE_AUDIO_AMR_NB NB-AMR},<br>
+ * {@link MediaFormat#MIMETYPE_AUDIO_AMR_WB WB-AMR},<br>
+ * {@link MediaFormat#MIMETYPE_VIDEO_H263 H.263},<br>
+ * {@link MediaFormat#MIMETYPE_VIDEO_MPEG4 MPEG-4},<br>
+ * {@link MediaFormat#MIMETYPE_VIDEO_AVC AVC} (H.264)</td>
+ * <td rowspan=3>Not supported</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#KITKAT}</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#KITKAT_WATCH}</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#LOLLIPOP}</td>
+ * <td rowspan=3>{@link MediaFormat#MIMETYPE_AUDIO_VORBIS Vorbis},<br>
+ * {@link MediaFormat#MIMETYPE_VIDEO_VP8 VP8}</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1}</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#M}</td>
+ * </tr><tr>
+ * <td>{@link android.os.Build.VERSION_CODES#N}</td>
+ * <td>as above, plus<br>
+ * {@link MediaFormat#MIMETYPE_VIDEO_HEVC HEVC} (H.265)</td>
+ * <td>as above, plus<br>
+ * {@link MediaFormat#MIMETYPE_VIDEO_VP9 VP9}</td>
+ * </tr>
+ * </tbody>
+ * </table>
+ *
* @param format The media format for the track. This must not be an empty
* MediaFormat.
* @return The track index for this newly added track, and it should be used