NAME
    App::FfmpegUtils - Utilities related to ffmpeg

VERSION
    This document describes version 0.014 of App::FfmpegUtils (from Perl
    distribution App-FfmpegUtils), released on 2024-09-22.

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*

        (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*

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

  reencode_video_with_libx264
    Usage:

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

    Re-encode video (using ffmpeg and libx264).

    This utility runs *ffmpeg* to re-encode your video files using the
    libx264 codec. It is a wrapper to simplify invocation of ffmpeg. It
    selects the appropriate ffmpeg options for you, allows you to specify
    multiple files, and picks appropriate output filenames. It also sports a
    "--dry-run" option to let you see ffmpeg options to be used without
    actually running ffmpeg.

    This utility is usually used to reduce the file size (and optionally
    video width/height) of videos so they are smaller, while minimizing
    quality loss. Smartphone-produced videos are often high bitrate (e.g.
    >10-20Mbit) and not yet well compressed, so they make a good input for
    this utility. The default setting is roughly similar to how Google
    Photos encodes videos (max 1080p).

    The default settings are:

     -v:c libx264
     -preset veryslow (to get the best compression rate, but with the slowest encoding time)
     -crf 28 (0-51, subjectively sane is 18-28, 18 ~ visually lossless, 28 ~ visually acceptable)

    when a downsizing is requested (using the "--downsize-to" option), this
    utility first checks each input video if it is indeed larger than the
    requested final size. If it is, then the "-vf scale" option is added.
    This utility also calculates a valid size for ffmpeg, since using "-vf
    scale=-1:720" sometimes results in failure due to odd number.

    Audio streams are copied, not re-encoded.

    Output filenames are:

     ORIGINAL_NAME.crf28.mp4

    or (if downsizing is done):

     ORIGINAL_NAME.480p-crf28.mp4

    This function is not exported.

    This function supports dry-run operation.

    Arguments ('*' denotes required arguments):

    *   audio_sample_rate => *uint*

        Set audio sample rate, in Hz.

    *   crf => *int*

        (No description)

    *   ffmpeg_path => *filename*

        (No description)

    *   files* => *array[filename]*

        (No description)

    *   frame_rate => *ufloat*

        Set frame rate, in fps.

    *   overwrite => *bool*

        (No description)

    *   preset => *str* (default: "veryslow")

        (No description)

    *   scale => *str* (default: "1080^>")

        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,
    Dist::Zilla::PluginBundle::Author::PERLANCAR,
    Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
    other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
    required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE
    This software is copyright (c) 2024, 2023, 2022, 2020 by perlancar
    <perlancar@cpan.org>.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=App-FfmpegUtils>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.