NAME

       SReview::Video - SReview internal representation of an asset

SYNOPSIS

         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();

DESCRIPTION

       The SReview::Video package is used to represent media assets inside SReview. It is a "Moose"-based base
       class for much of the other Video* classes in SReview.

       There is one required attribute, "url", which represents the filename of the video (however, for
       SReview::Video::NGinX, it should be an HTTP URL instead).

       If the "url" 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
       "SReview::Video" will call "ffprobe" on the file in question, and use that to populate the requested
       attributes. If it does not, or "ffprobe" 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 "undef".

       If the "url" 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 "undef". However, if the "reference" attribute is populated with another "SReview::Video"
       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 "reference" object.

       The return value of "SReview::Video::ProfileFactory->create()" 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
       "SReview::Video::ProfileFactory->create()" method.

       For more information on how to use the files referred to in the "SReview::Video" object in an ffmpeg
       command line, please see "SReview::Videopipe".

ATTRIBUTES

       The following attributes are supported by SReview::Video. All attributes will be probed from ffprobe
       output unless noted otherwise.

   url
       The filename of the asset this object should deal with. Required at construction time. Will not be
       probed.

   duration
       The duration of this asset.

   duration_style
       The time unit is used for the "duration" attribute. One of 'seconds' (default) or 'frames'. Will not be
       probed.

   video_codec
       The codec in use for the video stream. Note that "ffprobe" will sometimes use a string (e.g., "vp8") that
       is not the best choice when instructing "ffmpeg" to transcode video to the said codec (for vp8, the use
       of "libvpx" is recommended). "SReview::CodecMap" is used to map detected codecs to output codecs and
       resolve this issue.

   audio_codec
       The codec in use for the audio stream. Note that "ffprobe" will sometimes use a string (e.g., "vorbis")
       that is not the best choice when instructing "ffmpeg" to transcode audio to the said codec (for vorbis,
       the use of "libvorbis" is recommended). "SReview::CodecMap" is used to map detected codecs to output
       codecs and resolve this issue.

   video_size
       A string representing the resolution of the video in "WxH" format, where W is the width and H is the
       height.

       This attribute is special in that in contrast to all the other attributes, it is not provided directly by
       "ffprobe"; instead, when this parameter is read, the "video_width" and "video_height" attributes are read
       and combined.

       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 either the "video_width" and
       "video_height" attribute, or this one.

       Failure to follow this rule will result in undefined behaviour.

   video_width
       The width of the video, in pixels.

   video_height
       The height of the video, in pixels.

   video_bitrate
       The bit rate of this video, in bits per second.

       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 "undef".

   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 "video_size" attribute.

   audio_bitrate
       The bit rate of the audio stream on this video, in bits per second

   audio_samplerate
       The sample rate of the audio, in samples per second

   video_framerate
       The frame rate of the video, as a fraction.

       Note that in the weird US frame rate, this could be 30000/1001.

   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.

   quality
       The quality used for the video encoding, i.e., the value passed to the "-crf" parameter. Mostly for use
       by a profile. Will not be probed.

   metadata
       Can be used to set video metadata (as per "ffmpeg"'s "-metadata" parameter). Functions "add_metadata" and
       "drop_metadata" can be used to add or remove individual metedata values. Will not be probed.

   reference
       If set to any "SReview::Video" object, then when any value is being probed, rather than trying to run
       "ffprobe" on the file pointed to by our "url" attribute, we will use the value reported by the referenced
       object.

       Can be used in "build a file almost like this one, but with these things different" kind of scenarios.

       Will not be probed (obviously).

   pix_fmt
       The pixel format (e.g., "yuv420p" or the likes) of the video.

   astream_id
       Returns the numeric ID for the first audio stream in this file. Useful for the implementation of stream
       mappings etc; see "SReview::Map"

   vstream_id
       Returns the numeric ID for the first video stream in this file. Useful for the implementation of stream
       mappings etc; see "SReview::Map"

   extra_params
       Add extra parameters. This should be used sparingly, rather add some abstraction.