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

cpanm SReview

perl -MCPAN -e shell
install SReview