.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Media::Convert::Map 3pm"
.TH Media::Convert::Map 3pm "2023-03-07" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Media::Convert::Map \- Map streams and/or channels from an input asset into an output
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  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);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
It has three options: \f(CW\*(C`input\*(C'\fR, which must be the
Media::Convert::Asset from which we want to map a stream or channel;
\&\f(CW\*(C`type\*(C'\fR, which selects the type of routing to configure, and \f(CW\*(C`choice\*(C'\fR,
which selects which input stream or channel to use from the selected
type.
.PP
The values for \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`choice\*(C'\fR work together; the values of
\&\f(CW\*(C`type\*(C'\fR define what the valid values of \f(CW\*(C`choice\*(C'\fR are.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "input"
.IX Subsection "input"
The asset from which we are reading data. \fIMust\fR be passed to the same
\&\f(CW\*(C`Media::Convert::Pipe\*(C'\fR as one of the elements in the input array.
.SS "type"
.IX Subsection "type"
The type of map that is being created. Must be one these options:
.PP
\fIchannel\fR
.IX Subsection "channel"
.PP
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.
.PP
This value is the default.
.PP
Valid values for \f(CW\*(C`choice\*(C'\fR when this type is selected, are:
.IP "left" 4
.IX Item "left"
Select the left channel in the first audio stream (assuming it is a
stereo stream)
.IP "right" 4
.IX Item "right"
Select the right channel in the first audio stream
.IP "both" 4
.IX Item "both"
Use \f(CW\*(C`\-ac 1\*(C'\fR to perform a downmix of all audio channels in the first
audio stream into a single mono channel.
.PP
\fIstream\fR
.IX Subsection "stream"
.PP
Selects either the first audio or the first video stream in the file
.PP
Valid values for \f(CW\*(C`choice\*(C'\fR when this type is selected, are:
.IP "audio" 4
.IX Item "audio"
Select the first audio stream from the input file
.IP "video" 4
.IX Item "video"
Select the first video stream from the input file
.PP
\fIastream\fR
.IX Subsection "astream"
.PP
Selects a specific audio stream from the file, or allows to merge the
first two audio streams into a single audio stream, using the \f(CW\*(C`amix\*(C'\fR
ffmpeg filter.
.PP
Valid values for \f(CW\*(C`choice\*(C'\fR when this type is selected, are:
.IP "\-1" 4
.IX Item "-1"
Use the \f(CW\*(C`amix\*(C'\fR ffmpeg filter to downmix the first two audio streams
from the file into a single audio stream.
.IP "any other number" 4
.IX Item "any other number"
Select the Nth audio stream from the input file, where N is the number
given.
.Sp
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
\&\*(L"astream_count\*(R" in Media::Convert::Asset method.
.PP
\fIallcopy\fR
.IX Subsection "allcopy"
.PP
Copy all streams.
.PP
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.
.PP
When this is not wanted, a Media::Convert::Map object of type \*(L"allcopy\*(R"
will copy \fIall\fR streams, not just the first of each type, into the
output file.
.PP
If this option is chosen, no choice value should be selected (any value
given is ignored).
.PP
\fInone\fR
.IX Subsection "none"
.PP
No routing is done. This has the same effect as not passing any
\&\f(CW\*(C`Media::Convert::Map\*(C'\fR object to \f(CW\*(C`Media::Convert::Pipe\*(C'\fR.