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 /* ============================= qtmux ==================================== */ 47 48 /** 49 * SECTION:element-qtmux 50 * @title: qtmux 51 * @short_description: Muxer for quicktime(.mov) files 52 * 53 * This element merges streams (audio and video) into QuickTime(.mov) files. 54 * 55 * The following background intends to explain why various similar muxers 56 * are present in this plugin. 57 * 58 * The [QuickTime file format specification](http://www.apple.com/quicktime/resources/qtfileformat.pdf) 59 * served as basis for the MP4 file format specification (mp4mux), and as such 60 * the QuickTime file structure is nearly identical to the so-called ISO Base 61 * Media file format defined in ISO 14496-12 (except for some media specific 62 * parts). 63 * 64 * In turn, the latter ISO Base Media format was further specialized as a 65 * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) 66 * and in various 3GPP(2) specs (gppmux). 67 * The fragmented file features defined (only) in ISO Base Media are used by 68 * ISMV files making up (a.o.) Smooth Streaming (ismlmux). 69 * 70 * A few properties (#GstBaseQTMux:movie-timescale, #GstBaseQTMux:trak-timescale, 71 * #GstQTMuxPad:trak-timescale) allow adjusting some technical parameters, 72 * which might be useful in (rare) cases to resolve compatibility issues in 73 * some situations. 74 * 75 * Some other properties influence the result more fundamentally. 76 * A typical mov/mp4 file's metadata (aka moov) is located at the end of the 77 * file, somewhat contrary to this usually being called "the header". 78 * However, a #GstBaseQTMux:faststart file will (with some effort) arrange this to 79 * be located near start of the file, which then allows it e.g. to be played 80 * while downloading. Alternatively, rather than having one chunk of metadata at 81 * start (or end), there can be some metadata at start and most of the other 82 * data can be spread out into fragments of #GstBaseQTMux:fragment-duration. 83 * If such fragmented layout is intended for streaming purposes, then 84 * #GstQTMux:streamable allows foregoing to add index metadata (at the end of 85 * file). 86 * 87 * When the maximum duration to be recorded can be known in advance, #GstQTMux 88 * also supports a 'Robust Muxing' mode. In robust muxing mode, space for the 89 * headers are reserved at the start of muxing, and rewritten at a configurable 90 * interval, so that the output file is always playable, even if the recording 91 * is interrupted uncleanly by a crash. Robust muxing mode requires a seekable 92 * output, such as filesink, because it needs to rewrite the start of the file. 93 * 94 * To enable robust muxing mode, set the #GstBaseQTMux:reserved-moov-update-period 95 * and #GstBaseQTMux:reserved-max-duration property. Also present is the 96 * #GstBaseQTMux:reserved-bytes-per-sec property, which can be increased if 97 * for some reason the default is not large enough and the initial reserved 98 * space for headers is too small. Applications can monitor the 99 * #GstBaseQTMux:reserved-duration-remaining property to see how close to full 100 * the reserved space is becoming. 101 * 102 * Applications that wish to be able to use/edit a file while it is being 103 * written to by live content, can use the "Robust Prefill Muxing" mode. That 104 * mode is a variant of the "Robust Muxing" mode in that it will pre-allocate a 105 * completely valid header from the start for all tracks (i.e. it appears as 106 * though the file is "reserved-max-duration" long with all samples 107 * present). This mode can be enabled by setting the 108 * #GstBaseQTMux:reserved-moov-update-period and #GstBaseQTMux:reserved-prefill 109 * properties. Note that this mode is only possible with input streams that have 110 * a fixed sample size (such as raw audio and Prores Video) and that don't 111 * have reordered samples. 112 * 113 * ## Example pipelines 114 * |[ 115 * gst-launch-1.0 v4l2src num-buffers=500 ! video/x-raw,width=320,height=240 ! videoconvert ! qtmux ! filesink location=video.mov 116 * ]| 117 * Records a video stream captured from a v4l2 device and muxes it into a qt file. 118 * 119 */ 120 121 /* ============================= mp4mux ==================================== */ 122 123 /** 124 * SECTION:element-mp4mux 125 * @title: mp4mux 126 * @short_description: Muxer for ISO MPEG-4 (.mp4) files 127 * 128 * This element merges streams (audio and video) into ISO MPEG-4 (.mp4) files. 129 * 130 * The following background intends to explain why various similar muxers 131 * are present in this plugin. 132 * 133 * The [QuickTime file format specification](http://www.apple.com/quicktime/resources/qtfileformat.pdf) 134 * served as basis for the MP4 file format specification (mp4mux), and as such 135 * the QuickTime file structure is nearly identical to the so-called ISO Base 136 * Media file format defined in ISO 14496-12 (except for some media specific 137 * parts). 138 * 139 * In turn, the latter ISO Base Media format was further specialized as a 140 * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) 141 * and in various 3GPP(2) specs (3gppmux). 142 * The fragmented file features defined (only) in ISO Base Media are used by 143 * ISMV files making up (a.o.) Smooth Streaming (ismlmux). 144 * 145 * A few properties (#GstBaseQTMux:movie-timescale, #GstBaseQTMux:trak-timescale) 146 * allow adjusting some technical parameters, which might be useful in (rare) 147 * cases to resolve compatibility issues in some situations. 148 * 149 * Some other properties influence the result more fundamentally. 150 * A typical mov/mp4 file's metadata (aka moov) is located at the end of the 151 * file, somewhat contrary to this usually being called "the header". 152 * However, a #GstBaseQTMux:faststart file will (with some effort) arrange this to 153 * be located near start of the file, which then allows it e.g. to be played 154 * while downloading. Alternatively, rather than having one chunk of metadata at 155 * start (or end), there can be some metadata at start and most of the other 156 * data can be spread out into fragments of #GstBaseQTMux:fragment-duration. 157 * If such fragmented layout is intended for streaming purposes, then 158 * #GstMP4Mux:streamable allows foregoing to add index metadata (at the end of 159 * file). 160 * 161 * ## Example pipelines 162 * |[ 163 * gst-launch-1.0 gst-launch-1.0 v4l2src num-buffers=50 ! queue ! x264enc ! mp4mux ! filesink location=video.mp4 164 * ]| 165 * Records a video stream captured from a v4l2 device, encodes it into H.264 166 * and muxes it into an mp4 file. 167 * 168 */ 169 170 /* ============================= 3gppmux ==================================== */ 171 172 /** 173 * SECTION:element-3gppmux 174 * @title: 3gppmux 175 * @short_description: Muxer for 3GPP (.3gp) files 176 * 177 * This element merges streams (audio and video) into 3GPP (.3gp) files. 178 * 179 * The following background intends to explain why various similar muxers 180 * are present in this plugin. 181 * 182 * The [QuickTime file format specification](http://www.apple.com/quicktime/resources/qtfileformat.pdf) 183 * served as basis for the MP4 file format specification (mp4mux), and as such 184 * the QuickTime file structure is nearly identical to the so-called ISO Base 185 * Media file format defined in ISO 14496-12 (except for some media specific 186 * parts). 187 * 188 * In turn, the latter ISO Base Media format was further specialized as a 189 * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) 190 * and in various 3GPP(2) specs (3gppmux). 191 * The fragmented file features defined (only) in ISO Base Media are used by 192 * ISMV files making up (a.o.) Smooth Streaming (ismlmux). 193 * 194 * A few properties (#GstBaseQTMux:movie-timescale, #GstBaseQTMux:trak-timescale) 195 * allow adjusting some technical parameters, which might be useful in (rare) 196 * cases to resolve compatibility issues in some situations. 197 * 198 * Some other properties influence the result more fundamentally. 199 * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, 200 * somewhat contrary to this usually being called "the header". However, a 201 * #GstBaseQTMux:faststart file will (with some effort) arrange this to be located 202 * near start of the file, which then allows it e.g. to be played while 203 * downloading. Alternatively, rather than having one chunk of metadata at start 204 * (or end), there can be some metadata at start and most of the other data can 205 * be spread out into fragments of #GstBaseQTMux:fragment-duration. If such 206 * fragmented layout is intended for streaming purposes, then 207 * #Gst3GPPMux:streamable allows foregoing to add index metadata (at the end of 208 * file). 209 * 210 * ## Example pipelines 211 * |[ 212 * gst-launch-1.0 v4l2src num-buffers=50 ! queue ! ffenc_h263 ! 3gppmux ! filesink location=video.3gp 213 * ]| 214 * Records a video stream captured from a v4l2 device, encodes it into H.263 215 * and muxes it into an 3gp file. 216 * 217 * Documentation last reviewed on 2011-04-21 218 */ 219 220 /* ============================= mj2pmux ==================================== */ 221 222 /** 223 * SECTION:element-mj2mux 224 * @title: mj2mux 225 * @short_description: Muxer for Motion JPEG-2000 (.mj2) files 226 * 227 * This element merges streams (audio and video) into MJ2 (.mj2) files. 228 * 229 * The following background intends to explain why various similar muxers 230 * are present in this plugin. 231 * 232 * The [QuickTime file format specification](http://www.apple.com/quicktime/resources/qtfileformat.pdf) 233 * served as basis for the MP4 file format specification (mp4mux), and as such 234 * the QuickTime file structure is nearly identical to the so-called ISO Base 235 * Media file format defined in ISO 14496-12 (except for some media specific 236 * parts). 237 * 238 * In turn, the latter ISO Base Media format was further specialized as a 239 * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) 240 * and in various 3GPP(2) specs (3gppmux). 241 * The fragmented file features defined (only) in ISO Base Media are used by 242 * ISMV files making up (a.o.) Smooth Streaming (ismlmux). 243 * 244 * A few properties (#GstBaseQTMux:movie-timescale, #GstBaseQTMux:trak-timescale) 245 * allow adjusting some technical parameters, which might be useful in (rare) 246 * cases to resolve compatibility issues in some situations. 247 * 248 * Some other properties influence the result more fundamentally. 249 * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, 250 * somewhat contrary to this usually being called "the header". However, a 251 * #GstBaseQTMux:faststart file will (with some effort) arrange this to be located 252 * near start of the file, which then allows it e.g. to be played while 253 * downloading. Alternatively, rather than having one chunk of metadata at start 254 * (or end), there can be some metadata at start and most of the other data can 255 * be spread out into fragments of #GstBaseQTMux:fragment-duration. If such 256 * fragmented layout is intended for streaming purposes, then 257 * #GstMJ2Mux:streamable allows foregoing to add index metadata (at the end of 258 * file). 259 * 260 * ## Example pipelines 261 * |[ 262 * gst-launch-1.0 v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2 263 * ]| 264 * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000 265 * and muxes it into an mj2 file. 266 * 267 * Documentation last reviewed on 2011-04-21 268 */ 269 270 /* ============================= ismlmux ==================================== */ 271 272 /** 273 * SECTION:element-ismlmux 274 * @title: ismlmux 275 * @short_description: Muxer for ISML smooth streaming (.isml) files 276 * 277 * This element merges streams (audio and video) into MJ2 (.mj2) files. 278 * 279 * The following background intends to explain why various similar muxers 280 * are present in this plugin. 281 * 282 * The [QuickTime file format specification](http://www.apple.com/quicktime/resources/qtfileformat.pdf) 283 * served as basis for the MP4 file format specification (mp4mux), and as such 284 * the QuickTime file structure is nearly identical to the so-called ISO Base 285 * Media file format defined in ISO 14496-12 (except for some media specific 286 * parts). 287 * 288 * In turn, the latter ISO Base Media format was further specialized as a 289 * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) 290 * and in various 3GPP(2) specs (3gppmux). 291 * The fragmented file features defined (only) in ISO Base Media are used by 292 * ISMV files making up (a.o.) Smooth Streaming (ismlmux). 293 * 294 * A few properties (#GstBaseQTMux:movie-timescale, #GstBaseQTMux:trak-timescale) 295 * allow adjusting some technical parameters, which might be useful in (rare) 296 * cases to resolve compatibility issues in some situations. 297 * 298 * Some other properties influence the result more fundamentally. 299 * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, 300 * somewhat contrary to this usually being called "the header". However, a 301 * #GstBaseQTMux:faststart file will (with some effort) arrange this to be located 302 * near start of the file, which then allows it e.g. to be played while 303 * downloading. Alternatively, rather than having one chunk of metadata at start 304 * (or end), there can be some metadata at start and most of the other data can 305 * be spread out into fragments of #GstBaseQTMux:fragment-duration. If such 306 * fragmented layout is intended for streaming purposes, then 307 * #GstISMLMux:streamable allows foregoing to add index metadata (at the end of 308 * file). 309 * 310 * ## Example pipelines 311 * |[ 312 * gst-launch-1.0 v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2 313 * ]| 314 * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000 315 * and muxes it into an mj2 file. 316 * 317 * Documentation last reviewed on 2011-04-21 318 */ 319