% GStreamer - Installation instructions for the GStreamer media framework.
%
% Psychtoolbox uses the GStreamer multi-media framework for all multi-media
% related operations. On MS-Windows and macOS with Matlab, GStreamer is also
% needed for high quality text rendering via Screen('DrawText').
%
% All movie playback, movie creation, video capture and video recording
% operations are based on GStreamer. These functions won't work without a
% working GStreamer installation on your system (with the exception of
% video capture from firewire and USB-Vision DCAM/IIDC machine vision
% cameras on Linux, where high-performance multi-camera capture works via
% libdc1394, see 'help VideoCaptureDC1394', and GStreamer is only needed
% for video recording, not live capture).
%
% You will need at least version 1.8 of GStreamer on Linux, and at least
% version 1.18 on Windows and macOS, but we recommend to use the latest
% available stable release of the version 1 series. For limited HDR
% playback support on Linux, you will need at least GStreamer 1.16 + some
% modifications to your playback scripts. For full HDR playback support on
% Linux, just as on Windows, you will need at least version 1.18. HDR
% playback is not yet supported on macOS due to macOS operating system
% deficiencies - an insufficiently advanced OpenGL implementation.
%
% Installation instructions:
%
%
% GNU/Linux:
%
% Any decent Linux distribution will include support for GStreamer-1 in its
% package management system, so you can easily install it via the software
% management tools of your system. If you install PTB via NeuroDebian, then
% most GStreamer packages will get automatically installed, with the
% possible exception of some optional packages with potential license or
% patent restrictions, so read on.
%
% You may need to install those extra plugin packages to play back all
% common audio and video file formats like MP3 and MP4. Video or movie
% recording with high quality (DivX, H.264) may also require recent
% versions of additional plugin packages which contain support for these
% formats. These may not installed by default due to licensing and patent
% clauses in place for some territories on this planet. You may want to
% specifically add them to your system depending on your format needs.
%
% An easy test is to run SimpleMovieDemo. If it fails or only plays sound,
% but not video, then some of the plugins are missing, e.g., the important
% "gst-libav" plugins. For basic HDR playback support, Ubuntu 20.04 LTS
% (and maybe 18.04 LTS - untested) would suffice. For full HDR playback
% support, you would need Ubuntu 20.10, or some 3rd party provided
% GStreamer 1.18+ packages, or packages built from source.
%
%
% MS-Windows and Apple OSX:
%
% macOS: You must install GStreamer if you want to use multi-media functions or
% if you want to use the high-quality text renderer with Matlab, which provides
% consistent, fast, high-quality text rendering, instead of the lower quality,
% officially unsupported, legacy Apple CoreText text renderer.
%
% If you don't intend to use such functionality then installation of GStreamer
% is optional on macOS. Screen will work normally, but abort with an error
% message if you try to use any multi-media functions.
%
% Windows: You must install GStreamer regardless if you want to use multi-media
% functionality or not, as the Screen() mex file won't work at all without
% GStreamer installed! You must install at least version 1.18.0 of the MSVC
% variant of GStreamer.
%
% Here is a FAQ entry on resolving GStreamer problems:
%
% <https://github.com/Psychtoolbox-3/Psychtoolbox-3/wiki/FAQ#how-to-resolve-gstreamer-problems>
%
% NOTE: If GStreamer complains about not being able to find some plugins,
% e.g., the video playback doesn't work because there is a GStreamer
% configuration problem, then it can help to delete the GStreamer plugin
% registry to force a rebuild of that database. E.g., under Windows-10, if
% your login user name would be Bob, you would probably have to delete the
% file:
%
% 'C:\Users\Bob\AppData\Local\Microsoft\Windows\INetCache\gstreamer-1.0\registry.x86_64-msvc.bin'
%
%
% Download and install the latest 64-Bit ("x86_64") GStreamer runtimes from:
%
% <http://gstreamer.freedesktop.org/download/>
%
% The following GStreamer runtime packages have been tested for good compatibility
% with Psychtoolbox 3.0.17 as of December 2020:
%
% For MS-Windows: 64-Bit Intel MSVC runtime v1.18.2 for use with 64-Bit Matlab/Octave.
%
% <https://gstreamer.freedesktop.org/data/pkg/windows/1.18.2/msvc/gstreamer-1.0-msvc-x86_64-1.18.2.msi>
%
% You *must* install the MSVC variants of GStreamer, not the MinGW64 variants!
%
%
% For Apple macOS: Runtime v1.18.2
%
% <https://gstreamer.freedesktop.org/data/pkg/osx/1.18.2/gstreamer-1.0-1.18.2-x86_64.pkg>
%
% When the installer asks you to select the components it should install,
% select a "Full installation" or "Complete installation", or if those
% options do not exist then select a "Custom installation" (instead of a
% "Basic installation" or such). Then, if you chose a "Custom installation"
% in the displayed list of packages to install, select *all* components
% manually, if you want support for all video formats and all
% functionality. Without this, many popular video formats like H264 video
% will not play at all, or video recording / video capture and similar
% functions may not work. In fact, even our own demos, e.g.,
% SimpleMovieDemo *will fail* if you don't have all codecs installed! -> If
% SimpleMovieDemo doesn't work, then the most likely cause is that you
% didn't select all GStreamer packages for installation, so restart the
% installer and repeat installation with the full set of packages.
%