.\" 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::Pipe 3pm"
.TH Media::Convert::Pipe 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::Pipe \- class to generate ffmpeg command lines with Media::Convert::Asset
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Media::Convert::Asset;
\&  use Media::Convert::Pipe;
\&
\&  my $input_audio = Media::Convert::Asset\->new(url => $input_filename_audio);
\&  my $input_video = Media::Convert::Asset\->new(url => $input_filename_video);
\&  my $output = Media::Convert::Asset\->new(url => $output_filename);
\&  my $map_audio = Media::Convert::Map\->new(input => $input_audio, type => "stream", choice => "audio");
\&  my $map_video = Media::Convert::Map\->new(input => $input_video, type => "stream", choice => "video");
\&  my $pipe = Media::Convert::Pipe\->new(inputs => [$input_audio, $input_video], map => [ $map_audio, $map_video ], output => $output);
\&  $pipe\->run();
\&
\&  # Or, if progress information is wanted:
\&  sub print_progress {
\&    my $percentage = shift;
\&    print "Transcoding progress: $percentage\er";
\&  }
\&  $pipe\->progress(\e&print_progress);
\&  $pipe\->run();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Media::Convert::Pipe\*(C'\fR is the class in the \f(CW\*(C`Media::Convert\*(C'\fR package
which does most of the hard work inside \f(CW\*(C`Media::Convert\*(C'\fR. It generates
and runs the ffmpeg command line, capturing the output where required.
.PP
\&\f(CW\*(C`Media::Convert::Pipe\*(C'\fR will compare the properties of the input
\&\f(CW\*(C`Media::Convert::Asset\*(C'\fR objects against those of the output
\&\f(CW\*(C`Media::Convert::Asset\*(C'\fR object, and will add the necessary parameters
to the ffmpeg command line to convert the audio/video material in the
input file to the format required by the output file.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
The following attributes are supported by \f(CW\*(C`Media::Convert::Pipe\*(C'\fR.
.SS "inputs"
.IX Subsection "inputs"
The objects to read from. Must be \f(CW\*(C`Media::Convert::Asset\*(C'\fR objects. If
more than one object is passed, a value for the \f(CW\*(C`map\*(C'\fR attribute may be
required to tell ffmpeg which audio/video stream to read from which
file.
.PP
More input objects can be added using the \f(CW\*(C`add_input\*(C'\fR method, and they
can all be removed using the \f(CW\*(C`clear_inputs\*(C'\fR object.
.SS "output"
.IX Subsection "output"
The object to write to. Must be a \f(CW\*(C`Media::Convert::Asset\*(C'\fR object.
Required.
.PP
If any properties differ between the input objects and the output
object (e.g., the codec, pixel format, audio sample frequency, video
resolution, etc etc etc), \f(CW\*(C`Media::Convert::Pipe\*(C'\fR will add the necessary
command-line options to the ffmpeg command line to convert the video
from the input file to the output file.
.SS "map"
.IX Subsection "map"
Array of \f(CW\*(C`Media::Convert::Map\*(C'\fR objects, used to manipulate which audio
and video streams exactly will be written to the output file (and in
which order, etc).
.PP
For more info: see Media::Convert::Map.
.PP
Maps can be cleared with \f(CW\*(C`clear_map\*(C'\fR and added to with \f(CW\*(C`add_map\*(C'\fR.
.SS "vcopy"
.IX Subsection "vcopy"
Boolean. If true, explicitly tell \f(CW\*(C`Media::Convert\*(C'\fR to copy video
without transcoding it.
.PP
Normally, \f(CW\*(C`Media::Convert\*(C'\fR should not request a transcode if all
attributes of the input file and the output file are exactly the same.
Getting this right may sometimes be problematic, however. In such cases,
it can be good to explicitly say that the video should not be
transcoded. That's what this property is for.
.SS "acopy"
.IX Subsection "acopy"
The same as \f(CW\*(C`vcopy\*(C'\fR, but for audio rather than video.
.SS "vskip"
.IX Subsection "vskip"
Tell \f(CW\*(C`Media::Convert\*(C'\fR that the output file should not contain any
video (i.e., that it should skip handling of any video). This is implied
if the output container does not support video streams (e.g., the .wav
format), but is required if it does.
.SS "askip"
.IX Subsection "askip"
The same as \f(CW\*(C`vskip\*(C'\fR, but for audio rather than video.
.SS "multipass"
.IX Subsection "multipass"
Boolean. If true, the \f(CW\*(C`run\*(C'\fR method performs a two-pass encode, rather
than a single-pass encode.
.PP
Two-pass encodes will generate a better end result, but require more
time to perform.
.SS "progress"
.IX Subsection "progress"
Normally, \f(CW\*(C`Media::Convert::Pipe\*(C'\fR shows (and runs) the ffmpeg command.
Any output of the ffmpeg command is shown on stdout.
.PP
If this attribute is set to a coderef, then the following happens:
.ie n .IP "The ffmpeg command line that is executed gains ""\-progress /dev/stdout"" parameters" 4
.el .IP "The ffmpeg command line that is executed gains ``\-progress /dev/stdout'' parameters" 4
.IX Item "The ffmpeg command line that is executed gains -progress /dev/stdout parameters"
.PD 0
.IP "The output of the ffmpeg command is parsed, and the completion percentage calculated (and all other output suppressed)," 4
.IX Item "The output of the ffmpeg command is parsed, and the completion percentage calculated (and all other output suppressed),"
.IP "The coderef that was passed to this attribute is executed with the completion percentage as the only parameter whenever the percentage changes." 4
.IX Item "The coderef that was passed to this attribute is executed with the completion percentage as the only parameter whenever the percentage changes."
.PD
.SH "METHODS"
.IX Header "METHODS"
.SS "run"
.IX Subsection "run"
Run the ffmpeg command.
.PP
If this method is not run at least once, the object's destructor will
issue a warning.
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 194:" 4
.IX Item "Around line 194:"
=over should be: '=over' or '=over positive_number'