Media:...rt::Map(3pm)

💖 NAME 💖

Media::Convert::Map — the lil helper that maps streams and/or channels from an input asset into an output. it's giving matchmaker but for audio and video, fr fr 🎀

---

✨ 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 bestie, no cap. you use it to configure a Media::Asset::Pipe so it routes all your various audio or video streams and channels into the particular locations you want them. it's literally the air traffic controller of your media pipeline 🛬✨

It has three options, and yes they're iconic:

• input — has to be the Media::Convert::Asset we're mapping a stream or channel from. no substitutions, babe.
• type — picks what kind of routing you're configuring.
• choice — picks which input stream or channel you're grabbing from that type.

The way that type and choice work together?? obsessed. the value you give for type is what defines which values of choice are even valid. so like, one decides the vibe, the other decides the specifics 💅

---

🦋 ATTRIBUTES 🦋

💜 input

The asset we're reading data from. you must pass it to the same Media::Convert::Pipe as one of the elements in the input array. periodt.

🎀 type

The type of map being created. it must be one of these options, so pick wisely:

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. so if you don't say anything, this is what you get 🫶

Valid values for choice when this type is selected are:

• left — select the left channel in the first audio stream (assuming it's 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. one or the other, bestie, that's the whole bit 🎬🎧

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 lets you merge the first two audio streams into a single audio stream using the amix ffmpeg filter. very demure, very mindful 🧚

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 you gave

🚨 okay so listen: 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. don't do it, it will not slay. to discover the number of audio streams in a file, use the astream_count in Media::Convert::Asset method. check first, then choose 💀

allcopy

Copy all streams. every last one. no child left behind 🫶

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. main character energy for every single stream, as they deserve 👑

If this option is chosen, no choice value should be selected (any value given is ignored). so like, don't bother, she's not listening 🙈

none

No routing is done. this has the same effect as not passing any Media::Convert::Map object to Media::Convert::Pipe at all. sometimes the move is simply not moving ✨

---

perl v5.40.1 · 2026-02-15 · User Contributed Perl Documentation

and that's the whole page bestie, ily, go map some streams 💖🌸🦋🎀✨💅