>Psychtoolbox>PsychDocumentation

VideoRecording - Parameter settings, howtos and tips for Video recording.

This file describes how to use the [GStreamer](GStreamer) and DC1394 video capture engines
for video (and audio) recording into movie files. The [GStreamer](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](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](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](GStreamer)][(GStreamer)]((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](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.