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., 51 Franklin St, Fifth Floor,
  20  * Boston, MA 02110-1301, 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 (3gppmux).
  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 (#GstMp4Mux:movie-timescale, #GstMp4Mux:trak-timescale)
  69  * allow adjusting some technical parameters, which might be useful in (rare)
  70  * cases to resolve compatibility issues in some situations.
  71  *
  72  * Some other properties influence the result more fundamentally.
  73  * A typical mov/mp4 file's metadata (aka moov) is located at the end of the
  74  * file, somewhat contrary to this usually being called "the header".
  75  * However, a #GstMp4Mux:faststart file will (with some effort) arrange this to
  76  * be located near start of the file, which then allows it e.g. to be played
  77  * while downloading. Alternatively, rather than having one chunk of metadata at
  78  * start (or end), there can be some metadata at start and most of the other
  79  * data can be spread out into fragments of #GstMp4Mux:fragment-duration.
  80  * If such fragmented layout is intended for streaming purposes, then
  81  * #GstMp4Mux:streamable allows foregoing to add index metadata (at the end of
  82  * file).
  83  *
  84  * <refsect2>
  85  * <title>Example pipelines</title>
  86  * |[
  87  * gst-launch-1.0 gst-launch-1.0 v4l2src num-buffers=50 ! queue ! x264enc ! mp4mux ! filesink location=video.mp4
  88  * ]|
  89  * Records a video stream captured from a v4l2 device, encodes it into H.264
  90  * and muxes it into an mp4 file.
  91  * </refsect2>
  92  */
  93
  94 /* ============================= 3gppmux ==================================== */
  95
  96 /**
  97  * SECTION:element-3gppmux
  98  * @short_description: Muxer for 3GPP (.3gp) files
  99  *
 100  * This element merges streams (audio and video) into 3GPP (.3gp) files.
 101  *
 102  * The following background intends to explain why various similar muxers
 103  * are present in this plugin.
 104  *
 105  * The <ulink url="http://www.apple.com/quicktime/resources/qtfileformat.pdf">
 106  * QuickTime file format specification</ulink> served as basis for the MP4 file
 107  * format specification (mp4mux), and as such the QuickTime file structure is
 108  * nearly identical to the so-called ISO Base Media file format defined in
 109  * ISO 14496-12 (except for some media specific parts).
 110  * In turn, the latter ISO Base Media format was further specialized as a
 111  * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux)
 112  * and in various 3GPP(2) specs (3gppmux).
 113  * The fragmented file features defined (only) in ISO Base Media are used by
 114  * ISMV files making up (a.o.) Smooth Streaming (ismlmux).
 115  *
 116  * A few properties (#Gst3GPPMux:movie-timescale, #Gst3GPPMux:trak-timescale)
 117  * allow adjusting some technical parameters, which might be useful in (rare)
 118  * cases to resolve compatibility issues in some situations.
 119  *
 120  * Some other properties influence the result more fundamentally.
 121  * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file,
 122  * somewhat contrary to this usually being called "the header". However, a
 123  * #Gst3GPPMux:faststart file will (with some effort) arrange this to be located
 124  * near start of the file, which then allows it e.g. to be played while
 125  * downloading. Alternatively, rather than having one chunk of metadata at start
 126  * (or end), there can be some metadata at start and most of the other data can
 127  * be spread out into fragments of #Gst3GPPMux:fragment-duration. If such
 128  * fragmented layout is intended for streaming purposes, then
 129  * #Gst3GPPMux:streamable allows foregoing to add index metadata (at the end of
 130  * file).
 131  *
 132  * <refsect2>
 133  * <title>Example pipelines</title>
 134  * |[
 135  * gst-launch-1.0 v4l2src num-buffers=50 ! queue ! ffenc_h263 ! 3gppmux ! filesink location=video.3gp
 136  * ]|
 137  * Records a video stream captured from a v4l2 device, encodes it into H.263
 138  * and muxes it into an 3gp file.
 139  * </refsect2>
 140  *
 141  * Documentation last reviewed on 2011-04-21
 142  */
 143
 144 /* ============================= mj2pmux ==================================== */
 145
 146 /**
 147  * SECTION:element-mj2mux
 148  * @short_description: Muxer for Motion JPEG-2000 (.mj2) files
 149  *
 150  * This element merges streams (audio and video) into MJ2 (.mj2) files.
 151  *
 152  * The following background intends to explain why various similar muxers
 153  * are present in this plugin.
 154  *
 155  * The <ulink url="http://www.apple.com/quicktime/resources/qtfileformat.pdf">
 156  * QuickTime file format specification</ulink> served as basis for the MP4 file
 157  * format specification (mp4mux), and as such the QuickTime file structure is
 158  * nearly identical to the so-called ISO Base Media file format defined in
 159  * ISO 14496-12 (except for some media specific parts).
 160  * In turn, the latter ISO Base Media format was further specialized as a
 161  * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux)
 162  * and in various 3GPP(2) specs (3gppmux).
 163  * The fragmented file features defined (only) in ISO Base Media are used by
 164  * ISMV files making up (a.o.) Smooth Streaming (ismlmux).
 165  *
 166  * A few properties (#GstMJ2Mux:movie-timescale, #GstMJ2Mux:trak-timescale)
 167  * allow adjusting some technical parameters, which might be useful in (rare)
 168  * cases to resolve compatibility issues in some situations.
 169  *
 170  * Some other properties influence the result more fundamentally.
 171  * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file,
 172  * somewhat contrary to this usually being called "the header". However, a
 173  * #GstMJ2Mux:faststart file will (with some effort) arrange this to be located
 174  * near start of the file, which then allows it e.g. to be played while
 175  * downloading. Alternatively, rather than having one chunk of metadata at start
 176  * (or end), there can be some metadata at start and most of the other data can
 177  * be spread out into fragments of #GstMJ2Mux:fragment-duration. If such
 178  * fragmented layout is intended for streaming purposes, then
 179  * #GstMJ2Mux:streamable allows foregoing to add index metadata (at the end of
 180  * file).
 181  *
 182  * <refsect2>
 183  * <title>Example pipelines</title>
 184  * |[
 185  * gst-launch-1.0 v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2
 186  * ]|
 187  * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000
 188  * and muxes it into an mj2 file.
 189  * </refsect2>
 190  *
 191  * Documentation last reviewed on 2011-04-21
 192  */
 193
 194 /* ============================= ismlmux ==================================== */
 195
 196 /**
 197  * SECTION:element-ismlmux
 198  * @short_description: Muxer for ISML smooth streaming (.isml) files
 199  *
 200  * This element merges streams (audio and video) into MJ2 (.mj2) files.
 201  *
 202  * The following background intends to explain why various similar muxers
 203  * are present in this plugin.
 204  *
 205  * The <ulink url="http://www.apple.com/quicktime/resources/qtfileformat.pdf">
 206  * QuickTime file format specification</ulink> served as basis for the MP4 file
 207  * format specification (mp4mux), and as such the QuickTime file structure is
 208  * nearly identical to the so-called ISO Base Media file format defined in
 209  * ISO 14496-12 (except for some media specific parts).
 210  * In turn, the latter ISO Base Media format was further specialized as a
 211  * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux)
 212  * and in various 3GPP(2) specs (3gppmux).
 213  * The fragmented file features defined (only) in ISO Base Media are used by
 214  * ISMV files making up (a.o.) Smooth Streaming (ismlmux).
 215  *
 216  * A few properties (#GstISMLMux:movie-timescale, #GstISMLMux:trak-timescale)
 217  * allow adjusting some technical parameters, which might be useful in (rare)
 218  * cases to resolve compatibility issues in some situations.
 219  *
 220  * Some other properties influence the result more fundamentally.
 221  * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file,
 222  * somewhat contrary to this usually being called "the header". However, a
 223  * #GstISMLMux:faststart file will (with some effort) arrange this to be located
 224  * near start of the file, which then allows it e.g. to be played while
 225  * downloading. Alternatively, rather than having one chunk of metadata at start
 226  * (or end), there can be some metadata at start and most of the other data can
 227  * be spread out into fragments of #GstISMLMux:fragment-duration. If such
 228  * fragmented layout is intended for streaming purposes, then
 229  * #GstISMLMux:streamable allows foregoing to add index metadata (at the end of
 230  * file).
 231  *
 232  * <refsect2>
 233  * <title>Example pipelines</title>
 234  * |[
 235  * gst-launch-1.0 v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2
 236  * ]|
 237  * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000
 238  * and muxes it into an mj2 file.
 239  * </refsect2>
 240  *
 241  * Documentation last reviewed on 2011-04-21
 242  */