% VideoRecording - Parameter settings, howtos and tips for Video recording. % % This file describes how to use the GStreamer and DC1394 video capture engines % for video (and audio) recording into movie files. The GStreamer engine is % available on all operating systems and can record both video and sound. % The DC1394 engine is available on Linux and OSX and can currently only % record video, but no simultaneous audio. % % - Check VideoRecordingDemo for regular video recording via GStreamer! On % both MacOSX and MS-Windows, one often needs to pass special settings or % codec types for video recording and especially combined video + audio % recording to work. That demo illustrates at least one set of settings % which were shown to work on OSX and Windows in December 2013. % % - Check VideoDVCamCaptureDemo for video recording from DV cameras. These % cameras seem to need special treatment on all systems, but especially % on MS-Windows and the demo shows how to do that. % % - Check VideoMultiCameraCaptureDemo for video capture and recording from % multiple professional class IIDC/DCAM compliant firewire and USB cameras % on Linux and OSX via the DC1394 engine. % % Codec and parameter selection: % % % If you only want to record a movie with default settings, specify its % filename as 'targetmoviename' parameter to Screen('OpenVideocapture', ...); % % If you want to specify codecs and their settings as well, it is recommended % that you specify these settings in the 'targetmoviename' and specify the % moviefile name separately via the Screen('SetVideoCaptureParameter') interface, % e.g., to set the movie name to 'foo.avi' you'd use this command: % Screen('SetVideoCaptureParameter', grabber, 'SetNewMoviename=foo.avi'); % % If you want to use the default codec(s) with their default settings, % simply omit the parameter string. Psychtoolbox has a list of codecs that % it tries to use for video and audio encoding, together with reasonable % default parameters. It works its way down the list, starting with the most % suitable/efficient codec, until it finds a codec that is supported on % your system. Not all codecs may be installed by default on your operating % system. Especially proprietary, non-free, or patent-encumbered codecs may % not be installed on your system. You may have to select them explicitly % in the software center of your distribution (see "help GStreamer"). % % If you only want to specify settings for the automatically chosen default % codec, start the parameter string with ':CodecSettings=', followed by % parameters. % % If you want to chose a specific codec and (optionally) its settings, % start the parameter string with ':CodecType=', followed by the settings. % % Some video codecs are supported by our automatic setup code. These will % automatically select matching audio codecs and audio-video multiplexers % and reasonable default settings, so they are convenient for you to use: % % x264enc: A highly optimized H264 video encoder, automatically combined with the % faacenc or avenc_aac MPEG-4 AAC audio encoder and an AVI file % multiplexer or Quicktime mov file multiplexer. % % xvidenc: The XVid MPEG-4 video encoder + AAC audio in a AVI file. % % avenc_mpeg4: Another MPEG-4 video encoder + AAC audio in a AVI file. % % theoraenc: The Ogg Theora video encoder with Ogg Vorbis audio encoder and % Ogg file format multiplexer (.ogv files). % % vp8enc_webm: The VP-8 video codec with Ogg Vorbis audio in a WEBM (.webm) % video container (HTML-5 video). % % vp8enc_matroska: As above, but in a matroska file container. % % avenc_h263p: H.263 video encoder with AAC audio in a Quicktime container. % % yuvraw: Raw, uncompressed YUV video data with AAC audio in a avi container. % % huffyuv: Huffman encoded YUV raw video data + AAC audio in a % matroska container. This is a lossless video codec, but % it creates relatively large files. % % avenc_sgi: Stores video as a sequence of RLE compressed, lossless % encoded SGI image files. This format usually can only be % read and played back by Psychtoolbox itself and some % specialized tools. It also creates relatively large % files. % % The huffyuv and avenc_sgi encoders are mostly useful if you need % bit-exact image storage or storage of raw video sensor data (Bayer color % filter format), or of high bit depths video data, ie., with more than 8 % bpc. For most common use cases you can achieve qualitatively good enough % results at much smaller file sizes with the standard lossy codecs. % % Psychtoolbox supports high-level settings, which are relatively easy to % use and understand. We describe these first. Psychtoolbox also supports % low-level tweaking of codec specific settings, which require significant % knowledge about video and audio encoding and lots of tinkering, but % provide fine grained control over every tiny aspect of the recording % process. % % High level settings are not specific to a movie file format or choice of % codec. All settings are accepted for all formats and codecs and mapped to % corresponding format and codec specific low level settings, or they are % silently ignored if a specific file/codec combination doesn't support a % high level setting. These settings are the most frequently chosen % settings. % % High level settings are specified as Keyword=value pairs, without a blank % between the Keyword= and the value, and the first letter of the Keyword % being a capital letter. % % E.g.: ':CodecSettings= Keyframe=5 Videoquality=0.5' would encode using % the default video codec with a video encoding quality of 0.5 aka 50% and % a keyframe distance of maximum 5 frames. % % ':CodecType=xvidenc Keyframe=10 Videobitrate=1000' would choose the % "xvidenc" XVid video codec with a keyframe interval of 10 frames and a % average video bitrate of 1000 kilobits/sec. % % The following high level parameters are supported: % % Video encoding settings: % ------------------------ % % Interlaced=0/1 - Tell codec if input video material is interlaced. This % allows to optimize encoding further for smaller file size % and better quality. % % Keyframe=x - Set the maximum keyframe interval to at most 'x' frames. % Most video players can only seek/navigate in a video with % keyframe granularity. E.g., a keyframe setting of 10 would % mean that one can only move forward/backward or address a % specific target video frame with a stepsize or accuracy of % 10 frames. Lower numbers mean better navigation accuracy, % with 1 providing frame accurate positioning, and possibly % higher quality, but bigger video file sizes and potentially % higher computational load. If omitted, the codec selects % keyframe distances automatically, possibly dynamically, % depending on visual scene content. % % Videobitrate=x kb/s - Select video bit rate in kilobits per second. A direct % control of the tradeoff filesize vs. quality. Bigger % numbers mean higher quality and larger files. Codecs % interpret this number as target average rate or maximum % rate, depending on codec. Many codecs select this % parameter dynamically (variable bitrate coding VBR). % % Videoquality=x - A value between 0.0 and 1.0 to select target video quality % between 0% and 100%. This controls different aspects of the % encoding process, but bigger values mean higher quality and % sometimes bigger filesize and sometimes higher cpu processor % load during recording. If you have a slow computer and a % demanding video format (high resolution, high framerate) you % may need to lower video quality, so your poor machine can % cope. % % Profile=x - A value selecting the video encoding profile, where this is applicable. % Currently only the H264 encoder supports this setting and provides the % following profiles to select from: % % 0 = Baseline constrained profile. % 1 = Baseline profile. % 2 = Main profile. % 3 = High profile. % 4 = High profile with 10 bpc support. % 5 = High profile with YUV 4:2:2 sampling. % 6 = High profile with YUV 4:4:4 full resolution sampling. % 7 = High profile with 10 bpc support. Intra frame only. % 8 = High profile with YUV 4:2:2 sampling. Intra frame only. % 9 = High profile with YUV 4:4:4 full resolution sampling. Intra frame only. % % Note that not all values may be supported on your system, esp. the 10 bpc % profiles may not be supported by current PTB + GStreamer versions. % % Note that deficient video software like Apples Quicktime player may % only be able to play back movie files encoded in Baseline and maybe Main % profile, ie., for profile values 0, 1, and maybe 2. % % If Profile isn't specified, the default will be High profile, ie., it will % play back at high quality on good playback software like Psychtoolbox movie % playback engine, or with VLC and many other open-source playback applications, % but it won't play back with Apples Quicktime player. % % Audio encoding settings: % ------------------------ % % Audioquality=x - See Videoquality, this time for the audio encoding. % % Audiobitrate=x kb/s - See Videobitrate, this time for the audio encoding. % % Multiplexer / File format settings: % ----------------------------------- % % Timeresolution=x - How fine should time be resolved in the recorded footage? % A value of x means to divide 1 second into x units, i.e., % provide a time granularity of 1/x th of a second. This % influences file size, accuracy of time based navigation in % the video, possibly the accuracy of returned movie presentation % timestamps and of audio-video sync. If omitted, defaults to % 1/1000 th second aka 1 msec granularity. % % Faststart=0/1 - If set to 1, optimize recorded files for a fast load and start % of playback in players. This is usually what you want, so it is % on by default. % % Bigfiles=0/1 - If set to 1, allow recording of movie files with a size greater % than 2 GB. This is usually what you want, but it may cause % compatibility problems with playback software which can't handle % the "big file" file format. % % % Specifying low-level settings: % ------------------------------ % % For more control you can also specify the various codec types and their % low level settings in the syntax of the "gst-launch" GStreamer command % line utility. This disables use of the high-level settings and provides % full control: % % A video codec type and settings string is prefixed with: 'VideoCodec=' % followed by codec name and settings, postfixed with ':::', e.g., % 'VideoCodec=x264enc speed-preset=1 noise-reduction=100000 :::'. % % A audio codec type and settings follows the same logic, with the % 'AudioCodec=' prefix, e.g., 'AudioCodec=faac :::' % % A multiplexer is chosen via the 'Muxer=' prefix, but no low-level % settings can be passed to the multiplexer, only high-level settings as % described above. % % A specific (non-auto-selected) audio source and its settings can be % chosen via the 'AudioSource=' prefix, e.g., 'AudioSource=pulsesrc :::' to % select an audio input provided by the PulseAudio sound server explicitly. % % A full example string to select codecs and other low level settings would % look like this: % ':CodecType=VideoCodec=x264enc speed-preset=1 noise-reduction=100000 ::: AudioCodec=faac ::: AudioSource=pulsesrc ::: Muxer=avimux' % % Intermixing of high-level and low-level settings is also possible: % ':CodecType=x264enc Keyframe=1 Videobitrate=8192 AudioCodec=alawenc ::: AudioSource=pulsesrc ::: Muxer=qtmux' % This would select the x264enc H264 video codec, with high level settings, % and additionally choose (low-level) a specific audio codec, audio source % and multiplexer. % % You can find a list of supported codecs, sources and multiplexers by % typing 'gst-inspect' in a Unix or Windows terminal window. You can % list the available low-level settings (aka properties) via gst-inspect codecname. % % E.g., to list all available low-level properties of the x264enc codec, % you'd type "gst-inspect x264enc" in a terminal window. % % Please note that if you don't choose a Psychtoolbox supported video codec % from the list provided above, then you will need to specify all audio % codec and multiplexer settings manually, as Psychtoolbox doesn't know % which audio codecs or muxers to use with a video codec unknown to it. % % History: % 5.6.2011 mk Created. %