.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SReview::Video 3pm"
.TH SReview::Video 3pm "2022-10-15" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
SReview::Video \- SReview internal representation of an asset
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use SReview::Video;
\&  use SReview::Video::ProfileFactory;
\&  use SReview::Videopipe;
\&
\&  # convert any input file to VP9 at recommended settings for vertical resolution and frame rate
\&  my $input = SReview::Video\->new(url => $input_filename);
\&  my $profile = SReview::Video::ProfileFactory\->new("vp9", $input);
\&  my $output = SReview::Video\->new(url => $output_filename, reference => $profile);
\&  SReview::Videopipe\->new(inputs => [$input], output => $output)\->run();
\&
\&  # do that again; but this time, force vorbis audio:
\&  $output = SReview::Video\->new(url => $other_filename, reference => $profile);
\&  $output\->audio_codec("libvorbis");
\&  SReview::Videopipe\->new(inputs => [$input], output => $output)\->run();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The SReview::Video package is used to represent media assets inside
SReview. It is a \f(CW\*(C`Moose\*(C'\fR\-based base class for much of the other Video*
classes in SReview.
.PP
There is one required attribute, \f(CW\*(C`url\*(C'\fR, which represents the filename
of the video (however, for SReview::Video::NGinX, it should be an \s-1HTTP
URL\s0 instead).
.PP
If the \f(CW\*(C`url\*(C'\fR attribute points to an existing file and an attempt is
made to read any of the codec, framerate, bit rate, or similar
attributes (without explicitly writing to them first), then
\&\f(CW\*(C`SReview::Video\*(C'\fR will call \f(CW\*(C`ffprobe\*(C'\fR on the file in question, and use
that to populate the requested attributes. If it does not, or \f(CW\*(C`ffprobe\*(C'\fR
is incapable of detecting the requested attribute (which may be the case
for things like audio or video bitrate), then the attribute in question
will resolve to \f(CW\*(C`undef\*(C'\fR.
.PP
If the \f(CW\*(C`url\*(C'\fR attribute does not point to an existing file and an
attempt is made to read any of the codec, framerate, bit rate, or
similar attributes (without explicitly writing to them first), then they
will resolve to \f(CW\*(C`undef\*(C'\fR. However, if the \f(CW\*(C`reference\*(C'\fR attribute is
populated with another \f(CW\*(C`SReview::Video\*(C'\fR object, then reading any of the
codec, framerate, bit rate, or similar attributes (without explicitly
writing to them first) will resolve to the value of the requested
attribute that is set or detected on the \f(CW\*(C`reference\*(C'\fR object.
.PP
The return value of \f(CW\*(C`SReview::Video::ProfileFactory\->create()\*(C'\fR is
also an SReview::Video object, but with different implementations of
some of the probing methods; this allows it to choose the correct values
for things like bitrate and encoder speed based on properties set in the
input object provided to the
\&\f(CW\*(C`SReview::Video::ProfileFactory\->create()\*(C'\fR method.
.PP
For more information on how to use the files referred to in the
\&\f(CW\*(C`SReview::Video\*(C'\fR object in an ffmpeg command line, please see
\&\f(CW\*(C`SReview::Videopipe\*(C'\fR.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
The following attributes are supported by SReview::Video. All attributes
will be probed from ffprobe output unless noted otherwise.
.SS "url"
.IX Subsection "url"
The filename of the asset this object should deal with. Required at
construction time. Will not be probed.
.SS "mtime"
.IX Subsection "mtime"
The mtime of the file backing this asset. Only defined if the file
exists at the time the attribute is first read, and is not updated later
on.
.SS "duration"
.IX Subsection "duration"
The duration of this asset.
.SS "duration_style"
.IX Subsection "duration_style"
The time unit is used for the \f(CW\*(C`duration\*(C'\fR attribute. One of 'seconds'
(default) or 'frames'. Will not be probed.
.SS "video_codec"
.IX Subsection "video_codec"
The codec in use for the video stream. Note that \f(CW\*(C`ffprobe\*(C'\fR will
sometimes use a string (e.g., \*(L"vp8\*(R") that is not the best choice when
instructing \f(CW\*(C`ffmpeg\*(C'\fR to transcode video to the said codec (for vp8, the
use of \*(L"libvpx\*(R" is recommended). \f(CW\*(C`SReview::CodecMap\*(C'\fR is used to map
detected codecs to output codecs and resolve this issue.
.SS "audio_codec"
.IX Subsection "audio_codec"
The codec in use for the audio stream. Note that \f(CW\*(C`ffprobe\*(C'\fR will
sometimes use a string (e.g., \*(L"vorbis\*(R") that is not the best choice when
instructing \f(CW\*(C`ffmpeg\*(C'\fR to transcode audio to the said codec (for vorbis,
the use of \*(L"libvorbis\*(R" is recommended). \f(CW\*(C`SReview::CodecMap\*(C'\fR is used to
map detected codecs to output codecs and resolve this issue.
.SS "video_size"
.IX Subsection "video_size"
A string representing the resolution of the video in \f(CW\*(C`WxH\*(C'\fR format,
where W is the width and H is the height.
.PP
This attribute is special in that in contrast to all the other
attributes, it is not provided directly by \f(CW\*(C`ffprobe\*(C'\fR; instead, when
this parameter is read, the \f(CW\*(C`video_width\*(C'\fR and \f(CW\*(C`video_height\*(C'\fR
attributes are read and combined.
.PP
That does mean that you should not read this attribute, and based on
that possibly set the height and/or width attributes of a video (or vice
versa). Instead, you should read \fIeither\fR the \f(CW\*(C`video_width\*(C'\fR and
\&\f(CW\*(C`video_height\*(C'\fR attribute, \fIor\fR this one.
.PP
Failure to follow this rule will result in undefined behaviour.
.SS "video_width"
.IX Subsection "video_width"
The width of the video, in pixels.
.SS "video_height"
.IX Subsection "video_height"
The height of the video, in pixels.
.SS "video_bitrate"
.IX Subsection "video_bitrate"
The bit rate of this video, in bits per second.
.PP
Note that not all container formats support probing the bitrate of the
encoded video or audio; when read on input objects with those that do
not, this will resolve to \f(CW\*(C`undef\*(C'\fR.
.SS "video_minrate"
.IX Subsection "video_minrate"
The minimum bit rate for this video, in bits per second.
.PP
Defaults to 0.5 * video_bitrate
.SS "video_maxrate"
.IX Subsection "video_maxrate"
The maximum bit rate for this video, in bits per second.
.PP
Defaults to 1.45 * video_bitrate
.SS "aspect_ratio"
.IX Subsection "aspect_ratio"
The Display Aspect Ratio of a video. Note that with non-square pixels,
this is not guaranteed to be what one would expect when reading the
\&\f(CW\*(C`video_size\*(C'\fR attribute.
.SS "audio_bitrate"
.IX Subsection "audio_bitrate"
The bit rate of the audio stream on this video, in bits per second
.SS "audio_samplerate"
.IX Subsection "audio_samplerate"
The sample rate of the audio, in samples per second
.SS "video_framerate"
.IX Subsection "video_framerate"
The frame rate of the video, as a fraction.
.PP
Note that in the weird \s-1US\s0 frame rate, this could be 30000/1001.
.SS "fragment_start"
.IX Subsection "fragment_start"
If set, this instructs SReview on read to only read a particular part of the
video from this file. Should be specified in seconds; will not be probed.
.SS "quality"
.IX Subsection "quality"
The quality used for the video encoding, i.e., the value passed to the \f(CW\*(C`\-crf\*(C'\fR
parameter. Mostly for use by a profile. Will not be probed.
.SS "metadata"
.IX Subsection "metadata"
Can be used to set video metadata (as per \f(CW\*(C`ffmpeg\*(C'\fR's \f(CW\*(C`\-metadata\*(C'\fR
parameter). Functions \f(CW\*(C`add_metadata\*(C'\fR and \f(CW\*(C`drop_metadata\*(C'\fR can be used
to add or remove individual metedata values. Will not be probed.
.SS "reference"
.IX Subsection "reference"
If set to any \f(CW\*(C`SReview::Video\*(C'\fR object, then when any value is being
probed, rather than trying to run \f(CW\*(C`ffprobe\*(C'\fR on the file pointed to by
our \f(CW\*(C`url\*(C'\fR attribute, we will use the value reported by the referenced
object.
.PP
Can be used in \*(L"build a file almost like this one, but with these things
different\*(R" kind of scenarios.
.PP
Will not be probed (obviously).
.SS "pix_fmt"
.IX Subsection "pix_fmt"
The pixel format (e.g., \f(CW\*(C`yuv420p\*(C'\fR or the likes) of the video.
.SS "astream_id"
.IX Subsection "astream_id"
Returns the numeric \s-1ID\s0 for the first audio stream in this file. Useful for the
implementation of stream mappings etc; see \f(CW\*(C`SReview::Map\*(C'\fR
.SS "blackspots"
.IX Subsection "blackspots"
Returns an array of hashes. Each hash contains a member \f(CW\*(C`start\*(C'\fR,
\&\f(CW\*(C`end\*(C'\fR, and \f(CW\*(C`duration\*(C'\fR, containing the start, end, and duration,
respectively, of locations in the video file that are (almost) entirely
black.
.PP
Could be used by a script for automatic review.
.PP
Note that the ffmpeg run required to detect blackness is \s-1CPU\s0 intensive
and may require a very long time to finish.
.SS "astream_ids"
.IX Subsection "astream_ids"
Returns an array with the IDs for the audio streams in this file.
.SS "astream_count"
.IX Subsection "astream_count"
Returns the number of audio streams in this file.
.SS "vstream_id"
.IX Subsection "vstream_id"
Returns the numeric \s-1ID\s0 for the first video stream in this file. Useful
for the implementation of stream mappings etc; see \f(CW\*(C`SReview::Map\*(C'\fR
.SS "extra_params"
.IX Subsection "extra_params"
Add extra parameters. This should be used sparingly, rather add some
abstraction.
.SS "time_offset"
.IX Subsection "time_offset"
Apply an input time offset to this video (only valid when used as an
input video in SReview::Videopipe). Can be used to apply A/V sync
correction values.