Media:...::Asset(3pm)

✨ NAME ✨

Hiii, welcome to Media:...::Asset(3pm) — the man page for Media::Convert::Asset, aka Media::Convert's very own representation of a media asset. 💖

---

🎀 SYNOPSIS 🎀

okay so here's the whole vibe in code form, no notes:

use Media::Convert::Asset;
use Media::Convert::ProfileFactory;
use Media::Convert::Pipe;

# convert any input file to VP9 at recommended settings for vertical resolution and frame rate
my $input = Media::Convert::Asset->new(url => $input_filename);
my $profile = Media::Convert::ProfileFactory->new("vp9", $input);
my $output = Media::Convert::Asset->new(url => $output_filename, reference => $profile);
Media::Convert::Pipe->new(inputs => [$input], output => $output)->run();

# do that again; but this time, force vorbis audio:
$output = Media::Convert::Asset->new(url => $other_filename, reference => $profile);
$output->audio_codec("libvorbis");
Media::Convert::Pipe->new(inputs => [$input], output => $output)->run();

# Merge the video stream from one file with the audio stream from another,
# and convert to VP9
use Media::Convert::Map;
my $input_v = Media::Convert::Asset->new(url => $input_video_filename);
my $input_a = Media::Convert::Asset->new(url => $input_audio_filename);
$profile = Media::Convert::ProfileFactory->new("vp9", $input);
$output = Media::Convert::Asset->new(url => $merged_filename, reference => $profile);
my $map_v = Media::Convert::Map->new(input => $input_v, type => "stream", choice => "video");
my $map_a = Media::Convert::Map->new(input => $input_a, type => "stream", choice => "audio");
Media::Convert::Pipe->new(inputs => [$input_a, $input_v], map => [$map_a, $map_v], output => $output)->run();

---

💅 DESCRIPTION 💅

So the tea is: the Media::Convert::Asset package exists to represent media assets inside Media::Convert. It's a Moose-based base class, and honestly a bunch of the other classes in Media::Convert are built on top of it. Main character energy, truly. 👑

There is one required attribute, and it's url — that's the filename of the asset. Just the one. That's it. 🫶

Now here's the part where it gets kind of magical. ✨ If the url attribute points to a file that actually exists, and you try to read any of the codec, framerate, bit rate, or similar attributes without explicitly writing to them first, then Media::Convert::Asset will go call ffprobe on the file in question and use whatever it finds to populate the attributes you asked for.

But if it does not — or if ffprobe is simply not capable of detecting the attribute you requested (which, lowkey, may totally be the case for things like audio or video bitrate) — then the attribute in question will just resolve to undef. Not dramatic, just facts. 💀

vibe check: reading an attribute you never wrote to = automatic ffprobe run. no writing first. iykyk.

And what if the url attribute points to a file that does not exist? Well bestie, if you try to read any of the codec, framerate, bit rate, or similar attributes without explicitly writing to them first, they will resolve to undef. That's the whole answer. 😭

HOWEVER. 🙈 If the reference attribute is populated with another Media::Convert::Asset object, then reading any of those same codec, framerate, bit rate, or similar attributes (again, without explicitly writing to them first) will resolve to the value of the requested attribute that is set or detected on the reference object. So the reference object is basically carrying the whole team on its back. 🧚

Also, just so you know: the return value of Media::Convert::ProfileFactory->create() is also a Media::Convert object, except it has different implementations of some of the probing methods. The reason it does that is so it can pick the correct values for things like bitrate and encoder speed, based on the properties that are set in the input object you handed to the Media::Convert::ProfileFactory->create() method. It's giving smart. It's giving adaptive. We stan. 🌸

One last thing — if you wanna know how to actually use the files that the Media::Convert::Asset object refers to in an ffmpeg command line, please go see Media::Convert::Pipe. That's where that conversation lives. 🌈

✨ ATTRIBUTES ✨

okay so Media::Convert::Asset has a whole little roster of attributes and honestly? they ate. every single one of these gets probed straight out of the ffprobe output unless it says otherwise below, so keep that in mind bestie 💖

---

url

the filename of the asset this object is supposed to deal with. Required at construction time — like, no url, no object, periodt. this one will not be probed. 🎀

