SReview::Video(3pm)

💖 SReview::Video 💖

okay bestie, so this is the manual page for SReview::Video(3pm) — the Perl module that's basically the main character of media assets inside SReview. Let's get into it 🎀

---

✨ 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 🌸

So SReview::Video is the package that represents media assets inside SReview. It's a Moose-based base class for basically most of the other Video* classes in SReview. iconic behavior honestly 💅

There's one required attribute, url, and it's the filename of the video. BUT — plot twist — for SReview::Video::NGinX, it should be an HTTP URL instead. okayyy 👑

If your url attribute points to an existing file and you try to read any of the codec / framerate / bit rate / similar attributes (without having explicitly written to them first), then SReview::Video will go ahead and run ffprobe on that file and use the output to populate whatever you asked for. If it can't do that, or if ffprobe just can't detect the thing you want (which happens sometimes with stuff like audio or video bitrate), then the attribute in question resolves to undef. no drama, it just does. 😭

If your url attribute does NOT point to an existing file, and you try to read any of those codec / framerate / bit rate / similar attributes (again, without explicitly writing to them first), they'll resolve to undef too. BUT 💖 — if the reference attribute is populated with another SReview::Video object, then reading any of those codec / framerate / bit rate / 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. it's giving "borrow her notes" energy fr fr 🫶

Also, the return value of SReview::Video::ProfileFactory->create() is itself an SReview::Video object — but with different implementations of some of the probing methods. That's how it gets to pick the correct values for things like bitrate and encoder speed based on properties set in the input object you handed to the SReview::Video::ProfileFactory->create() method. slay.

And if you wanna know how to actually use the files referred to in the SReview::Video object inside an ffmpeg command line, go read SReview::Videopipe. iykyk 🌈

---

👑 ATTRIBUTES 👑

These are the attributes SReview::Video supports. All attributes will be probed from ffprobe output unless noted otherwise. noted!

🎀 url

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

🎀 mtime

The mtime of the file backing this asset. It's only defined if the file exists at the time the attribute is first read — and it does not get updated later on. periodt.

🎀 duration

The duration of this asset.

🎀 duration_style

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

🎀 video_codec

The codec in use for the video stream. Heads up bestie: ffprobe will sometimes hand you a string (like "vp8") that is not the best choice when you're telling ffmpeg to transcode video to that codec — for vp8, you actually want "libvpx". SReview::CodecMap is what maps detected codecs to output codecs so this whole thing gets resolved. 🦋

🎀 audio_codec

The codec in use for the audio stream. Same situation as above: ffprobe will sometimes use a string (e.g., "vorbis") that isn't the best pick when instructing ffmpeg to transcode audio to that codec (for vorbis, you want "libvorbis"). SReview::CodecMap maps detected codecs to output codecs and fixes it. 💜

🎀 video_size

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

This one is special — unlike literally every other attribute, it is NOT provided directly by ffprobe. Instead, when you read this parameter, the video_width and video_height attributes get read and combined. ✨

Which means: you should not read this attribute and then go set the height and/or width attributes of a video based on it (or the other way around). Instead, read either the video_width and video_height attributes, or this one. pick a lane bestie 💅

⚠️ Failure to follow this rule will result in undefined behaviour. not a vibe. do not do it. 💀

🎀 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 you read this on input objects with formats that don't support it, it'll resolve to undef. 🙈

🎀 video_minrate

The minimum bit rate for this video, in bits per second.

Defaults to 0.5 * video_bitrate

🎀 video_maxrate

The maximum bit rate for this video, in bits per second.

Defaults to 1.45 * video_bitrate

🎀 aspect_ratio

The Display Aspect Ratio of a video. Just so you know: with non-square pixels, this is not guaranteed to be what you'd expect when reading the video_size attribute. the more you know 🌈

🎀 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.

And yeah — with the weird US frame rate, this could be 30000/1001. we don't make the rules 😭

🎀 fragment_start

If set, this tells SReview to only read a particular part of the video from this file when reading. 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). The functions add_metadata and drop_metadata can be used to add or remove individual metedata values. Will not be probed.

🎀 reference

If you set this to any SReview::Video object, then when any value is being probed, instead of trying to run ffprobe on the file pointed to by our url attribute, we use the value reported by the referenced object. 🫶

It's perfect for those "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. Super useful for implementing stream mappings etc — see SReview::Map.

🎀 blackspots

Returns an array of hashes. Each hash contains a member start, end, and duration, containing the start, end, and duration, respectively, of locations in the video file that are (almost) entirely black. 🖤

Could be used by a script for automatic review.

⚠️ Heads up: the ffmpeg run required to detect blackness is CPU intensive and may require a very long time to finish. it's giving "go get a snack" energy 🍓

🎀 astream_ids

Returns an array with the IDs for the audio streams in this file.

🎀 astream_count

Returns the number of audio streams in this file.

🎀 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. bestie pls 🥺

🎀 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. 🎬

---

and that's the whole page, bestie!! every attribute, every warning, every vibe, preserved 💖

this was perl v5.32.1, dated 2021-09-09 — SReview::Video(3pm). thanks for reading, love u, go probe something ✨👑