Merge "media: document format keys for MediaMuxer" into nyc-dev

    /**

     * 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…: 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