Merge branch 'master' into 0.11
[platform/upstream/gstreamer.git] / tools / README
1 gst-launch
2 ================
3
4 This is a tool that will construct pipelines based on a command-line
5 syntax.  The syntax is rather complex to enable all the features I want it
6 to have, but should be easy to use for most people.  Multi-pathed and
7 feedback pipelines are the most complex.
8
9 A simple commandline looks like:
10
11  gst-launch filesrc location=music.mp3 ! mad ! osssink
12
13 This plays an mp3 music file music.mp3 using libmad, and:
14
15  gst-launch filesrc location=music.mp3 ! mp3parse ! mpg123 ! osssink
16
17 Plays and mp3 music file using mpg123
18
19 You can also stream files over http:
20
21  gst-launch httpsrc location=http://domain.com/music.mp3 ! mad ! osssink
22
23 And using gnome-vfs you can do the same with:
24
25  gst-launch gnomevfssrc location=music.mp3 ! mad ! osssink
26  gst-launch gnomevfssrc location=http://domain.com/music.mp3 ! mad ! osssink
27
28 And too play the same song with gnome-vfs via smb:
29
30  gst-launch gnomevfssrc location=smb://computer/music.mp3 ! mad ! osssink
31
32 Here we convert a Mp3 file into an Ogg Vorbis file:
33
34  gst-launch filesrc location=music.mp3 ! mad ! vorbisenc ! filesink location=music.ogg
35
36 And then we can play that file with:
37
38  gst-launch filesrc location=music.ogg ! oggdemux ! vorbisdec ! audioconvert ! osssink
39
40 Some other useful pipelines are..
41 Plays wav files (currently there are no wav encoders):
42
43  gst-launch filesrc location=music.wav ! wavparse ! osssink
44
45 Converts wav files into mp3 and ogg files:
46
47  gst-launch filesrc location=music.wav ! wavparse ! vorbisenc ! filesink location=music.ogg
48  gst-launch filesrc location=music.wav ! wavparse ! mpegaudio ! filesink location=music.mp3
49
50 You can also use lame for mp3 encoding if you have it installed, it does a 
51 much better job than mpegaudio.
52
53 Rips all songs from cd and saves them into a mp3 file:
54
55  gst-launch cdparanoia ! mpegaudio ! filesink location=cd.mp3
56
57 You can toy around with gst-inspect to discover the settings for 
58 cdparanoia to rip individual tracks
59
60 Record sound from your sound input and encode it into an ogg file:
61
62  gst-launch osssrc ! vorbisenc ! filesink location=input.ogg
63
64 gst-launch not only handles audio but video as well:
65 For mpeg1 files (video and audio streams respectively):
66
67  gst-launch filesrc location=video.mpg ! mpegdemux video_00! { queue ! mpeg2dec ! sdlvideosink }
68  gst-launch filesrc location=video.mpg ! mpegdemux audio_00! { queue ! mad ! osssink }
69
70 for mpeg1 with both audio and video (for glib2):
71
72  gst-launch filesrc location=video.mpg ! mpegdemux name=demux video_00! { queue ! mpeg2dec ! sdlvideosink } demux.audio_00! { queue ! mad ! osssink }
73
74 for mpeg1 with both audio and video (for gtk1.2, the shim doesn't handle the 'name' property yet):
75
76  gst-launch filesrc location=video.mpg ! mpegdemux video_00! { queue ! mpeg2dec ! sdlvideosink } mpegdemux0.audio_00! { queue ! mad ! osssink }
77
78 For mpeg2 files (video and audio streams respectively):
79  
80  gst-launch filesrc location=video.mpeg ! mpegdemux video_00! { queue ! mpeg2dec ! sdlvideosink }
81  gst-launch filesrc location=video.mpeg ! mpegdemux private_stream_1.0! { queue ! a52dec ! osssink }
82
83 for mpeg2 with both audio and video (glib2):
84
85  gst-launch filesrc location=video.mpg ! mpegdemux name=demux video_00! { queue ! mpeg2dec ! sdlvideosink } demux.private_stream_1.0! { queue ! a52dec ! osssink }
86
87 Note: The types of audio streams in the mpeg files can vary!
88
89 For an avi file (DivX, mjpeg,...)
90
91  gst-launch filesrc location=video.avi ! avidecoder video_00! { queue ! sdlvideosink } avidecoder0.audio_00! { queue ! osssink }
92
93
94
95 gst-complete
96 ==================
97
98 This is a simple utility which provides custom bash completion when
99 typing gst-launch commands. 
100
101 Simply run "gst-compprep" as root to build the registry of completions,
102 and then put, in your .bashrc,
103 "complete -C gst-complete gst-launch"
104 (ensuring that gst-complete is on your path).
105
106 You can then enjoy context sensitive tab-completion of gst-launch
107 commands.
108
109
110
111 gst-inspect
112 =================
113
114 Allows you to check the properties of plugins and elements.
115
116  ./gst-inspect 
117  
118 will show all the plugins available and the elements they contain.
119
120  ./gst-inspect <pluginname/elementname>
121
122 shows more info about the plugin/element.
123
124
125
126 gst-xmlinspect
127 =================
128
129 Dump properties of plugins and elements in an xml format. You can 
130 transform the xml to something else with an appropriate stylesheet.
131
132  ./gst-xmlinspect <elementname> | xsltproc xml2text.xsl -
133
134