From ec5c93f1690323a0a162f7e1401d4d16c83e4a3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= Date: Sat, 9 May 2015 22:33:26 +0100 Subject: [PATCH] docs: update element example pipelines - gst-launch -> gst-launch-1.0 - use autoaudiosink and audiovideosink more often - review pipeline examples and descriptions --- ext/alsa/gstalsasink.c | 6 ++-- ext/alsa/gstalsasrc.c | 2 +- ext/ogg/gstoggdemux.c | 4 +-- ext/pango/gstbasetextoverlay.c | 49 ---------------------------- ext/pango/gstclockoverlay.c | 6 ++-- ext/pango/gsttextoverlay.c | 13 ++------ ext/pango/gsttextrender.c | 2 +- ext/pango/gsttimeoverlay.c | 7 ++-- ext/theora/gsttheoradec.c | 6 ++-- ext/theora/gsttheoraenc.c | 2 +- ext/theora/gsttheoraparse.c | 4 +-- ext/vorbis/gstvorbisdec.c | 6 ++-- ext/vorbis/gstvorbisenc.c | 6 ++-- ext/vorbis/gstvorbisparse.c | 4 +-- ext/vorbis/gstvorbistag.c | 4 +-- gst/adder/gstadder.c | 6 +++- gst/audioconvert/gstaudioconvert.c | 11 ++++--- gst/audiorate/gstaudiorate.c | 10 ++++-- gst/audioresample/gstaudioresample.c | 5 +-- gst/audiotestsrc/gstaudiotestsrc.c | 4 +-- gst/gio/gstgiosink.c | 10 +++--- gst/gio/gstgiosrc.c | 8 ++--- gst/playback/gstplaybin2.c | 12 +++---- gst/playback/gstsubtitleoverlay.c | 4 +-- gst/tcp/gsttcpclientsink.c | 5 +-- gst/tcp/gsttcpclientsrc.c | 2 +- gst/tcp/gsttcpserversink.c | 4 +-- gst/tcp/gsttcpserversrc.c | 4 +-- gst/videoconvert/gstvideoconvert.c | 6 ++-- gst/videorate/gstvideorate.c | 11 ++++--- gst/videoscale/gstvideoscale.c | 13 ++++---- gst/videotestsrc/gstvideotestsrc.c | 4 +-- gst/volume/gstvolume.c | 2 +- sys/ximage/ximagesink.c | 6 ++-- sys/xvimage/xvimagesink.c | 24 +++++++------- 35 files changed, 118 insertions(+), 154 deletions(-) diff --git a/ext/alsa/gstalsasink.c b/ext/alsa/gstalsasink.c index 5c6a95899b..77fa0a1b97 100644 --- a/ext/alsa/gstalsasink.c +++ b/ext/alsa/gstalsasink.c @@ -24,13 +24,13 @@ * SECTION:element-alsasink * @see_also: alsasrc * - * This element renders raw audio samples using the ALSA api. + * This element renders raw audio samples using the ALSA audio API. * * * Example pipelines * |[ - * gst-launch -v filesrc location=sine.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! alsasink - * ]| Play an Ogg/Vorbis file. + * gst-launch-1.0 -v uridecodebin uri=file:///path/to/audio.ogg ! audioconvert ! audioresample ! autoaudiosink + * ]| Play an Ogg/Vorbis file and output audio via ALSA. * */ diff --git a/ext/alsa/gstalsasrc.c b/ext/alsa/gstalsasrc.c index 6d11ba4123..0233748b24 100644 --- a/ext/alsa/gstalsasrc.c +++ b/ext/alsa/gstalsasrc.c @@ -28,7 +28,7 @@ * * Example pipelines * |[ - * gst-launch -v alsasrc ! audioconvert ! vorbisenc ! oggmux ! filesink location=alsasrc.ogg + * gst-launch-1.0 -v alsasrc ! queue ! audioconvert ! vorbisenc ! oggmux ! filesink location=alsasrc.ogg * ]| Record from a sound card using ALSA and encode to Ogg/Vorbis. * */ diff --git a/ext/ogg/gstoggdemux.c b/ext/ogg/gstoggdemux.c index c6c652f71f..05ce495bf7 100644 --- a/ext/ogg/gstoggdemux.c +++ b/ext/ogg/gstoggdemux.c @@ -28,8 +28,8 @@ * * Example pipelines * |[ - * gst-launch -v filesrc location=test.ogg ! oggdemux ! vorbisdec ! audioconvert ! alsasink - * ]| Decodes the vorbis audio stored inside an ogg container. + * gst-launch-1.0 -v filesrc location=test.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! autoaudiosink + * ]| Decodes a vorbis audio stream stored inside an ogg container and plays it. * */ diff --git a/ext/pango/gstbasetextoverlay.c b/ext/pango/gstbasetextoverlay.c index b66768d3f9..a8d82d0c2b 100644 --- a/ext/pango/gstbasetextoverlay.c +++ b/ext/pango/gstbasetextoverlay.c @@ -22,55 +22,6 @@ * Boston, MA 02110-1301, USA. */ -/** - * SECTION:element-textoverlay - * @see_also: #GstTextRender, #GstClockOverlay, #GstTimeOverlay, #GstSubParse - * - * This plugin renders text on top of a video stream. This can be either - * static text or text from buffers received on the text sink pad, e.g. - * as produced by the subparse element. If the text sink pad is not linked, - * the text set via the "text" property will be rendered. If the text sink - * pad is linked, text will be rendered as it is received on that pad, - * honouring and matching the buffer timestamps of both input streams. - * - * The text can contain newline characters and text wrapping is enabled by - * default. - * - * - * Example launch lines - * |[ - * gst-launch -v videotestsrc ! textoverlay text="Room A" valign=top halign=left ! xvimagesink - * ]| Here is a simple pipeline that displays a static text in the top left - * corner of the video picture - * |[ - * gst-launch -v filesrc location=subtitles.srt ! subparse ! txt. videotestsrc ! timeoverlay ! textoverlay name=txt shaded-background=yes ! xvimagesink - * ]| Here is another pipeline that displays subtitles from an .srt subtitle - * file, centered at the bottom of the picture and with a rectangular shading - * around the text in the background: - * - * If you do not have such a subtitle file, create one looking like this - * in a text editor: - * |[ - * 1 - * 00:00:03,000 --> 00:00:05,000 - * Hello? (3-5s) - * - * 2 - * 00:00:08,000 --> 00:00:13,000 - * Yes, this is a subtitle. Don't - * you like it? (8-13s) - * - * 3 - * 00:00:18,826 --> 00:01:02,886 - * Uh? What are you talking about? - * I don't understand (18-62s) - * ]| - * - * - */ - -/* FIXME: alloc segment as part of instance struct */ - #ifdef HAVE_CONFIG_H #include #endif diff --git a/ext/pango/gstclockoverlay.c b/ext/pango/gstclockoverlay.c index 8fb1ecf62a..e5e177fc67 100644 --- a/ext/pango/gstclockoverlay.c +++ b/ext/pango/gstclockoverlay.c @@ -31,10 +31,10 @@ * * Example launch lines * |[ - * gst-launch -v videotestsrc ! clockoverlay ! xvimagesink - * ]| Display the current time in the top left corner of the video picture + * gst-launch-1.0 -v videotestsrc ! clockoverlay ! autovideosink + * ]| Display the current wall clock time in the top left corner of the video picture * |[ - * gst-launch -v videotestsrc ! clockoverlay halign=right valign=bottom text="Edge City" shaded-background=true ! videoconvert ! ximagesink + * gst-launch-1.0 -v videotestsrc ! clockoverlay halignment=right valignment=bottom text="Edge City" shaded-background=true font-desc="Sans, 36" ! videoconvert ! autovideosink * ]| Another pipeline that displays the current time with some leading * text in the bottom right corner of the video picture, with the background * of the text being shaded in order to make it more legible on top of a diff --git a/ext/pango/gsttextoverlay.c b/ext/pango/gsttextoverlay.c index 9e3f9dec51..d036579e57 100644 --- a/ext/pango/gsttextoverlay.c +++ b/ext/pango/gsttextoverlay.c @@ -40,11 +40,11 @@ * * Example launch lines * |[ - * gst-launch -v videotestsrc ! textoverlay text="Room A" valign=top halign=left ! xvimagesink + * gst-launch-1.0 -v gst-launch-1.0 videotestsrc ! textoverlay text="Room A" valignment=top halignment=left font-desc="Sans, 72" ! autovideosink * ]| Here is a simple pipeline that displays a static text in the top left * corner of the video picture * |[ - * gst-launch -v filesrc location=subtitles.srt ! subparse ! txt. videotestsrc ! timeoverlay ! textoverlay name=txt shaded-background=yes ! xvimagesink + * gst-launch-1.0 -v filesrc location=subtitles.srt ! subparse ! txt. videotestsrc ! timeoverlay ! textoverlay name=txt shaded-background=yes ! autovideosink * ]| Here is another pipeline that displays subtitles from an .srt subtitle * file, centered at the bottom of the picture and with a rectangular shading * around the text in the background: @@ -66,15 +66,6 @@ * Uh? What are you talking about? * I don't understand (18-62s) * ]| - * One can also feed arbitrary live text into the element: - * |[ - * gst-launch fdsrc fd=0 ! text/x-raw,format=utf8 ! txt. videotestsrc ! \ - * textoverlay name=txt shaded-background=yes font-desc="Serif 40" wait-text=false ! \ - * xvimagesink - * ]| This shows new text as entered on the terminal (stdin). This is not suited - * for subtitles as the test overlay is not timed. Subtitles should use - * timestamped formats. For the above use case one can also read the text from - * the application as set the #GstTextOverlay:text property. * * */ diff --git a/ext/pango/gsttextrender.c b/ext/pango/gsttextrender.c index be7df62294..603457ce30 100644 --- a/ext/pango/gsttextrender.c +++ b/ext/pango/gsttextrender.c @@ -34,7 +34,7 @@ * * Example launch lines * |[ - * gst-launch -v filesrc location=subtitles.srt ! subparse ! textrender ! xvimagesink + * gst-launch-1.0 -v filesrc location=subtitles.srt ! subparse ! textrender ! videoconvert ! autovideosink * ]| * */ diff --git a/ext/pango/gsttimeoverlay.c b/ext/pango/gsttimeoverlay.c index 535202fb97..0cedd6674d 100644 --- a/ext/pango/gsttimeoverlay.c +++ b/ext/pango/gsttimeoverlay.c @@ -30,11 +30,10 @@ * * * |[ - * gst-launch -v videotestsrc ! timeoverlay ! xvimagesink - * ]| Display the time stamps in the top left - * corner of the video picture. + * gst-launch-1.0 -v videotestsrc ! timeoverlay ! autovideosink + * ]| Display the time stamps in the top left corner of the video picture. * |[ - * gst-launch -v videotestsrc ! timeoverlay halign=right valign=bottom text="Stream time:" shaded-background=true ! xvimagesink + * gst-launch-1.0 -v videotestsrc ! timeoverlay halignment=right valignment=bottom text="Stream time:" shaded-background=true font-desc="Sans, 24" ! autovideosink * ]| Another pipeline that displays the time stamps with some leading * text in the bottom right corner of the video picture, with the background * of the text being shaded in order to make it more legible on top of a diff --git a/ext/theora/gsttheoradec.c b/ext/theora/gsttheoradec.c index 5adb057c04..fdb8a835bb 100644 --- a/ext/theora/gsttheoradec.c +++ b/ext/theora/gsttheoradec.c @@ -32,9 +32,9 @@ * * Example pipeline * |[ - * gst-launch -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! xvimagesink - * ]| This example pipeline will decode an ogg stream and decodes the theora video. Refer to - * the theoraenc example to create the ogg file. + * gst-launch-1.0 -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoconvert ! videoscale ! autovideosink + * ]| This example pipeline will decode an ogg stream and decodes the theora video in it. + * Refer to the theoraenc example to create the ogg file. * */ diff --git a/ext/theora/gsttheoraenc.c b/ext/theora/gsttheoraenc.c index 126c5e3d4c..f8af35310f 100644 --- a/ext/theora/gsttheoraenc.c +++ b/ext/theora/gsttheoraenc.c @@ -45,7 +45,7 @@ * * Example pipeline * |[ - * gst-launch -v videotestsrc num-buffers=1000 ! theoraenc ! oggmux ! filesink location=videotestsrc.ogg + * gst-launch-1.0 -v videotestsrc num-buffers=500 ! video/x-raw,width=1280,height=720 ! queue ! progressreport ! theoraenc ! oggmux ! filesink location=videotestsrc.ogg * ]| This example pipeline will encode a test video source to theora muxed in an * ogg container. Refer to the theoradec documentation to decode the create * stream. diff --git a/ext/theora/gsttheoraparse.c b/ext/theora/gsttheoraparse.c index f3558e80e6..5c58644c62 100644 --- a/ext/theora/gsttheoraparse.c +++ b/ext/theora/gsttheoraparse.c @@ -43,11 +43,11 @@ * * Example pipelines * |[ - * gst-launch -v filesrc location=video.ogg ! oggdemux ! theoraparse ! fakesink + * gst-launch-1.0 -v filesrc location=video.ogg ! oggdemux ! theoraparse ! fakesink * ]| This pipeline shows that the streamheader is set in the caps, and that each * buffer has the timestamp, duration, offset, and offset_end set. * |[ - * gst-launch filesrc location=video.ogg ! oggdemux ! theoraparse \ + * gst-launch-1.0 filesrc location=video.ogg ! oggdemux ! theoraparse \ * ! oggmux ! filesink location=video-remuxed.ogg * ]| This pipeline shows remuxing. video-remuxed.ogg might not be exactly the same * as video.ogg, but they should produce exactly the same decoded data. diff --git a/ext/vorbis/gstvorbisdec.c b/ext/vorbis/gstvorbisdec.c index 5741053afa..00dc784f09 100644 --- a/ext/vorbis/gstvorbisdec.c +++ b/ext/vorbis/gstvorbisdec.c @@ -24,12 +24,14 @@ * This element decodes a Vorbis stream to raw float audio. * Vorbis is a royalty-free * audio codec maintained by the Xiph.org - * Foundation. + * Foundation. As it outputs raw float audio you will often need to + * put an audioconvert element after it. + * * * * Example pipelines * |[ - * gst-launch -v filesrc location=sine.ogg ! oggdemux ! vorbisdec ! audioconvert ! alsasink + * gst-launch-1.0 -v filesrc location=sine.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! autoaudiosink * ]| Decode an Ogg/Vorbis. To create an Ogg/Vorbis file refer to the documentation of vorbisenc. * */ diff --git a/ext/vorbis/gstvorbisenc.c b/ext/vorbis/gstvorbisenc.c index 8dec47762a..7e9f504d95 100644 --- a/ext/vorbis/gstvorbisenc.c +++ b/ext/vorbis/gstvorbisenc.c @@ -29,12 +29,12 @@ * * Example pipelines * |[ - * gst-launch -v audiotestsrc wave=sine num-buffers=100 ! audioconvert ! vorbisenc ! oggmux ! filesink location=sine.ogg + * gst-launch-1.0 -v audiotestsrc wave=sine num-buffers=100 ! audioconvert ! vorbisenc ! oggmux ! filesink location=sine.ogg * ]| Encode a test sine signal to Ogg/Vorbis. Note that the resulting file * will be really small because a sine signal compresses very well. * |[ - * gst-launch -v alsasrc ! audioconvert ! vorbisenc ! oggmux ! filesink location=alsasrc.ogg - * ]| Record from a sound card using ALSA and encode to Ogg/Vorbis. + * gst-launch-1.0 -v autoaudiosrc ! audioconvert ! vorbisenc ! oggmux ! filesink location=alsasrc.ogg + * ]| Record from a sound card and encode to Ogg/Vorbis. * */ #ifdef HAVE_CONFIG_H diff --git a/ext/vorbis/gstvorbisparse.c b/ext/vorbis/gstvorbisparse.c index 6cf8510f52..f9f9198f74 100644 --- a/ext/vorbis/gstvorbisparse.c +++ b/ext/vorbis/gstvorbisparse.c @@ -36,11 +36,11 @@ * * Example pipelines * |[ - * gst-launch -v filesrc location=sine.ogg ! oggdemux ! vorbisparse ! fakesink + * gst-launch-1.0 -v filesrc location=sine.ogg ! oggdemux ! vorbisparse ! fakesink * ]| This pipeline shows that the streamheader is set in the caps, and that each * buffer has the timestamp, duration, offset, and offset_end set. * |[ - * gst-launch filesrc location=sine.ogg ! oggdemux ! vorbisparse \ + * gst-launch-1.0 filesrc location=sine.ogg ! oggdemux ! vorbisparse \ * ! oggmux ! filesink location=sine-remuxed.ogg * ]| This pipeline shows remuxing. sine-remuxed.ogg might not be exactly the same * as sine.ogg, but they should produce exactly the same decoded data. diff --git a/ext/vorbis/gstvorbistag.c b/ext/vorbis/gstvorbistag.c index fa7af7ac76..fded30cb62 100644 --- a/ext/vorbis/gstvorbistag.c +++ b/ext/vorbis/gstvorbistag.c @@ -37,8 +37,8 @@ * * Example pipelines * |[ - * gst-launch -v filesrc location=foo.ogg ! oggdemux ! vorbistag ! oggmux ! filesink location=bar.ogg - * ]| This element is not useful with gst-launch, because it does not support + * gst-launch-1.0 -v filesrc location=foo.ogg ! oggdemux ! vorbistag ! oggmux ! filesink location=bar.ogg + * ]| This element is not useful with gst-launch-1.0, because it does not support * setting the tags on a #GstTagSetter interface. Conceptually, the element * will usually be used in this order though. * diff --git a/gst/adder/gstadder.c b/gst/adder/gstadder.c index 094b25ee29..0f297d0e8d 100644 --- a/gst/adder/gstadder.c +++ b/gst/adder/gstadder.c @@ -29,10 +29,14 @@ * The adder currently mixes all data received on the sinkpads as soon as * possible without trying to synchronize the streams. * + * Check out the audiomixer element in gst-plugins-bad for a better-behaving + * audio mixing element: It will sync input streams correctly and also handle + * live inputs properly. + * * * Example launch line * |[ - * gst-launch audiotestsrc freq=100 ! adder name=mix ! audioconvert ! alsasink audiotestsrc freq=500 ! mix. + * gst-launch-1.0 audiotestsrc freq=100 ! adder name=mix ! audioconvert ! autoaudiosink audiotestsrc freq=500 ! mix. * ]| This pipeline produces two sine waves mixed together. * */ diff --git a/gst/audioconvert/gstaudioconvert.c b/gst/audioconvert/gstaudioconvert.c index a4195e08fb..09a6860446 100644 --- a/gst/audioconvert/gstaudioconvert.c +++ b/gst/audioconvert/gstaudioconvert.c @@ -26,18 +26,21 @@ * * Audioconvert converts raw audio buffers between various possible formats. * It supports integer to float conversion, width/depth conversion, - * signedness and endianness conversion and channel transformations. + * signedness and endianness conversion and channel transformations + * (ie. upmixing and downmixing), as well as dithering and noise-shaping. * * * Example launch line * |[ - * gst-launch -v -m audiotestsrc ! audioconvert ! audio/x-raw,format=S8,channels=2 ! level ! fakesink silent=TRUE + * gst-launch-1.0 -v -m audiotestsrc ! audioconvert ! audio/x-raw,format=S8,channels=2 ! level ! fakesink silent=TRUE * ]| This pipeline converts audio to 8-bit. The level element shows that * the output levels still match the one for a sine wave. * |[ - * gst-launch -v -m audiotestsrc ! audioconvert ! vorbisenc ! fakesink silent=TRUE + * gst-launch-1.0 -v -m uridecodebin uri=file:///path/to/audio.flac ! audioconvert ! vorbisenc ! oggmux ! filesink location=audio.ogg * ]| The vorbis encoder takes float audio data instead of the integer data - * generated by audiotestsrc. + * output by most other audio elements. This pipeline decodes a FLAC audio file + * (or any other audio file for which decoders are installed) and re-encodes + * it into an Ogg/Vorbis audio file. * */ diff --git a/gst/audiorate/gstaudiorate.c b/gst/audiorate/gstaudiorate.c index 15e76031a1..19661d8028 100644 --- a/gst/audiorate/gstaudiorate.c +++ b/gst/audiorate/gstaudiorate.c @@ -51,9 +51,15 @@ * * Example pipelines * |[ - * gst-launch -v alsasrc ! audiorate ! wavenc ! filesink location=alsa.wav - * ]| Capture audio from an ALSA device, and turn it into a perfect stream + * gst-launch-1.0 -v autoaudiosrc ! audiorate ! audioconvert ! wavenc ! filesink location=alsa.wav + * ]| Capture audio from the sound card and turn it into a perfect stream * for saving in a raw audio file. + * |[ + * gst-launch-1.0 -v uridecodebin uri=file:///path/to/audio.file ! audiorate ! audioconvert ! wavenc ! filesink location=alsa.wav + * ]| Decodes an audio file and transforms it into a perfect stream for saving + * in a raw audio WAV file. Without the audio rate, the timing might not be + * preserved correctly in the WAV file in case the decoded stream is jittery + * or there are samples missing. * */ diff --git a/gst/audioresample/gstaudioresample.c b/gst/audioresample/gstaudioresample.c index b4db739d79..a268ebc912 100644 --- a/gst/audioresample/gstaudioresample.c +++ b/gst/audioresample/gstaudioresample.c @@ -36,9 +36,10 @@ * * Example launch line * |[ - * gst-launch -v filesrc location=sine.ogg ! oggdemux ! vorbisdec ! audioconvert ! audioresample ! audio/x-raw, rate=8000 ! alsasink - * ]| Decode an Ogg/Vorbis downsample to 8Khz and play sound through alsa. + * gst-launch-1.0 -v uridecodebin uri=file:///path/to/audio.ogg ! audioconvert ! audioresample ! audio/x-raw, rate=8000 ! autoaudiosink + * ]| Decode an audio file and downsample it to 8Khz and play sound. * To create the Ogg/Vorbis file refer to the documentation of vorbisenc. + * This assumes there is an audio sink that will accept/handle 8kHz audio. * */ diff --git a/gst/audiotestsrc/gstaudiotestsrc.c b/gst/audiotestsrc/gstaudiotestsrc.c index c349559eb0..894fa16d5f 100644 --- a/gst/audiotestsrc/gstaudiotestsrc.c +++ b/gst/audiotestsrc/gstaudiotestsrc.c @@ -25,11 +25,11 @@ * * Example launch line * |[ - * gst-launch audiotestsrc ! audioconvert ! alsasink + * gst-launch-1.0 audiotestsrc ! audioconvert ! autoaudiosink * ]| This pipeline produces a sine with default frequency, 440 Hz, and the * default volume, 0.8 (relative to a maximum 1.0). * |[ - * gst-launch audiotestsrc wave=2 freq=200 ! audioconvert ! tee name=t ! queue ! alsasink t. ! queue ! libvisual_lv_scope ! videoconvert ! xvimagesink + * gst-launch-1.0 audiotestsrc wave=2 freq=200 ! tee name=t ! queue ! audioconvert ! autoaudiosink t. ! queue ! audioconvert ! libvisual_lv_scope ! videoconvert ! autovideosink * ]| In this example a saw wave is generated. The wave is shown using a * scope visualizer from libvisual, allowing you to visually verify that * the saw wave is correct. diff --git a/gst/gio/gstgiosink.c b/gst/gio/gstgiosink.c index 3f985b83e8..cf02090d2c 100644 --- a/gst/gio/gstgiosink.c +++ b/gst/gio/gstgiosink.c @@ -48,15 +48,15 @@ * * Example pipelines * |[ - * gst-launch -v filesrc location=input.xyz ! giosink location=file:///home/joe/out.xyz + * gst-launch-1.0 -v filesrc location=input.xyz ! giosink location=file:///home/joe/out.xyz * ]| The above pipeline will simply copy a local file. Instead of giosink, * we could just as well have used the filesink element here. * |[ - * gst-launch -v filesrc location=foo.mp3 ! mad ! flacenc ! giosink location=smb://othercomputer/foo.flac - * ]| The above pipeline will re-encode an mp3 file into FLAC format and store + * gst-launch-1.0 -v uridecodebin uri=file:///path/to/audio.file ! audioconvert ! flacenc ! giosink location=smb://othercomputer/foo.flac + * ]| The above pipeline will re-encode an audio file into FLAC format and store * it on a remote host using the Samba protocol. * |[ - * gst-launch -v audiotestsrc num-buffers=100 ! vorbisenc ! oggmux ! giosink location=file:///home/foo/bar.ogg + * gst-launch-1.0 -v audiotestsrc num-buffers=100 ! vorbisenc ! oggmux ! giosink location=file:///home/foo/bar.ogg * ]| The above pipeline will encode a 440Hz sine wave to Ogg Vorbis and stores * it in the home directory of user foo. * @@ -65,7 +65,7 @@ /* FIXME: We would like to mount the enclosing volume of an URL * if it isn't mounted yet but this is possible async-only. * Unfortunately this requires a running main loop from the - * default context and we can't guarantuee this! + * default context and we can't guarantee this! * * We would also like to do authentication while mounting. */ diff --git a/gst/gio/gstgiosrc.c b/gst/gio/gstgiosrc.c index d2149050af..9f9bae58c3 100644 --- a/gst/gio/gstgiosrc.c +++ b/gst/gio/gstgiosrc.c @@ -43,18 +43,18 @@ * * Example launch lines * |[ - * gst-launch -v giosrc location=file:///home/joe/foo.xyz ! fakesink + * gst-launch-1.0 -v giosrc location=file:///home/joe/foo.xyz ! fakesink * ]| The above pipeline will simply read a local file and do nothing with the * data read. Instead of giosrc, we could just as well have used the * filesrc element here. * |[ - * gst-launch -v giosrc location=smb://othercomputer/foo.xyz ! filesink location=/home/joe/foo.xyz + * gst-launch-1.0 -v giosrc location=smb://othercomputer/foo.xyz ! filesink location=/home/joe/foo.xyz * ]| The above pipeline will copy a file from a remote host to the local file * system using the Samba protocol. * |[ - * gst-launch -v giosrc location=http://music.foobar.com/demo.mp3 ! mad ! audioconvert ! audioresample ! alsasink + * gst-launch-1.0 -v giosrc location=smb://othercomputer/demo.mp3 ! decodebin ! audioconvert ! audioresample ! autoaudiosink * ]| The above pipeline will read and decode and play an mp3 file from a - * web server using the http protocol. + * SAMBA server. * */ diff --git a/gst/playback/gstplaybin2.c b/gst/playback/gstplaybin2.c index 757ec9b569..df75a8eb83 100644 --- a/gst/playback/gstplaybin2.c +++ b/gst/playback/gstplaybin2.c @@ -199,18 +199,18 @@ * * Examples * |[ - * gst-launch -v playbin uri=file:///path/to/somefile.avi + * gst-launch-1.0 -v playbin uri=file:///path/to/somefile.mp4 * ]| This will play back the given AVI video file, given that the video and * audio decoders required to decode the content are installed. Since no - * special audio sink or video sink is supplied (not possible via gst-launch), - * playbin will try to find a suitable audio and video sink automatically - * using the autoaudiosink and autovideosink elements. + * special audio sink or video sink is supplied (via playbin's audio-sink or + * video-sink properties) playbin will try to find a suitable audio and + * video sink automatically using the autoaudiosink and autovideosink elements. * |[ - * gst-launch -v playbin uri=cdda://4 + * gst-launch-1.0 -v playbin uri=cdda://4 * ]| This will play back track 4 on an audio CD in your disc drive (assuming * the drive is detected automatically by the plugin). * |[ - * gst-launch -v playbin uri=dvd:// + * gst-launch-1.0 -v playbin uri=dvd:// * ]| This will play back the DVD in your disc drive (assuming * the drive is detected automatically by the plugin). * diff --git a/gst/playback/gstsubtitleoverlay.c b/gst/playback/gstsubtitleoverlay.c index 16ac1664f6..6c56ed8377 100644 --- a/gst/playback/gstsubtitleoverlay.c +++ b/gst/playback/gstsubtitleoverlay.c @@ -29,8 +29,8 @@ * * Examples * |[ - * gst-launch -v filesrc location=test.mkv ! matroskademux name=demux ! "video/x-h264" ! queue2 ! decodebin ! subtitleoverlay name=overlay ! videoconvert ! autovideosink demux. ! "subpicture/x-dvd" ! queue2 ! overlay. - * ]| This will play back the given Matroska file with h264 video and subpicture subtitles. + * gst-launch-1.0 -v filesrc location=test.mkv ! matroskademux name=demux ! video/x-h264 ! queue ! decodebin ! subtitleoverlay name=overlay ! videoconvert ! autovideosink demux. ! subpicture/x-dvd ! queue ! overlay. + * ]| This will play back the given Matroska file with h264 video and dvd subpicture style subtitles. * */ diff --git a/gst/tcp/gsttcpclientsink.c b/gst/tcp/gsttcpclientsink.c index d2465a6726..65a9d0128f 100644 --- a/gst/tcp/gsttcpclientsink.c +++ b/gst/tcp/gsttcpclientsink.c @@ -30,8 +30,9 @@ * # server: * nc -l -p 3000 * # client: - * gst-launch fdsink fd=1 ! tcpclientsink port=3000 - * ]| everything you type in the client is shown on the server + * gst-launch-1.0 fdsink fd=1 ! tcpclientsink port=3000 + * ]| everything you type in the client is shown on the server (fd=1 means + * standard input which is the command line input file descriptor) * */ diff --git a/gst/tcp/gsttcpclientsrc.c b/gst/tcp/gsttcpclientsrc.c index 633665bfbf..2207563ebe 100644 --- a/gst/tcp/gsttcpclientsrc.c +++ b/gst/tcp/gsttcpclientsrc.c @@ -30,7 +30,7 @@ * # server: * nc -l -p 3000 * # client: - * gst-launch tcpclientsrc port=3000 ! fdsink fd=2 + * gst-launch-1.0 tcpclientsrc port=3000 ! fdsink fd=2 * ]| everything you type in the server is shown on the client * */ diff --git a/gst/tcp/gsttcpserversink.c b/gst/tcp/gsttcpserversink.c index b805ebc40f..cb43d2d7bb 100644 --- a/gst/tcp/gsttcpserversink.c +++ b/gst/tcp/gsttcpserversink.c @@ -26,9 +26,9 @@ * Example launch line * |[ * # server: - * gst-launch fdsrc fd=1 ! tcpserversink port=3000 + * gst-launch-1.0 fdsrc fd=1 ! tcpserversink port=3000 * # client: - * gst-launch tcpclientsrc port=3000 ! fdsink fd=2 + * gst-launch-1.0 tcpclientsrc port=3000 ! fdsink fd=2 * ]| * */ diff --git a/gst/tcp/gsttcpserversrc.c b/gst/tcp/gsttcpserversrc.c index d2a09e9597..9cd6ad6f41 100644 --- a/gst/tcp/gsttcpserversrc.c +++ b/gst/tcp/gsttcpserversrc.c @@ -28,9 +28,9 @@ * Example launch line * |[ * # server: - * gst-launch tcpserversrc port=3000 ! fdsink fd=2 + * gst-launch-1.0 tcpserversrc port=3000 ! fdsink fd=2 * # client: - * gst-launch fdsrc fd=1 ! tcpclientsink port=3000 + * gst-launch-1.0 fdsrc fd=1 ! tcpclientsink port=3000 * ]| * */ diff --git a/gst/videoconvert/gstvideoconvert.c b/gst/videoconvert/gstvideoconvert.c index f28a735c55..ec71f8c2ec 100644 --- a/gst/videoconvert/gstvideoconvert.c +++ b/gst/videoconvert/gstvideoconvert.c @@ -28,8 +28,10 @@ * * Example launch line * |[ - * gst-launch -v videotestsrc ! video/x-raw,format=\(string\)YUY2 ! videoconvert ! ximagesink - * ]| + * gst-launch-1.0 -v videotestsrc ! video/x-raw,format=YUY2 ! videoconvert ! autovideosink + * ]| This will output a test video (generated in YUY2 format) in a video + * window. If the video sink selected does not support YUY2 videoconvert will + * automatically convert the video to a format understood by the video sink. * */ diff --git a/gst/videorate/gstvideorate.c b/gst/videorate/gstvideorate.c index 9842c67e70..aa3cf1460a 100644 --- a/gst/videorate/gstvideorate.c +++ b/gst/videorate/gstvideorate.c @@ -55,13 +55,16 @@ * * Example pipelines * |[ - * gst-launch -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videorate ! video/x-raw,framerate=15/1 ! xvimagesink - * ]| Decode an Ogg/Theora file and adjust the framerate to 15 fps before playing. - * To create the test Ogg/Theora file refer to the documentation of theoraenc. + * gst-launch-1.0 -v uridecodebin uri=file:///path/to/video.ogg ! videoconvert ! videoscale ! videorate ! video/x-raw,framerate=15/1 ! autovideosink + * ]| Decode a video file and adjust the framerate to 15 fps before playing. + * To create a test Ogg/Theora file refer to the documentation of theoraenc. * |[ - * gst-launch -v v4l2src ! videorate ! video/x-raw,framerate=25/2 ! theoraenc ! oggmux ! filesink location=recording.ogg + * gst-launch-1.0 -v v4l2src ! videorate ! video/x-raw,framerate=25/2 ! theoraenc ! oggmux ! filesink location=recording.ogg * ]| Capture video from a V4L device, and adjust the stream to 12.5 fps before * encoding to Ogg/Theora. + * |[ + * gst-launch-1.0 -v uridecodebin uri=file:///path/to/video.ogg ! videoconvert ! videoscale ! videorate ! video/x-raw,framerate=1/5 ! jpegenc ! multifilesink location=snapshot-%05d.jpg + * ]| Decode a video file and save a snapshot every 5 seconds as consecutively numbered jpeg file. * */ diff --git a/gst/videoscale/gstvideoscale.c b/gst/videoscale/gstvideoscale.c index b694ea37e5..a88bee299a 100644 --- a/gst/videoscale/gstvideoscale.c +++ b/gst/videoscale/gstvideoscale.c @@ -34,15 +34,14 @@ * * Example pipelines * |[ - * gst-launch -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoconvert ! videoscale ! ximagesink - * ]| Decode an Ogg/Theora and display the video using ximagesink. Since - * ximagesink cannot perform scaling, the video scaling will be performed by - * videoscale when you resize the video window. + * gst-launch-1.0 -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoconvert ! videoscale ! autovideosink + * ]| Decode an Ogg/Theora and display the video. If the video sink chosen + * cannot perform scaling, the video scaling will be performed by videoscale + * when you resize the video window. * To create the test Ogg/Theora file refer to the documentation of theoraenc. * |[ - * gst-launch -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoscale ! video/x-raw, width=50 ! xvimagesink - * ]| Decode an Ogg/Theora and display the video using xvimagesink with a width - * of 50. + * gst-launch-1.0 -v filesrc location=videotestsrc.ogg ! oggdemux ! theoradec ! videoconvert ! videoscale ! video/x-raw,width=100 ! autovideosink + * ]| Decode an Ogg/Theora and display the video with a width of 100. * */ diff --git a/gst/videotestsrc/gstvideotestsrc.c b/gst/videotestsrc/gstvideotestsrc.c index 60b320012f..96a2a926ae 100644 --- a/gst/videotestsrc/gstvideotestsrc.c +++ b/gst/videotestsrc/gstvideotestsrc.c @@ -28,8 +28,8 @@ * * Example launch line * |[ - * gst-launch -v videotestsrc pattern=snow ! ximagesink - * ]| Shows random noise in an X window. + * gst-launch-1.0 -v videotestsrc pattern=snow ! video/x-raw,width=1280,height=720 ! autovideosink + * ]| Shows random noise in a video window. * */ diff --git a/gst/volume/gstvolume.c b/gst/volume/gstvolume.c index 7612095f45..0b6482a11b 100644 --- a/gst/volume/gstvolume.c +++ b/gst/volume/gstvolume.c @@ -30,7 +30,7 @@ * * Example launch line * |[ - * gst-launch -v -m audiotestsrc ! volume volume=0.5 ! level ! fakesink silent=TRUE + * gst-launch-1.0 -v -m audiotestsrc ! volume volume=0.5 ! level ! fakesink silent=TRUE * ]| This pipeline shows that the level of audiotestsrc has been halved * (peak values are around -6 dB and RMS around -9 dB) compared to * the same pipeline without the volume element. diff --git a/sys/ximage/ximagesink.c b/sys/ximage/ximagesink.c index 2a1f76b3af..7814ac84ad 100644 --- a/sys/ximage/ximagesink.c +++ b/sys/ximage/ximagesink.c @@ -74,14 +74,14 @@ * * Examples * |[ - * gst-launch -v videotestsrc ! queue ! ximagesink + * gst-launch-1.0 -v videotestsrc ! queue ! ximagesink * ]| A pipeline to test reverse negotiation. When the test video signal appears * you can resize the window and see that scaled buffers of the desired size are * going to arrive with a short delay. This illustrates how buffers of desired * size are allocated along the way. If you take away the queue, scaling will * happen almost immediately. * |[ - * gst-launch -v videotestsrc ! navigationtest ! videoconvert ! ximagesink + * gst-launch-1.0 -v videotestsrc ! navigationtest ! videoconvert ! ximagesink * ]| A pipeline to test navigation events. * While moving the mouse pointer over the test signal you will see a black box * following the mouse pointer. If you press the mouse button somewhere on the @@ -89,7 +89,7 @@ * the button and a red one where you released it. (The navigationtest element * is part of gst-plugins-good.) * |[ - * gst-launch -v videotestsrc ! video/x-raw, pixel-aspect-ratio=(fraction)4/3 ! videoscale ! ximagesink + * gst-launch-1.0 -v videotestsrc ! video/x-raw, pixel-aspect-ratio=(fraction)4/3 ! videoscale ! ximagesink * ]| This is faking a 4/3 pixel aspect ratio caps on video frames produced by * videotestsrc, in most cases the pixel aspect ratio of the display will be * 1/1. This means that videoscale will have to do the scaling to convert diff --git a/sys/xvimage/xvimagesink.c b/sys/xvimage/xvimagesink.c index e8752d32bf..ad2d77325a 100644 --- a/sys/xvimage/xvimagesink.c +++ b/sys/xvimage/xvimagesink.c @@ -73,17 +73,20 @@ * * Examples * |[ - * gst-launch -v videotestsrc ! xvimagesink + * gst-launch-1.0 -v videotestsrc ! xvimagesink * ]| A pipeline to test hardware scaling. * When the test video signal appears you can resize the window and see that - * video frames are scaled through hardware (no extra CPU cost). + * video frames are scaled through hardware (no extra CPU cost). By default + * the image will never be distorted when scaled, instead black borders will + * be added if needed. * |[ - * gst-launch -v videotestsrc ! xvimagesink force-aspect-ratio=true - * ]| Same pipeline with #GstXvImageSink:force-aspect-ratio property set to true - * You can observe the borders drawn around the scaled image respecting aspect - * ratio. + * gst-launch-1.0 -v videotestsrc ! xvimagesink force-aspect-ratio=false + * ]| Same pipeline with #GstXvImageSink:force-aspect-ratio property set to + * false. You can observe that no borders are drawn around the scaled image + * now and it will be distorted to fill the entire frame instead of respecting + * the aspect ratio. * |[ - * gst-launch -v videotestsrc ! navigationtest ! xvimagesink + * gst-launch-1.0 -v videotestsrc ! navigationtest ! xvimagesink * ]| A pipeline to test navigation events. * While moving the mouse pointer over the test signal you will see a black box * following the mouse pointer. If you press the mouse button somewhere on the @@ -95,15 +98,14 @@ * position. This also handles borders correctly, limiting coordinates to the * image area * |[ - * gst-launch -v videotestsrc ! video/x-raw, pixel-aspect-ratio=(fraction)4/3 ! xvimagesink + * gst-launch-1.0 -v videotestsrc ! video/x-raw, pixel-aspect-ratio=4/3 ! xvimagesink * ]| This is faking a 4/3 pixel aspect ratio caps on video frames produced by * videotestsrc, in most cases the pixel aspect ratio of the display will be * 1/1. This means that XvImageSink will have to do the scaling to convert * incoming frames to a size that will match the display pixel aspect ratio - * (from 320x240 to 320x180 in this case). Note that you might have to escape - * some characters for your shell like '\(fraction\)'. + * (from 320x240 to 320x180 in this case). * |[ - * gst-launch -v videotestsrc ! xvimagesink hue=100 saturation=-100 brightness=100 + * gst-launch-1.0 -v videotestsrc ! xvimagesink hue=100 saturation=-100 brightness=100 * ]| Demonstrates how to use the colorbalance interface. * */