view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    App::FfmpegUtils - Utilities related to ffmpeg

VERSION
    This document describes version 0.016 of App::FfmpegUtils (from Perl
    distribution App-FfmpegUtils), released on 2026-08-26.

FUNCTIONS
  cut_duration_from_video
    Usage:

     cut_duration_from_video(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Cut (censor out) a duration out of a video.

    Examples:

    *   Specify start & end only (using h:m:s notation), the result is
        100s.cut_50_to_63.mp4:

         cut_duration_from_video(files => ["100s.mp4"], end => "00:01:03", start => "00:00:50");

    *   Specify start & duration only (using seconds), the result is
        100s.cut_50_to_63.mp4:

         cut_duration_from_video(files => ["100s.mp4"], duration => 13, start => 50);

    *   Specify end & duration only (using human & ISO 8601 notation), the
        result is 100s.cut_50_to_63.mp4:

         cut_duration_from_video(files => ["100s.mp4"], duration => "13s", end => "PT63S");

    This utility uses *ffmpeg* (particularly the "-t" and "-ss") option to
    cut a portion (time range) out of a video. It can be used to remove an
    unwanted scene from a video.

    Compared to using "ffmpeg" directly, this wrapper offers convenience of
    more flexibility in specifying times and duration (e.g. '15s' as well as
    '00:10' as well as 'PT1M30S'), specifying only 'end' and 'duration',
    handling multiple files, automatically choosing output filename, and tab
    completion.

    Alternatives:

    1. If you just want to play a video and censor out certain parts, you
    can use create a playlist of segments called an EDL file. See for
    example:

    <https://github.com/mpv-player/mpv/blob/master/DOCS/edl-mpv.rst>

    This function is not exported.

    This function supports dry-run operation.

    Arguments ('*' denotes required arguments):

    *   copy => *bool*

        Whether to use the "copy" codec (fast but produces inaccurate
        timings).

    *   duration => *duration|percent_str*

        (No description)

    *   end => *duration|percent_str*

        (No description)

    *   files* => *array[filename]*

        (No description)

    *   start => *duration|percent_str* (default: 0)

        (No description)

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  cut_video_by_duration
    Usage:

     cut_video_by_duration(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Get a portion (time range) of a video.

    Examples:

    *   Specify start only, the result is 100s.cut_40_to_100.mp4:

         cut_video_by_duration(files => ["100s.mp4"], start => "40s");

    *   Specify duration only (using percentage) of two files, the results
        are 100s.cut_0_to_30.mp4 & 50s.cut_0_to_15.mp4:

         cut_video_by_duration(files => ["100s.mp4", "50s.mp4"], duration => "30%");

    *   Specify end only (using h:m:s notation), the result is
        100s.cut_0_to_63.mp4:

         cut_video_by_duration(files => ["100s.mp4"], end => "00:01:03");

    *   Specify start & end only (using h:m:s notation), the result is
        100s.cut_50_to_63.mp4:

         cut_video_by_duration(files => ["100s.mp4"], end => "00:01:03", start => "00:00:50");

    *   Specify start & duration only (using seconds), the result is
        100s.cut_50_to_63.mp4:

         cut_video_by_duration(files => ["100s.mp4"], duration => 13, start => 50);

    *   Specify end & duration only (using human & ISO 8601 notation), the
        result is 100s.cut_50_to_63.mp4:

         cut_video_by_duration(files => ["100s.mp4"], duration => "13s", end => "PT63S");

    This utility uses *ffmpeg* (particularly the "-t" and "-ss") option to
    get a portion (time range) of a video.

    Compared to using "ffmpeg" directly, this wrapper offers convenience of
    more flexibility in specifying times and duration (e.g. '15s' as well as
    '00:10' as well as 'PT1M30S'), specifying only 'end' and 'duration',
    handling multiple files, automatically choosing output filename, and tab
    completion.

    This function is not exported.

    This function supports dry-run operation.

    Arguments ('*' denotes required arguments):

    *   copy => *bool*

        Whether to use the "copy" codec (fast but produces inaccurate
        timings).

    *   duration => *duration|percent_str*

        (No description)

    *   end => *duration|percent_str*

        (No description)

    *   files* => *array[filename]*

        (No description)

    *   overwrite => *bool*

        (No description)

    *   start => *duration|percent_str* (default: 0)

        (No description)

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  join_audio
    Usage:

     join_audio(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Join two or more audios (e.g. MP3 files).

    Examples:

    *   Join 3 MP3 files, output in joined.mp3:

         join_audio(files => ["1.mp3", "2.mp3", "3.mp3"]);

    This utility uses *ffmpeg* to join two or more audio files (e.g. MP3
    files) into one.

    This function is not exported.

    This function supports dry-run operation.

    Arguments ('*' denotes required arguments):

    *   copy => *bool* (default: 1)

        Whether to use the "copy" codec (fast but produces inaccurate
        timings).

    *   files* => *array[filename]*

        (No description)

    *   output => *filename* (default: "joined.mp3")

        (No description)

    *   overwrite => *bool*

README  view on Meta::CPAN

        Scale video to specified size. See Math::Image::CalcResized or
        calc-image-resized-size for more details on scale specification.
        Some examples include:

        The default is "1080^>" which means to shrink to 1080p if video size
        is larger than 1080p.

        To disable scaling, set "--scale" to '' (empty string), or specify
        "--dont-scale" on the CLI.

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

  split_video_by_duration
    Usage:

     split_video_by_duration(%args) -> [$status_code, $reason, $payload, \%result_meta]

    Split video by duration into parts.

    This utility uses ffmpeg (particularly the "-t" and "-ss") option to
    split a longer video into shorter videos. For example, if you have
    "long.mp4" with duration of 1h12m and you run it through this utility
    with "--every 15min" then you will have 5 new video files:
    "long.1of5.mp4" (15min), "long.2of5.mp4" (15min), "long.3of5.mp4"
    (15min), "long.4of5.mp4" (15min), and "long.5of5.mp4" (12min).

    Compared to using "ffmpeg" directly, this wrapper offers convenience of
    calculating the times ("-ss") option for you, handling multiple files,
    automatically choosing output filename, and tab completion.

    This function is not exported.

    This function supports dry-run operation.

    Arguments ('*' denotes required arguments):

    *   copy => *bool*

        Whether to use the "copy" codec (fast but produces inaccurate
        timings).

    *   every => *duration|percent_str*

        (No description)

    *   files* => *array[filename]*

        (No description)

    *   overwrite => *bool*

        (No description)

    *   parts => *posint*

        (No description)

    Special arguments:

    *   -dry_run => *bool*

        Pass -dry_run=>1 to enable simulation mode.

    Returns an enveloped result (an array).

    First element ($status_code) is an integer containing HTTP-like status
    code (200 means OK, 4xx caller error, 5xx function error). Second
    element ($reason) is a string containing error message, or something
    like "OK" if status is 200. Third element ($payload) is the actual
    result, but usually not present when enveloped result is an error
    response ($status_code is not 2xx). Fourth element (%result_meta) is
    called result metadata and is optional, a hash that contains extra
    information, much like how HTTP response headers provide additional
    metadata.

    Return value: (any)

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/App-FfmpegUtils>.

SOURCE
    Source repository is at
    <https://github.com/perlancar/perl-App-FfmpegUtils>.

AUTHOR
    perlancar <perlancar@cpan.org>

CONTRIBUTOR
    Steven Haryanto <stevenharyanto@gmail.com>

CONTRIBUTING
    To contribute, you can send patches by email/via RT, or send pull
    requests on GitHub.

    Most of the time, you don't need to build the distribution yourself. You
    can simply modify the code, then test via:

     % prove -l

    If you want to build the distribution (e.g. to try to install it locally
    on your system), you can install Dist::Zilla,