NAME

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

SYNOPSIS

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

DESCRIPTION

       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.

ATTRIBUTES

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

   type
       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:

       left
           Select the left channel in the first audio stream (assuming it is a stereo stream)

       right
           Select the right channel in the first audio stream

       both
           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:

       audio
           Select the first audio stream from the input file

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

       any other number
           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".