DOKK / manpages / debian 12 / libmedia-convert-perl / Media::Convert::Map.3pm.en
Media::Convert::Map(3pm) User Contributed Perl Documentation Media::Convert::Map(3pm)

Media::Convert::Map - Map streams and/or channels from an input asset into an output

  use Media::Convert::Asset;
  use Media::Convert::Map;
  use Media::Convert::Pipe;
  my $input_video = Media::Convert::Asset->new(url => $input_with_video);
  my $input_audio = Media::Convert::Asset->new(url => $input_with_two_stereo_audio_streams);
  my $output = Media::Convert::Asset->new(url => $output_filename);
  # Merge the video from $input_video with the first audio stream from
  # $input_audio:
  my $map_video = Media::Convert::Map->new(input => $input_video, type => "stream", choice => "video");
  my $map_audio = Media::Convert::Map->new(input => $input_audio, type => "stream", choice => "audio");
  Media::Convert::Pipe->new(input => [$input_video, $input_audio], map => [$map_video, $map_audio], output => $output, vcopy => 1, acopy => 1)->run;
  # or, extract only the first audio stream:
  Media::Convert::Pipe->new(input => [$input_audio], map => [$map_audio], output => $output, acopy => 1, vskip => 1)->run;
  # or, extract the second audio stream:
  my $map_2nd_audio = Media::Convert::Map->new(input => $input_audio, type => "astream", choice => "2");
  Media::Convert::Pipe->new(input => [$input_audio], map => [$map_2nd_audio], output => $output, vskip => 1, acopy => 1);
  # or, extract only the left audio channel from the first audio stream
  # into a mono audio asset:
  my $map_left_audio = Media::Convert::Map->new(input => $input_audio, type => "channel", choice => "left");
  Media::Convert::Pipe->new(input => [$input_audio], map => [$map_left_audio], output => $output, vskip => 1, acopy => 1);

Media::Convert::Map is a helper object used to configure a Media::Asset::Pipe to route various audio or video streams and channels into particular locations.

It has three options: "input", which must be the Media::Convert::Asset from which we want to map a stream or channel; "type", which selects the type of routing to configure, and "choice", which selects which input stream or channel to use from the selected type.

The values for "type" and "choice" work together; the values of "type" define what the valid values of "choice" are.

The asset from which we are reading data. Must be passed to the same "Media::Convert::Pipe" as one of the elements in the input array.

The type of map that is being created. Must be one these options:

channel

Selects an audio channel from the first audio stream in the file, or mixes the first two audio channels from the first audio stream into one mono stream in the output file.

This value is the default.

Valid values for "choice" when this type is selected, are:

Select the left channel in the first audio stream (assuming it is a stereo stream)
Select the right channel in the first audio stream
Use "-ac 1" to perform a downmix of all audio channels in the first audio stream into a single mono channel.

stream

Selects either the first audio or the first video stream in the file

Valid values for "choice" when this type is selected, are:

Select the first audio stream from the input file
Select the first video stream from the input file

astream

Selects a specific audio stream from the file, or allows to merge the first two audio streams into a single audio stream, using the "amix" ffmpeg filter.

Valid values for "choice" when this type is selected, are:

-1
Use the "amix" ffmpeg filter to downmix the first two audio streams from the file into a single audio stream.
Select the Nth audio stream from the input file, where N is the number given.

It is an error to choose an audio stream with an index that is higher than the total number of audio streams in the input file. To discover the number of audio streams in a file, use the "astream_count" in Media::Convert::Asset method.

allcopy

Copy all streams.

The default behavior of ffmpeg is to copy only the first audio stream, the first video stream, and the first subtitle stream, from the input file into the output file.

When this is not wanted, a Media::Convert::Map object of type "allcopy" will copy all streams, not just the first of each type, into the output file.

If this option is chosen, no choice value should be selected (any value given is ignored).

none

No routing is done. This has the same effect as not passing any "Media::Convert::Map" object to "Media::Convert::Pipe".

2023-03-07 perl v5.36.0