docs: Fix typos in documentation
[platform/upstream/gstreamer.git] / README.md
1 # GStreamer
2
3 This is GStreamer, a framework for streaming media.
4
5 ## Where to start
6
7 We have a website at
8
9   https://gstreamer.freedesktop.org
10
11 Our documentation, including tutorials, API reference and FAQ can be found at
12
13   https://gstreamer.freedesktop.org/documentation/
14
15 You can subscribe to our mailing lists:
16
17   https://lists.freedesktop.org/mailman/listinfo/gstreamer-announce
18
19   https://lists.freedesktop.org/mailman/listinfo/gstreamer-devel
20
21 We track bugs, feature requests and merge requests (patches) in GitLab at
22
23   https://gitlab.freedesktop.org/gstreamer/
24
25 You can join us on IRC - #gstreamer on irc.oftc.net
26
27 This repository contains all official modules supported by the GStreamer
28 community which can be found in the `subprojects/` directory.
29
30 ## Getting started
31
32 ### Install git and python 3.5+
33
34 If you're on Linux, you probably already have these. On macOS, you can use the
35 [official Python installer](https://www.python.org/downloads/mac-osx/).
36
37 You can find [instructions for Windows below](#windows-prerequisites-setup).
38
39 ### Install meson and ninja
40
41 Meson 0.59 or newer is required.
42
43 On Linux and macOS you can get meson through your package manager or using:
44
45   $ pip3 install --user meson
46
47 This will install meson into `~/.local/bin` which may or may not be included
48 automatically in your PATH by default.
49
50 You should get `ninja` using your package manager or download the [official
51 release](https://github.com/ninja-build/ninja/releases) and put the `ninja`
52 binary in your PATH.
53
54 You can find [instructions for Windows below](#windows-prerequisites-setup).
55
56 ### Build GStreamer and its modules
57
58 You can get all GStreamer built running:
59
60 ```
61 meson builddir
62 ninja -C builddir
63 ```
64
65 This will automatically create the `build` directory and build everything
66 inside it.
67
68 NOTE: On Windows, you *must* run this from [inside the Visual Studio command
69 prompt](#running-meson-on-windows) of the appropriate architecture and version.
70
71 ### External dependencies
72
73 All mandatory dependencies of GStreamer are included as [meson subprojects](https://mesonbuild.com/Subprojects.html):
74 libintl, zlib, libffi, glib. Some optional dependencies are also included as
75 subprojects, such as ffmpeg, x264, json-glib, graphene, openh264, orc, etc.
76
77 Mandatory dependencies will be automatically built if meson cannot find them on
78 your system using pkg-config. The same is true for optional dependencies that
79 are included as subprojects. You can find a full list by looking at the
80 `subprojects` directory.
81
82 Plugins that need optional dependencies that aren't included can only be built
83 if they are provided by the system. Instructions on how to build some common
84 ones such as Qt5/QML are listed below. If you do not know how to provide an
85 optional dependency needed by a plugin, you should use [Cerbero](https://gitlab.freedesktop.org/gstreamer/cerbero/#description)
86 which handles this for you automatically.
87
88 Plugins will be automatically enabled if possible, but you can ensure that
89 a particular plugin (especially if it has external dependencies) is built by
90 enabling the gstreamer repository that ships it and the plugin inside it. For
91 example, to enable the Qt5 plugin in the gst-plugins-good repository, you need
92 to run meson as follows:
93
94 ```
95 meson -Dgood=enabled -Dgst-plugins-good:qt5=enabled builddir
96 ```
97
98 This will cause Meson to error out if the plugin could not be enabled. You can
99 also flip the default and disable all plugins except those explicitly enabled
100 like so:
101
102 ```
103 meson -Dauto_features=disabled -Dgstreamer:tools=enabled -Dbad=enabled -Dgst-plugins-bad:openh264=enabled
104 ```
105
106 This will disable all optional features and then enable the `openh264` plugin
107 and the tools that ship with the core gstreamer repository: `gst-inspect-1.0`,
108 `gst-launch-1.0`, etc. As usual, you can change these values on a builddir that
109 has already been setup with `meson configure -Doption=value`.
110
111 ### Building the Qt5 QML plugin
112
113 If `qmake` is not in `PATH` and pkgconfig files are not available, you can
114 point the `QMAKE` env var to the Qt5 installation of your choosing before
115 running `meson` as shown above.
116
117 The plugin will be automatically enabled if possible, but you can ensure that
118 it is built by passing `-Dgood=enabled -Dgst-plugins-good:qt5=enabled` to `meson`.
119
120 ### Building the Intel MSDK plugin
121
122 On Linux, you need to have development files for `libmfx` installed. On
123 Windows, if you have the [Intel Media SDK](https://software.intel.com/en-us/media-sdk),
124 it will set the `INTELMEDIASDKROOT` environment variable, which will be used by
125 the build files to find `libmfx`.
126
127 The plugin will be automatically enabled if possible, but you can ensure it by
128 passing `-Dbad=enabled -Dgst-plugins-bad:msdk=enabled` to `meson`.
129
130 ### Building plugins with (A)GPL-licensed dependencies
131
132 Some plugins have GPL- or AGPL-licensed dependencies and will only be built
133 if you have explicitly opted in to allow (A)GPL-licensed dependencies by
134 passing `-Dgpl=enabled` to Meson.
135
136 List of plugins with (A)GPL-licensed dependencies (non-exhaustive) in gst-plugins-bad:
137  - dts (DTS audio decoder plugin)
138  - faad (Free AAC audio decoder plugin)
139  - iqa (Image quality assessment plugin based on dssim-c)
140  - mpeg2enc (MPEG-2 video encoder plugin)
141  - mplex (audio/video multiplexer plugin)
142  - ofa (Open Fingerprint Architecture library plugin)
143  - resindvd (Resin DVD playback plugin)
144  - x265 (HEVC/H.265 video encoder plugin)
145
146 List of plugins with (A)GPL-licensed dependencies (non-exhaustive) in gst-plugins-ugly:
147  - a52dec (Dolby Digital (AC-3) audio decoder plugin)
148  - cdio (CD audio source plugin based on libcdio)
149  - dvdread (DVD video source plugin based on libdvdread)
150  - mpeg2dec (MPEG-2 video decoder plugin based on libmpeg2)
151  - sidplay (Commodore 64 audio decoder plugin based on libsidplay)
152  - x264 (H.264 video encoder plugin based on libx264)
153
154 ### Static build
155
156 Since *1.18.0* when doing a static build using `--default-library=static`, a
157 shared library `gstreamer-full-1.0` will be produced and includes all enabled
158 GStreamer plugins and libraries. A list of libraries that needs to be exposed in
159 `gstreamer-full-1.0` ABI can be set using `gst-full-libraries` option. glib-2.0,
160 gobject-2.0 and gstreamer-1.0 are always included.
161
162 ```
163 meson --default-library=static -Dgst-full-libraries=app,video builddir
164 ```
165
166 GStreamer *1.18* requires applications using gstreamer-full-1.0 to initialize
167 static plugins by calling `gst_init_static_plugins()` after `gst_init()`. That
168 function is defined in `gst/gstinitstaticplugins.h` header file.
169
170 Since *1.20.0* `gst_init_static_plugins()` is called automatically by
171 `gst_init()` and applications must not call it manually any more. The header
172 file has been removed from public API.
173
174 One can use the `gst-full-version-script` option to pass a
175 [version script](https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html)
176 to the linker. This can be used to control the exact symbols that are exported by
177 the gstreamer-full library, allowing the linker to garbage collect unused code
178 and so reduce the total library size. A default script `gstreamer-full-default.map`
179 declares only glib/gstreamer symbols as public.
180
181 One can use the `gst-full-plugins` option to pass a list of plugins to be registered
182 in the gstreamer-full library. The default value is '*' which means that all the plugins selected
183 during the build process will be registered statically. An empty value will prevent any plugins to
184 be registered.
185
186 One can select a specific set of features with `gst-full-elements`, `gst-full-typefind-functions`, `gst-full-device-providers` or `gst-full-dynamic-types` to select specific feature from a plugin.
187 When a feature has been listed in one of those options, the other features from its plugin will no longer be automatically included, even if the plugin is listed in `gst-full-plugins`.
188
189 The user must insure that all selected plugins and features (element, typefind, etc.) have been
190 enabled during the build configuration.
191
192 To register features, the syntax is the following:
193 plugins are separated by ';' and features from a plugin starts after ':' and are ',' separated.
194
195 As an example:
196  * `-Dgst-full-plugins=coreelements;playback;typefindfunctions;alsa;pbtypes`: enable only `coreelements`, `playback`, `typefindfunctions`, `alsa`, `pbtypes` plugins.
197  * `-Dgst-full-elements=coreelements:filesrc,fakesink,identity;alsa:alsasrc`: enable only `filesrc`, `identity` and `fakesink` elements from `coreelements` and `alsasrc` element from `alsa` plugin.
198  * `-Dgst-full-typefind-functions=typefindfunctions:wav,flv`: enable only typefind func `wav` and `flv` from `typefindfunctions`
199  * `-Dgst-full-device-providers=alsa:alsadeviceprovider`: enable `alsadeviceprovider` from `alsa`.
200  * `-Dgst-full-dynamic-types=pbtypes:video_multiview_flagset`:  enable `video_multiview_flagset` from `pbtypes
201
202 All features from the `playback` plugin will be enabled and the other plugins will be restricted to the specific features requested.
203
204 All the selected features will be registered into a dedicated `NULL` plugin name.
205
206 This will cause the features/plugins that are not registered to not be included in the final gstreamer-full library.
207
208 This is an experimental feature, backward incompatible changes could still be
209 made in the future.
210
211 # Development environment
212
213 ## Development environment target
214
215 GStreamer also contains a special `devenv` target that lets you enter an
216 development environment where you will be able to work on GStreamer
217 easily. You can get into that environment running:
218
219 ```
220 ninja -C builddir devenv
221 ```
222
223 If your operating system handles symlinks, built modules source code will be
224 available at the root for example GStreamer core will be in
225 `gstreamer/`. Otherwise they will be present in `subprojects/`. You can simply
226 hack in there and to rebuild you just need to rerun `ninja -C builddir`.
227
228 NOTE: In the development environment, a fully usable prefix is also configured
229 in `gstreamer/prefix` where you can install any extra dependency/project.
230
231 An external script can be run in development environment with:
232
233 ```
234 ./gst-env.py external_script.sh
235 ```
236
237 For more extensive documentation about the development environment go to [the
238 documentation](https://gstreamer.freedesktop.org/documentation/installing/building-from-source-using-meson.html).
239
240 ## Custom subprojects
241
242 We also added a meson option, `custom_subprojects`, that allows the user
243 to provide a comma-separated list of subprojects that should be built
244 alongside the default ones.
245
246 To use it:
247
248 ```
249 cd subprojects
250 git clone my_subproject
251 cd ../build
252 rm -rf * && meson .. -Dcustom_subprojects=my_subproject
253 ninja
254 ```
255
256 ## Run tests
257
258 You can easily run the test of all the components:
259
260 ```
261 meson test -C build
262 ```
263
264 To list all available tests:
265
266 ```
267 meson test -C builddir --list
268 ```
269
270 To run all the tests of a specific component:
271
272 ```
273 meson test -C builddir --suite gst-plugins-base
274 ```
275
276 Or to run a specific test file:
277
278 ```
279 meson test -C builddir --suite gstreamer gst_gstbuffer
280 ```
281
282 Run a specific test from a specific test file:
283
284 ```
285 GST_CHECKS=test_subbuffer meson test -C builddir --suite gstreamer gst_gstbuffer
286 ```
287
288 ## Optional Installation
289
290 You can also install everything that is built into a predetermined prefix like
291 so:
292
293 ```
294 meson --prefix=/path/to/install/prefix builddir
295 ninja -C builddir
296 meson install -C builddir
297 ```
298
299 Note that the installed files have `RPATH` stripped, so you will need to set
300 `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, or `PATH` as appropriate for your
301 platform for things to work.
302
303
304 ## Add information about GStreamer development environment in your prompt line
305
306 ### Bash prompt
307
308 We automatically handle `bash` and set `$PS1` accordingly.
309
310 If the automatic `$PS1` override is not desired (maybe you have a fancy custom
311 prompt), set the `$GST_BUILD_DISABLE_PS1_OVERRIDE` environment variable to
312 `TRUE` and use `$GST_ENV` when setting the custom prompt, for example with a
313 snippet like the following:
314
315 ```bash
316 ...
317 if [[ -n "${GST_ENV-}" ]];
318 then
319   PS1+="[ ${GST_ENV} ]"
320 fi
321 ...
322 ```
323
324 ### Using powerline
325
326 In your powerline theme configuration file (by default in
327 `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`)
328 you should add a new environment segment as follow:
329
330 ```
331 {
332   "function": "powerline.segments.common.env.environment",
333   "args": { "variable": "GST_ENV" },
334   "priority": 50
335 },
336 ```
337
338 ## Windows Prerequisites Setup
339
340 On Windows, some of the components may require special care.
341
342 ### Git for Windows
343
344 Use the [Git for Windows](https://gitforwindows.org/) installer. It will
345 install a `bash` prompt with basic shell utils and up-to-date git binaries.
346
347 During installation, when prompted about `PATH`, you should select the
348 following option:
349
350 ![Select "Git from the command line and also from 3rd-party software"](/data/images/git-installer-PATH.png)
351
352 ### Python 3.5+ on Windows
353
354 Use the [official Python installer](https://www.python.org/downloads/windows/).
355 You must ensure that Python is installed into `PATH`:
356
357 ![Enable Add Python to PATH, then click Customize Installation](/data/images/py-installer-page1.png)
358
359 You may also want to customize the installation and install it into
360 a system-wide location such as `C:\PythonXY`, but this is not required.
361
362 ### Ninja on Windows
363
364 The easiest way to install Ninja on Windows is with `pip3`, which will download
365 the compiled binary and place it into the `Scripts` directory inside your
366 Python installation:
367
368 ```
369 pip3 install ninja
370 ```
371
372 You can also download the [official release](https://github.com/ninja-build/ninja/releases)
373 and place it into `PATH`.
374
375 ### Meson on Windows
376
377 **IMPORTANT**: Do not use the Meson MSI installer since it is experimental and known to not
378 work with `GStreamer`.
379
380 You can use `pip3` to install Meson, same as Ninja above:
381
382 ```
383 pip3 install meson
384 ```
385
386 Note that Meson is written entirely in Python, so you can also run it as-is
387 from the [git repository](https://github.com/mesonbuild/meson/) if you want to
388 use the latest master branch for some reason.
389
390 ### Running Meson on Windows
391
392 At present, to build with Visual Studio, you need to run Meson from inside the
393 VS 2019 command prompt. Press `Start`, and search for `VS 2019`, and click on
394 `x64 Native Tools Command Prompt for VS 2019`, or a prompt named similar to
395 that:
396
397 ![x64 Native Tools Command Prompt for VS 2019](/data/images/vs-2019-dev-prompt.png)
398
399 **ARM64 native only**: Since Visual Studio might not install dedicated command
400 prompt for native ARM64 build, you might need to run `vcvarsx86_arm64.bat` on CMD.
401 Please refer to [this document](https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019#developer_command_file_locations)
402
403 ### Setup a mingw/wine based development environment on linux
404
405 #### Install wine and mingw
406
407 ##### On fedora x64
408
409 ``` sh
410 sudo dnf install mingw64-gcc mingw64-gcc-c++ mingw64-pkg-config mingw64-winpthreads wine
411 ```
412
413 FIXME: Figure out what needs to be installed on other distros
414
415 #### Get meson from git
416
417 This simplifies the process and allows us to use the cross files
418 defined in meson itself.
419
420 ``` sh
421 git clone https://github.com/mesonbuild/meson.git
422 ```
423
424 #### Build and install
425
426 ```
427 BUILDDIR=$PWD/winebuild/
428 export WINEPREFIX=$BUILDDIR/wine-prefix/ && mkdir -p $WINEPREFIX
429 # Setting the prefix is mandatory as it is used to setup symlinks within the development environment
430 meson/meson.py $BUILDDIR --cross-file meson/cross/linux-mingw-w64-64bit.txt -Dgst-plugins-bad:vulkan=disabled -Dorc:gtk_doc=disabled --prefix=$BUILDDIR/wininstall/ -Djson-glib:gtk_doc=disabled
431 meson/meson.py install -C $BUILDDIR/
432 ```
433
434 > __NOTE__: You should use `meson install -C $BUILDDIR`  each time you make a change
435 > instead of the usual `ninja -C build` as this is not in the development environment.
436
437 #### The development environment
438
439 You can get into the development environment the usual way:
440
441 ```
442 ninja -C $BUILDDIR/ devenv
443 ```
444
445 Alternatively, if you'd rather not start a shell in your workflow, you
446 can mutate the current environment into a suitable state like so:
447
448 ```
449 gst-env.py --only-environment
450 ```
451
452 This will print output suitable for an sh-compatible `eval` function,
453 just like `ssh-agent -s`.
454
455 After setting up [binfmt] to use wine for windows binaries,
456 you can run GStreamer tools under wine by running:
457
458 ```
459 gst-launch-1.0.exe videotestsrc ! glimagesink
460 ```
461
462 [binfmt]: http://man7.org/linux/man-pages/man5/binfmt.d.5.html