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