media: document format keys for MediaMuxer

Bug: 19461810
Change-Id: Iee4396aa6f00b3f580c02fa99f0b9291700f5738

1 files changed, 115 insertions, 0 deletions

diff --git a/media/java/android/media/MediaMuxer.java b/media/java/android/media/MediaMuxer.java
index 7117fbdbf122..e481aa141d6b 100644
--- a/media/java/android/media/MediaMuxer.java
+++ b/media/java/android/media/MediaMuxer.java
@@ -266,6 +266,121 @@ final public class MediaMuxer {
 
     /**
      * 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&hellip;: for listed containers<br>
+     *      MPEG4, AAC&hellip;: 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