gst/isomp4/gstqtmux-doc.c

   1 /* Quicktime muxer documentation
   2  * Copyright (C) 2008-2010 Thiago Santos <thiagoss@embedded.ufcg.edu.br>
   3  * Copyright (C) 2008 Mark Nauwelaerts <mnauw@users.sf.net>
   4  * Copyright (C) 2010 Nokia Corporation. All rights reserved.
   5  * Contact: Stefan Kost <stefan.kost@nokia.com>
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22 /*
  23  * Unless otherwise indicated, Source Code is licensed under MIT license.
  24  * See further explanation attached in License Statement (distributed in the file
  25  * LICENSE).
  26  *
  27  * Permission is hereby granted, free of charge, to any person obtaining a copy of
  28  * this software and associated documentation files (the "Software"), to deal in
  29  * the Software without restriction, including without limitation the rights to
  30  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
  31  * of the Software, and to permit persons to whom the Software is furnished to do
  32  * so, subject to the following conditions:
  33  *
  34  * The above copyright notice and this permission notice shall be included in all
  35  * copies or substantial portions of the Software.
  36  *
  37  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  38  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  39  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  40  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  41  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  42  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  43  * SOFTWARE.
  44  */
  45
  46 /* ============================= mp4mux ==================================== */
  47
  48 /**
  49  * SECTION:element-mp4mux
  50  * @short_description: Muxer for ISO MPEG-4 (.mp4) files
  51  *
  52  * This element merges streams (audio and video) into ISO MPEG-4 (.mp4) files.
  53  *
  54  * The following background intends to explain why various similar muxers
  55  * are present in this plugin.
  56  *
  57  * The <ulink url="http://www.apple.com/quicktime/resources/qtfileformat.pdf">
  58  * QuickTime file format specification</ulink> served as basis for the MP4 file
  59  * format specification (mp4mux), and as such the QuickTime file structure is
  60  * nearly identical to the so-called ISO Base Media file format defined in
  61  * ISO 14496-12 (except for some media specific parts).
  62  * In turn, the latter ISO Base Media format was further specialized as a
  63  * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux)
  64  * and in various 3GPP(2) specs (gppmux).
  65  * The fragmented file features defined (only) in ISO Base Media are used by
  66  * ISMV files making up (a.o.) Smooth Streaming (ismlmux).
  67  *
  68  * A few properties (<link linkend="GstMP4Mux--movie-timescale">movie-timescale</link>,
  69  * <link linkend="GstMP4Mux--trak-timescale">trak-timescale</link>) allow adjusting
  70  * some technical parameters, which might be useful in (rare) cases to resolve
  71  * compatibility issues in some situations.
  72  *
  73  * Some other properties influence the result more fundamentally.
  74  * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file,
  75  * somewhat contrary to this usually being called "the header".
  76  * However, a <link linkend="GstMP4Mux--faststart">faststart</link> file will
  77  * (with some effort) arrange this to be located near start of the file,
  78  * which then allows it e.g. to be played while downloading.
  79  * Alternatively, rather than having one chunk of metadata at start (or end),
  80  * there can be some metadata at start and most of the other data can be spread
  81  * out into fragments of <link linkend="GstMP4Mux--fragment-duration">fragment-duration</link>.
  82  * If such fragmented layout is intended for streaming purposes, then
  83  * <link linkend="GstMP4Mux--streamable">streamable</link> allows foregoing to add
  84  * index metadata (at the end of file).
  85  *
  86  * <link linkend="GstMP4Mux--dts-method">dts-method</link> allows selecting a
  87  * method for managing input timestamps (stay tuned for 0.11 to have this
  88  * automagically settled).  The default delta/duration method should handle nice
  89  * (aka perfect streams) just fine, but may experience problems otherwise
  90  * (e.g. input stream with re-ordered B-frames and/or with frame dropping).
  91  * The re-ordering approach re-assigns incoming timestamps in ascending order
  92  * to incoming buffers and offers an alternative in such cases.  In cases where
  93  * that might fail, the remaining method can be tried, which is exact and
  94  * according to specs, but might experience playback on not so spec-wise players.
  95  * Note that this latter approach also requires one to enable
  96  * <link linkend="GstMP4Mux--presentation-timestamp">presentation-timestamp</link>.
  97  *
  98  * <refsect2>
  99  * <title>Example pipelines</title>
 100  * |[
 101  * gst-launch gst-launch v4l2src num-buffers=50 ! queue ! x264enc ! mp4mux ! filesink location=video.mp4
 102  * ]|
 103  * Records a video stream captured from a v4l2 device, encodes it into H.264
 104  * and muxes it into an mp4 file.
 105  * </refsect2>
 106  *
 107  * Documentation last reviewed on 2011-04-21
 108  */
 109
 110 /* ============================= 3gppmux ==================================== */
 111
 112 /**
 113  * SECTION:element-3gppmux
 114  * @short_description: Muxer for 3GPP (.3gp) files
 115  *
 116  * This element merges streams (audio and video) into 3GPP (.3gp) files.
 117  *
 118  * The following background intends to explain why various similar muxers
 119  * are present in this plugin.
 120  *
 121  * The <ulink url="http://www.apple.com/quicktime/resources/qtfileformat.pdf">
 122  * QuickTime file format specification</ulink> served as basis for the MP4 file
 123  * format specification (mp4mux), and as such the QuickTime file structure is
 124  * nearly identical to the so-called ISO Base Media file format defined in
 125  * ISO 14496-12 (except for some media specific parts).
 126  * In turn, the latter ISO Base Media format was further specialized as a
 127  * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux)
 128  * and in various 3GPP(2) specs (gppmux).
 129  * The fragmented file features defined (only) in ISO Base Media are used by
 130  * ISMV files making up (a.o.) Smooth Streaming (ismlmux).
 131  *
 132  * A few properties (<link linkend="Gst3GPPMux--movie-timescale">movie-timescale</link>,
 133  * <link linkend="Gst3GPPMux--trak-timescale">trak-timescale</link>) allow adjusting
 134  * some technical parameters, which might be useful in (rare) cases to resolve
 135  * compatibility issues in some situations.
 136  *
 137  * Some other properties influence the result more fundamentally.
 138  * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file,
 139  * somewhat contrary to this usually being called "the header".
 140  * However, a <link linkend="Gst3GPPMux--faststart">faststart</link> file will
 141  * (with some effort) arrange this to be located near start of the file,
 142  * which then allows it e.g. to be played while downloading.
 143  * Alternatively, rather than having one chunk of metadata at start (or end),
 144  * there can be some metadata at start and most of the other data can be spread
 145  * out into fragments of <link linkend="Gst3GPPMux--fragment-duration">fragment-duration</link>.
 146  * If such fragmented layout is intended for streaming purposes, then
 147  * <link linkend="Gst3GPPMux--streamable">streamable</link> allows foregoing to add
 148  * index metadata (at the end of file).
 149  *
 150  * <link linkend="Gst3GPPMux--dts-method">dts-method</link> allows selecting a
 151  * method for managing input timestamps (stay tuned for 0.11 to have this
 152  * automagically settled).  The default delta/duration method should handle nice
 153  * (aka perfect streams) just fine, but may experience problems otherwise
 154  * (e.g. input stream with re-ordered B-frames and/or with frame dropping).
 155  * The re-ordering approach re-assigns incoming timestamps in ascending order
 156  * to incoming buffers and offers an alternative in such cases.  In cases where
 157  * that might fail, the remaining method can be tried, which is exact and
 158  * according to specs, but might experience playback on not so spec-wise players.
 159  * Note that this latter approach also requires one to enable
 160  * <link linkend="Gst3GPPMux--presentation-timestamp">presentation-timestamp</link>.
 161  *
 162  * <refsect2>
 163  * <title>Example pipelines</title>
 164  * |[
 165  * gst-launch v4l2src num-buffers=50 ! queue ! ffenc_h263 ! gppmux ! filesink location=video.3gp
 166  * ]|
 167  * Records a video stream captured from a v4l2 device, encodes it into H.263
 168  * and muxes it into an 3gp file.
 169  * </refsect2>
 170  *
 171  * Documentation last reviewed on 2011-04-21
 172  */
 173
 174 /* ============================= mj2pmux ==================================== */
 175
 176 /**
 177  * SECTION:element-mj2mux
 178  * @short_description: Muxer for Motion JPEG-2000 (.mj2) files
 179  *
 180  * This element merges streams (audio and video) into MJ2 (.mj2) files.
 181  *
 182  * The following background intends to explain why various similar muxers
 183  * are present in this plugin.
 184  *
 185  * The <ulink url="http://www.apple.com/quicktime/resources/qtfileformat.pdf">
 186  * QuickTime file format specification</ulink> served as basis for the MP4 file
 187  * format specification (mp4mux), and as such the QuickTime file structure is
 188  * nearly identical to the so-called ISO Base Media file format defined in
 189  * ISO 14496-12 (except for some media specific parts).
 190  * In turn, the latter ISO Base Media format was further specialized as a
 191  * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux)
 192  * and in various 3GPP(2) specs (gppmux).
 193  * The fragmented file features defined (only) in ISO Base Media are used by
 194  * ISMV files making up (a.o.) Smooth Streaming (ismlmux).
 195  *
 196  * A few properties (<link linkend="GstMJ2Mux--movie-timescale">movie-timescale</link>,
 197  * <link linkend="GstMJ2Mux--trak-timescale">trak-timescale</link>) allow adjusting
 198  * some technical parameters, which might be useful in (rare) cases to resolve
 199  * compatibility issues in some situations.
 200  *
 201  * Some other properties influence the result more fundamentally.
 202  * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file,
 203  * somewhat contrary to this usually being called "the header".
 204  * However, a <link linkend="GstMJ2Mux--faststart">faststart</link> file will
 205  * (with some effort) arrange this to be located near start of the file,
 206  * which then allows it e.g. to be played while downloading.
 207  * Alternatively, rather than having one chunk of metadata at start (or end),
 208  * there can be some metadata at start and most of the other data can be spread
 209  * out into fragments of <link linkend="GstMJ2Mux--fragment-duration">fragment-duration</link>.
 210  * If such fragmented layout is intended for streaming purposes, then
 211  * <link linkend="GstMJ2Mux--streamable">streamable</link> allows foregoing to add
 212  * index metadata (at the end of file).
 213  *
 214  * <link linkend="GstMJ2Mux--dts-method">dts-method</link> allows selecting a
 215  * method for managing input timestamps (stay tuned for 0.11 to have this
 216  * automagically settled).  The default delta/duration method should handle nice
 217  * (aka perfect streams) just fine, but may experience problems otherwise
 218  * (e.g. input stream with re-ordered B-frames and/or with frame dropping).
 219  * The re-ordering approach re-assigns incoming timestamps in ascending order
 220  * to incoming buffers and offers an alternative in such cases.  In cases where
 221  * that might fail, the remaining method can be tried, which is exact and
 222  * according to specs, but might experience playback on not so spec-wise players.
 223  * Note that this latter approach also requires one to enable
 224  * <link linkend="GstMJ2Mux--presentation-timestamp">presentation-timestamp</link>.
 225  *
 226  * <refsect2>
 227  * <title>Example pipelines</title>
 228  * |[
 229  * gst-launch v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2
 230  * ]|
 231  * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000
 232  * and muxes it into an mj2 file.
 233  * </refsect2>
 234  *
 235  * Documentation last reviewed on 2011-04-21
 236  */
 237
 238 /* ============================= ismlmux ==================================== */
 239
 240 /**
 241  * SECTION:element-ismlmux
 242  * @short_description: Muxer for ISML smooth streaming (.isml) files
 243  *
 244  * This element merges streams (audio and video) into MJ2 (.mj2) files.
 245  *
 246  * The following background intends to explain why various similar muxers
 247  * are present in this plugin.
 248  *
 249  * The <ulink url="http://www.apple.com/quicktime/resources/qtfileformat.pdf">
 250  * QuickTime file format specification</ulink> served as basis for the MP4 file
 251  * format specification (mp4mux), and as such the QuickTime file structure is
 252  * nearly identical to the so-called ISO Base Media file format defined in
 253  * ISO 14496-12 (except for some media specific parts).
 254  * In turn, the latter ISO Base Media format was further specialized as a
 255  * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux)
 256  * and in various 3GPP(2) specs (gppmux).
 257  * The fragmented file features defined (only) in ISO Base Media are used by
 258  * ISMV files making up (a.o.) Smooth Streaming (ismlmux).
 259  *
 260  * A few properties (<link linkend="GstISMLMux--movie-timescale">movie-timescale</link>,
 261  * <link linkend="GstISMLMux--trak-timescale">trak-timescale</link>) allow adjusting
 262  * some technical parameters, which might be useful in (rare) cases to resolve
 263  * compatibility issues in some situations.
 264  *
 265  * Some other properties influence the result more fundamentally.
 266  * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file,
 267  * somewhat contrary to this usually being called "the header".
 268  * However, a <link linkend="GstISMLMux--faststart">faststart</link> file will
 269  * (with some effort) arrange this to be located near start of the file,
 270  * which then allows it e.g. to be played while downloading.
 271  * Alternatively, rather than having one chunk of metadata at start (or end),
 272  * there can be some metadata at start and most of the other data can be spread
 273  * out into fragments of <link linkend="GstISMLMux--fragment-duration">fragment-duration</link>.
 274  * If such fragmented layout is intended for streaming purposes, then
 275  * <link linkend="GstISMLMux--streamable">streamable</link> allows foregoing to add
 276  * index metadata (at the end of file).
 277  *
 278  * <link linkend="GstISMLMux--dts-method">dts-method</link> allows selecting a
 279  * method for managing input timestamps (stay tuned for 0.11 to have this
 280  * automagically settled).  The default delta/duration method should handle nice
 281  * (aka perfect streams) just fine, but may experience problems otherwise
 282  * (e.g. input stream with re-ordered B-frames and/or with frame dropping).
 283  * The re-ordering approach re-assigns incoming timestamps in ascending order
 284  * to incoming buffers and offers an alternative in such cases.  In cases where
 285  * that might fail, the remaining method can be tried, which is exact and
 286  * according to specs, but might experience playback on not so spec-wise players.
 287  * Note that this latter approach also requires one to enable
 288  * <link linkend="GstISMLMux--presentation-timestamp">presentation-timestamp</link>.
 289  *
 290  * <refsect2>
 291  * <title>Example pipelines</title>
 292  * |[
 293  * gst-launch v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2
 294  * ]|
 295  * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000
 296  * and muxes it into an mj2 file.
 297  * </refsect2>
 298  *
 299  * Documentation last reviewed on 2011-04-21
 300  */