From 3346a53374135b8a58a50f2ff18e0ecaaf2272d4 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Tim-Philipp=20M=C3=BCller?= Date: Thu, 21 Apr 2011 23:30:26 +0100 Subject: [PATCH] docs: add various qtmux variants to documentation --- docs/plugins/Makefile.am | 1 + docs/plugins/gst-plugins-good-plugins-docs.sgml | 5 + docs/plugins/gst-plugins-good-plugins-sections.txt | 38 +++ gst/quicktime/Makefile.am | 4 + gst/quicktime/gstqtmoovrecover.c | 8 +- gst/quicktime/gstqtmux-doc.c | 300 +++++++++++++++++++++ gst/quicktime/gstqtmux-doc.h | 52 ++++ 7 files changed, 405 insertions(+), 3 deletions(-) create mode 100644 gst/quicktime/gstqtmux-doc.c create mode 100644 gst/quicktime/gstqtmux-doc.h diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am index b511a43..410123e 100644 --- a/docs/plugins/Makefile.am +++ b/docs/plugins/Makefile.am @@ -192,6 +192,7 @@ EXTRA_HFILES = \ $(top_srcdir)/gst/multipart/multipartmux.h \ $(top_srcdir)/gst/quicktime/qtdemux.h \ $(top_srcdir)/gst/quicktime/gstqtmux.h \ + $(top_srcdir)/gst/quicktime/gstqtmux-doc.h \ $(top_srcdir)/gst/replaygain/gstrganalysis.h \ $(top_srcdir)/gst/replaygain/gstrglimiter.h \ $(top_srcdir)/gst/replaygain/gstrgvolume.h \ diff --git a/docs/plugins/gst-plugins-good-plugins-docs.sgml b/docs/plugins/gst-plugins-good-plugins-docs.sgml index fba35fd..17584d7 100644 --- a/docs/plugins/gst-plugins-good-plugins-docs.sgml +++ b/docs/plugins/gst-plugins-good-plugins-docs.sgml @@ -18,6 +18,7 @@ gst-plugins-good Elements + @@ -100,6 +101,7 @@ + @@ -107,8 +109,10 @@ + + @@ -135,6 +139,7 @@ + diff --git a/docs/plugins/gst-plugins-good-plugins-sections.txt b/docs/plugins/gst-plugins-good-plugins-sections.txt index d2b8f75..f3b4cd3 100644 --- a/docs/plugins/gst-plugins-good-plugins-sections.txt +++ b/docs/plugins/gst-plugins-good-plugins-sections.txt @@ -1,4 +1,11 @@
+element-3gppmux +3gppmux +Gst3GPPMux + +
+ +
element-aacparse aacparse GstAacParse @@ -1197,6 +1204,13 @@ gst_interleave_get_type
+element-ismlmux +ismlmux +GstISMLMux + +
+ +
element-jackaudiosrc jackaudiosrc GstJackAudioSrc @@ -1301,6 +1315,13 @@ gst_matroska_demux_plugin_init
+element-mj2mux +mj2mux +GstMJ2Mux + +
+ +
element-monoscope monoscope GstMonoscope @@ -1329,6 +1350,13 @@ gst_mpeg_audio_parse_get_type
+element-mp4mux +mp4mux +GstMP4Mux + +
+ +
element-mulawdec mulawdec GstMuLawDec @@ -1688,6 +1716,16 @@ gst_qtdemux_get_type
+element-qtmoovrecover +qtmoovrecover +GstQTMoovRecover +GstQTMoovRecoverClass +gst_qt_moov_recover_get_type +gst_qt_moov_recover_register + +
+ +
element-qtmux qtmux GstQTMux diff --git a/gst/quicktime/Makefile.am b/gst/quicktime/Makefile.am index 00cc167..0e1b0f3 100644 --- a/gst/quicktime/Makefile.am +++ b/gst/quicktime/Makefile.am @@ -36,6 +36,10 @@ noinst_HEADERS = \ ftypcc.h \ gstqtmuxmap.h +EXTRA_DIST = \ + gstqtmux-doc.c \ + gstqtmux-doc.h + Android.mk: Makefile.am $(BUILT_SOURCES) androgenizer \ -:PROJECT libgstqtdemux -:SHARED libgstqtdemux \ diff --git a/gst/quicktime/gstqtmoovrecover.c b/gst/quicktime/gstqtmoovrecover.c index 68011dc..8079972 100644 --- a/gst/quicktime/gstqtmoovrecover.c +++ b/gst/quicktime/gstqtmoovrecover.c @@ -42,21 +42,23 @@ /** - * SECTION:gstqtmoovrecover + * SECTION:element-qtmoovrecover * @short_description: Utility element for recovering unfinished quicktime files * * * - * This element recovers quicktime files created with qtmux using the moov recovery feature. + * This element recovers quicktime files created with qtmux using the moov + * recovery feature. * * Example pipelines * * * TODO * + * * * - * Last reviewed on 2010-02-01 + * Documentation last reviewed on 2011-04-21 */ #ifdef HAVE_CONFIG_H diff --git a/gst/quicktime/gstqtmux-doc.c b/gst/quicktime/gstqtmux-doc.c new file mode 100644 index 0000000..986fffc --- /dev/null +++ b/gst/quicktime/gstqtmux-doc.c @@ -0,0 +1,300 @@ +/* Quicktime muxer documentation + * Copyright (C) 2008-2010 Thiago Santos + * Copyright (C) 2008 Mark Nauwelaerts + * Copyright (C) 2010 Nokia Corporation. All rights reserved. + * Contact: Stefan Kost + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Library General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Library General Public License for more details. + * + * You should have received a copy of the GNU Library General Public + * License along with this library; if not, write to the + * Free Software Foundation, Inc., 59 Temple Place - Suite 330, + * Boston, MA 02111-1307, USA. + */ +/* + * Unless otherwise indicated, Source Code is licensed under MIT license. + * See further explanation attached in License Statement (distributed in the file + * LICENSE). + * + * Permission is hereby granted, free of charge, to any person obtaining a copy of + * this software and associated documentation files (the "Software"), to deal in + * the Software without restriction, including without limitation the rights to + * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies + * of the Software, and to permit persons to whom the Software is furnished to do + * so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +/* ============================= mp4mux ==================================== */ + +/** + * SECTION:element-mp4mux + * @short_description: Muxer for ISO MPEG-4 (.mp4) files + * + * This element merges streams (audio and video) into ISO MPEG-4 (.mp4) files. + * + * The following background intends to explain why various similar muxers + * are present in this plugin. + * + * The + * QuickTime file format specification served as basis for the MP4 file + * format specification (mp4mux), and as such the QuickTime file structure is + * nearly identical to the so-called ISO Base Media file format defined in + * ISO 14496-12 (except for some media specific parts). + * In turn, the latter ISO Base Media format was further specialized as a + * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) + * and in various 3GPP(2) specs (gppmux). + * The fragmented file features defined (only) in ISO Base Media are used by + * ISMV files making up (a.o.) Smooth Streaming (ismlmux). + * + * A few properties (movie-timescale, + * trak-timescale) allow adjusting + * some technical parameters, which might be useful in (rare) cases to resolve + * compatibility issues in some situations. + * + * Some other properties influence the result more fundamentally. + * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, + * somewhat contrary to this usually being called "the header". + * However, a faststart file will + * (with some effort) arrange this to be located near start of the file, + * which then allows it e.g. to be played while downloading. + * Alternatively, rather than having one chunk of metadata at start (or end), + * there can be some metadata at start and most of the other data can be spread + * out into fragments of fragment-duration. + * If such fragmented layout is intended for streaming purposes, then + * streamable allows foregoing to add + * index metadata (at the end of file). + * + * dts-method allows selecting a + * method for managing input timestamps (stay tuned for 0.11 to have this + * automagically settled). The default delta/duration method should handle nice + * (aka perfect streams) just fine, but may experience problems otherwise + * (e.g. input stream with re-ordered B-frames and/or with frame dropping). + * The re-ordering approach re-assigns incoming timestamps in ascending order + * to incoming buffers and offers an alternative in such cases. In cases where + * that might fail, the remaining method can be tried, which is exact and + * according to specs, but might experience playback on not so spec-wise players. + * Note that this latter approach also requires one to enable + * presentation-timestamp. + * + * + * Example pipelines + * |[ + * gst-launch gst-launch v4l2src num-buffers=50 ! queue ! x264enc ! mp4mux ! filesink location=video.mp4 + * ]| + * Records a video stream captured from a v4l2 device, encodes it into H.264 + * and muxes it into an mp4 file. + * + * + * Documentation last reviewed on 2011-04-21 + */ + +/* ============================= 3gppmux ==================================== */ + +/** + * SECTION:element-3gppmux + * @short_description: Muxer for 3GPP (.3gp) files + * + * This element merges streams (audio and video) into 3GPP (.3gp) files. + * + * The following background intends to explain why various similar muxers + * are present in this plugin. + * + * The + * QuickTime file format specification served as basis for the MP4 file + * format specification (mp4mux), and as such the QuickTime file structure is + * nearly identical to the so-called ISO Base Media file format defined in + * ISO 14496-12 (except for some media specific parts). + * In turn, the latter ISO Base Media format was further specialized as a + * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) + * and in various 3GPP(2) specs (gppmux). + * The fragmented file features defined (only) in ISO Base Media are used by + * ISMV files making up (a.o.) Smooth Streaming (ismlmux). + * + * A few properties (movie-timescale, + * trak-timescale) allow adjusting + * some technical parameters, which might be useful in (rare) cases to resolve + * compatibility issues in some situations. + * + * Some other properties influence the result more fundamentally. + * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, + * somewhat contrary to this usually being called "the header". + * However, a faststart file will + * (with some effort) arrange this to be located near start of the file, + * which then allows it e.g. to be played while downloading. + * Alternatively, rather than having one chunk of metadata at start (or end), + * there can be some metadata at start and most of the other data can be spread + * out into fragments of fragment-duration. + * If such fragmented layout is intended for streaming purposes, then + * streamable allows foregoing to add + * index metadata (at the end of file). + * + * dts-method allows selecting a + * method for managing input timestamps (stay tuned for 0.11 to have this + * automagically settled). The default delta/duration method should handle nice + * (aka perfect streams) just fine, but may experience problems otherwise + * (e.g. input stream with re-ordered B-frames and/or with frame dropping). + * The re-ordering approach re-assigns incoming timestamps in ascending order + * to incoming buffers and offers an alternative in such cases. In cases where + * that might fail, the remaining method can be tried, which is exact and + * according to specs, but might experience playback on not so spec-wise players. + * Note that this latter approach also requires one to enable + * presentation-timestamp. + * + * + * Example pipelines + * |[ + * gst-launch v4l2src num-buffers=50 ! queue ! ffenc_h263 ! gppmux ! filesink location=video.3gp + * ]| + * Records a video stream captured from a v4l2 device, encodes it into H.263 + * and muxes it into an 3gp file. + * + * + * Documentation last reviewed on 2011-04-21 + */ + +/* ============================= mj2pmux ==================================== */ + +/** + * SECTION:element-mj2mux + * @short_description: Muxer for Motion JPEG-2000 (.mj2) files + * + * This element merges streams (audio and video) into MJ2 (.mj2) files. + * + * The following background intends to explain why various similar muxers + * are present in this plugin. + * + * The + * QuickTime file format specification served as basis for the MP4 file + * format specification (mp4mux), and as such the QuickTime file structure is + * nearly identical to the so-called ISO Base Media file format defined in + * ISO 14496-12 (except for some media specific parts). + * In turn, the latter ISO Base Media format was further specialized as a + * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) + * and in various 3GPP(2) specs (gppmux). + * The fragmented file features defined (only) in ISO Base Media are used by + * ISMV files making up (a.o.) Smooth Streaming (ismlmux). + * + * A few properties (movie-timescale, + * trak-timescale) allow adjusting + * some technical parameters, which might be useful in (rare) cases to resolve + * compatibility issues in some situations. + * + * Some other properties influence the result more fundamentally. + * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, + * somewhat contrary to this usually being called "the header". + * However, a faststart file will + * (with some effort) arrange this to be located near start of the file, + * which then allows it e.g. to be played while downloading. + * Alternatively, rather than having one chunk of metadata at start (or end), + * there can be some metadata at start and most of the other data can be spread + * out into fragments of fragment-duration. + * If such fragmented layout is intended for streaming purposes, then + * streamable allows foregoing to add + * index metadata (at the end of file). + * + * dts-method allows selecting a + * method for managing input timestamps (stay tuned for 0.11 to have this + * automagically settled). The default delta/duration method should handle nice + * (aka perfect streams) just fine, but may experience problems otherwise + * (e.g. input stream with re-ordered B-frames and/or with frame dropping). + * The re-ordering approach re-assigns incoming timestamps in ascending order + * to incoming buffers and offers an alternative in such cases. In cases where + * that might fail, the remaining method can be tried, which is exact and + * according to specs, but might experience playback on not so spec-wise players. + * Note that this latter approach also requires one to enable + * presentation-timestamp. + * + * + * Example pipelines + * |[ + * gst-launch v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2 + * ]| + * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000 + * and muxes it into an mj2 file. + * + * + * Documentation last reviewed on 2011-04-21 + */ + +/* ============================= ismlmux ==================================== */ + +/** + * SECTION:element-ismlmux + * @short_description: Muxer for ISML smooth streaming (.isml) files + * + * This element merges streams (audio and video) into MJ2 (.mj2) files. + * + * The following background intends to explain why various similar muxers + * are present in this plugin. + * + * The + * QuickTime file format specification served as basis for the MP4 file + * format specification (mp4mux), and as such the QuickTime file structure is + * nearly identical to the so-called ISO Base Media file format defined in + * ISO 14496-12 (except for some media specific parts). + * In turn, the latter ISO Base Media format was further specialized as a + * Motion JPEG-2000 file format in ISO 15444-3 (mj2mux) + * and in various 3GPP(2) specs (gppmux). + * The fragmented file features defined (only) in ISO Base Media are used by + * ISMV files making up (a.o.) Smooth Streaming (ismlmux). + * + * A few properties (movie-timescale, + * trak-timescale) allow adjusting + * some technical parameters, which might be useful in (rare) cases to resolve + * compatibility issues in some situations. + * + * Some other properties influence the result more fundamentally. + * A typical mov/mp4 file's metadata (aka moov) is located at the end of the file, + * somewhat contrary to this usually being called "the header". + * However, a faststart file will + * (with some effort) arrange this to be located near start of the file, + * which then allows it e.g. to be played while downloading. + * Alternatively, rather than having one chunk of metadata at start (or end), + * there can be some metadata at start and most of the other data can be spread + * out into fragments of fragment-duration. + * If such fragmented layout is intended for streaming purposes, then + * streamable allows foregoing to add + * index metadata (at the end of file). + * + * dts-method allows selecting a + * method for managing input timestamps (stay tuned for 0.11 to have this + * automagically settled). The default delta/duration method should handle nice + * (aka perfect streams) just fine, but may experience problems otherwise + * (e.g. input stream with re-ordered B-frames and/or with frame dropping). + * The re-ordering approach re-assigns incoming timestamps in ascending order + * to incoming buffers and offers an alternative in such cases. In cases where + * that might fail, the remaining method can be tried, which is exact and + * according to specs, but might experience playback on not so spec-wise players. + * Note that this latter approach also requires one to enable + * presentation-timestamp. + * + * + * Example pipelines + * |[ + * gst-launch v4l2src num-buffers=50 ! queue ! jp2kenc ! mj2mux ! filesink location=video.mj2 + * ]| + * Records a video stream captured from a v4l2 device, encodes it into JPEG-2000 + * and muxes it into an mj2 file. + * + * + * Documentation last reviewed on 2011-04-21 + */ diff --git a/gst/quicktime/gstqtmux-doc.h b/gst/quicktime/gstqtmux-doc.h new file mode 100644 index 0000000..48b5d8c --- /dev/null +++ b/gst/quicktime/gstqtmux-doc.h @@ -0,0 +1,52 @@ +/* Quicktime muxer documentation + * Copyright (C) 2008-2010 Thiago Santos + * Copyright (C) 2008 Mark Nauwelaerts + * Copyright (C) 2010 Nokia Corporation. All rights reserved. + * Contact: Stefan Kost + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Library General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Library General Public License for more details. + * + * You should have received a copy of the GNU Library General Public + * License along with this library; if not, write to the + * Free Software Foundation, Inc., 59 Temple Place - Suite 330, + * Boston, MA 02111-1307, USA. + */ +/* + * Unless otherwise indicated, Source Code is licensed under MIT license. + * See further explanation attached in License Statement (distributed in the file + * LICENSE). + * + * Permission is hereby granted, free of charge, to any person obtaining a copy of + * this software and associated documentation files (the "Software"), to deal in + * the Software without restriction, including without limitation the rights to + * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies + * of the Software, and to permit persons to whom the Software is furnished to do + * so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +#error "This header is for gtk-doc only and not supposed to be included" + +typedef struct _GstMP4Mux GstMP4Mux; +typedef struct _Gst3GPPMux GstMP4Mux; +typedef struct _GstISMLMux GstMP4Mux; +typedef struct _GstMJ2Mux GstMJ2Mux; + -- 2.7.4