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>
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.
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.
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.
23 * Unless otherwise indicated, Source Code is licensed under MIT license.
24 * See further explanation attached in License Statement (distributed in the file
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:
34 * The above copyright notice and this permission notice shall be included in all
35 * copies or substantial portions of the Software.
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
46 /* ============================= mp4mux ==================================== */
49 * SECTION:element-mp4mux
50 * @short_description: Muxer for ISO MPEG-4 (.mp4) files
52 * This element merges streams (audio and video) into ISO MPEG-4 (.mp4) files.
54 * The following background intends to explain why various similar muxers
55 * are present in this plugin.
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).
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.
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).
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>.
99 * <title>Example pipelines</title>
101 * gst-launch gst-launch v4l2src num-buffers=50 ! queue ! x264enc ! mp4mux ! filesink location=video.mp4
103 * Records a video stream captured from a v4l2 device, encodes it into H.264
104 * and muxes it into an mp4 file.
107 * Documentation last reviewed on 2011-04-21
110 /* ============================= 3gppmux ==================================== */
113 * SECTION:element-3gppmux
114 * @short_description: Muxer for 3GPP (.3gp) files
116 * This element merges streams (audio and video) into 3GPP (.3gp) files.
118 * The following background intends to explain why various similar muxers
119 * are present in this plugin.
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).
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.
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).
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>.
163 * <title>Example pipelines</title>
165 * gst-launch v4l2src num-buffers=50 ! queue ! ffenc_h263 ! gppmux ! filesink location=video.3gp
167 * Records a video stream captured from a v4l2 device, encodes it into H.263
168 * and muxes it into an 3gp file.
171 * Documentation last reviewed on 2011-04-21
174 /* ============================= mj2pmux ==================================== */
177 * SECTION:element-mj2mux
178 * @short_description: Muxer for Motion JPEG-2000 (.mj2) files
180 * This element merges streams (audio and video) into MJ2 (.mj2) files.
182 * The following background intends to explain why various similar muxers
183 * are present in this plugin.
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).
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.
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).
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>.
227 * <title>Example pipelines</title>
229 * gst-launch v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2
231 * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000
232 * and muxes it into an mj2 file.
235 * Documentation last reviewed on 2011-04-21
238 /* ============================= ismlmux ==================================== */
241 * SECTION:element-ismlmux
242 * @short_description: Muxer for ISML smooth streaming (.isml) files
244 * This element merges streams (audio and video) into MJ2 (.mj2) files.
246 * The following background intends to explain why various similar muxers
247 * are present in this plugin.
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).
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.
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).
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>.
291 * <title>Example pipelines</title>
293 * gst-launch v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2
295 * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000
296 * and muxes it into an mj2 file.
299 * Documentation last reviewed on 2011-04-21