mtime

the mtime of the file backing this asset. it's only defined if the file actually exists at the moment the attribute is first read, and heads up: it is not updated later on. so it's a snapshot, not a live feed. 🦋

canonical_duration

which value we're gonna take as the canonical duration while probing how long a media file is.

ngl this one exists because of pain 😭 some versions of ffprobe have bugs where they either read or write corrupt values for certain parts of a media file. sometimes the video stream length is correct but the container length is not, and sometimes it's literally the other way around. the way that it flip-flops is genuinely cursed.

so since it's impossible to pick a source that will always work as the probed value for the duration attribute, this has to be configurable in some way. slay.

this option can take the following values:

• container — uses the duration value parsed from the container file, rather than any particular stream. if the parsing of that value isn't buggy, this is the right thing to do, and therefore this is also the default. 👑
• video — uses the duration value parsed from the first video stream.
• audio — uses the duration value parsed from the first audio stream.

duration

the duration of this asset. peep "canonical_duration" for the details on how it gets probed. ⏳

duration_frames

the number of frames in this asset. 🎞️

duration_style

the time unit used for the duration attribute. one of 'seconds' (the default) or 'frames'. will not be probed.

⚠️ Deprecated; will be removed in a future release. use duration_frames instead of setting this to a non-default value. like, fr fr, don't get attached. 💀

force_key_frames

can be set to an expression that can be passed to ffmpeg's -force_key_frames parameter. will not be probed. 🔑

video_codec

the codec in use for the video stream. heads up tho: ffprobe will sometimes use a string (e.g., vp8) that is not the best choice when you're instructing ffmpeg to transcode video to that said codec — for vp8, using libvpx is what's recommended. Media::Convert::CodecMap is what maps detected codecs to output codecs and resolves this whole situation. 🧚

audio_codec

the codec in use for the audio stream. same deal as above, bestie: ffprobe will sometimes use a string (e.g., vorbis) that is not the best choice when instructing ffmpeg to transcode audio to that said codec — for vorbis, libvorbis is the recommended move. Media::Convert::CodecMap handles the mapping of detected codecs to output codecs and fixes it up. 🎧

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 ✨ — unlike literally every other attribute, it is not provided directly by ffprobe. instead, when this parameter is read, 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 attribute, or this one. pick a lane, babe.

🚨 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 those that don't, it will resolve to undef. so, like, expect the void sometimes 🫠

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

video_preset

the value for the -preset parameter. used by some codecs, like av1 (and pretty critical there, iykyk). 🎛️

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. geometry is fake, pixels are liars. 🙈

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. 🇺🇸✨

video_frame_length

the length of a single video frame in seconds, as a floating point number.

calculated as 1 / (video_framerate numerator / video_framerate denumerator)

probed from the value of video_framerate. Ignored if set.

fragment_start

if set, this instructs Media::Convert 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). the 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 Media::Convert::Asset 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. sooo handy.

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; peep "Media::Convert::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. 👀

⚠️ note that the ffmpeg run required to detect blackness is CPU intensive and may require a very long time to finish. like, go make a snack, bestie. maybe two snacks. 🍓

channel_layouts

returns an array of audio channel layouts, as detected by ffprobe. 🎚️

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

audio_channel_count

returns the number of channels in the first audio stream. 🎶

vstream_id

returns the numeric ID for the first video stream in this file. useful for the implementation of stream mappings etc; peep "Media::Convert::Map" 📽️

extra_params

add extra (output) parameters. this should be used sparingly — rather add some abstraction. 🙏

handles:

• add_param (adds an extra parameter)
• drop_param (delete a parameter)

input_params

add extra input parameters. this should be used sparingly — rather add some abstraction. 🙏

handles:

• add_input_param (adds an extra parameter)
• drop_input_param (delete a parameter)

time_offset

apply an input time offset to this video (only valid when used as an input video in Media::Convert::Pipe). can be used to apply A/V sync correction values. ⏱️

---

aaand that's the whole roster, bestie 💅 this page ships as perl v5.40.1, dated 2026-02-15, from the Media::Convert user-contributed Perl documentation. go forth and probe responsibly 🫶✨