Media::Convert::Asset(3pm)

NAME
Media::Convert::Asset - Media::Convert representation of a media asset

SYNOPSIS
  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
The "Media::Convert::Asset" package is used to represent media assets inside "Media::Convert". It is a "Moose"-based base class for much of the other classes in "Media::Convert".

There is one required attribute, "url", which represents the filename of the asset.

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 "Media::Convert::Asset" 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 "Media::Convert::Asset" 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 "Media::Convert::ProfileFactory->create()" is also a Media::Convert 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 "Media::Convert::ProfileFactory->create()" method.

For more information on how to use the files referred to in the "Media::Convert::Asset" object in an ffmpeg command line, please see "Media::Convert::Pipe".

ATTRIBUTES
The following attributes are supported by "Media::Convert::Asset". 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.

  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.

  canonical_duration
Which value to take as the canonical duration while probing the duration of a media file.

Unfortunately, some versions of ffprobe have bugs in that they either read or write corrupt values for some parts of a media file. Sometimes the video stream length is correct but the container length is not, sometimes it is the other way around.

Since, given that, it is not possible to choose a source that will always work as the probed value for the duration attribute, this needs to be configurable in some way.

This option can take the following values:

container
    Uses the duration value that is parsed from the container file, rather than any particular stream. If the parsing of that value is not buggy, this is the right thing to do, and therefore this is also the default.

video
    Uses the duration value that is parsed from the first video stream.

audio
    Uses the duration value that is parsed from the first audio stream.

  duration
The duration of this asset. See "canonical_duration" for details on how it is probed.

  duration_frames
The number of frames in this asset.

  duration_style
The time unit is used for the "duration" attribute. One of 'seconds' (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.

  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. 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). "Media::Convert::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). "Media::Convert::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".

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

  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.

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

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

  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; see "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.