Table of Contents

• Overview
• Simple examples
• Exporter Command
• Sampler Command
• Merger Command Guide
• Gmicer Command Guide
• Clutter Command
• Clipper Command
• Init Command
• Installation
• Help Options
• Contributing
• License

Overview

fxp_videoclipper is an open source tool for amateur videoclip creation. Videoclipper allows you to extract frames from a video, sample frames evenly, merge images, apply GMIC commands, transfer colors via CLUT, and create complete video clips. It supports several subcommands including exporter, sampler, merger, gmicer, clutter, and clipper.

To install the tool:

cargo install fxp_videoclipper

Make sure you have Rust and Cargo installed. For further installation instructions, see Installation.

Simple examples

Most simple possible scenario

fxp_videoclipper exporter -i Video.mp4
#Video_original_frames

fxp_videoclipper clipper -i Video_original_frames
#Video_original_frames.mp4 , the original video is reproduced, but rescaled and fps adjusted

Simple scenario with specific output

fxp_videoclipper exporter -i Video.mp4 -o aaa

fxp_videoclipper clipper -i aaa -o Video.mp4

Simple scenario with audio

fxp_videoclipper exporter -i Video.mp4 -a audio.mp3 -o aaa
#aaa

fxp_videoclipper clipper -i aaa -a audio.mp3 -o bbb.mp4
#video now now cut to the duration of audio, and merged together
#making a videoclip

Gmic example

fxp_videoclipper exporter -i Video.mp4
#Video_original_frames

fxp_videoclipper gmicer -i Video_original_frames cl_lineart 0,0,2,1,15,15,1,0,6,2,2,0,0,0,50,50
#Video_original_frames_cl_lineart
#the original command from gmic is:
#gmic image.png cl_lineart 0,0,2,1,15,15,1,0,6,2,2,0,0,0,50,50

Real world example

I made this video using the following commands

fxp_videoclipper exporter -i Video.mp4 -a audio.mp3
#Video_original_frames

fxp_videoclipper gmicer -i Video_original_frames cl_lineart 0,0,2,1,15,15,1,0,6,2,2,0,0,0,50,50
#Video_original_frames_cl_lineart

I selected one image from Video_original_frames and i fractalized it using GIMP and i passed some more filters to that one image. I got an image clut.png

fxp_videoclipper clutter -i Video_original_frames -l clut.png
#Video_original_frames_clutted

fxp_videoclipper merger -i Video_original_frames_clutted -r Video_original_frames_cl_lineart
#Video_original_frames_clutted_merged_0.5

fxp_videoclipper clipper -i Video_original_frames_clutted_merged_0.5 -a audio.mp3

Exporter Command

The exporter mode extracts frames from a video based on duration and resolution. It supports the following options:

• -i, –input : Input video file.
• -o, –output : Output directory to save frames. (Optional)
• -p, –pixel-limit : Maximum upper limit for pixel resolution. (Optional)
• -a, –audio : Optional MP3 file path. (Optional)
• -d, –duration : Duration in milliseconds to cut the video. (Optional)
• -f, –fps : Frames per second to extract. (Optional)

Below are several examples demonstrating how to use the exporter command.

Example 1: Basic Extraction

Extract frames from a video with a specified duration and FPS, saving them to an output directory.

fxp_videoclipper exporter \
  --input path/to/sample_video.mp4 \
  --output path/to/output_frames \
  --duration 30000 \
  --fps 25

Explanation:

• Extract frames from sample_video.mp4.
• Output frames are stored in output_frames.
• The video is cut to 30,000 milliseconds (30 seconds).
• 25 frames are extracted per second.

Example 2: Extraction with Pixel Limit and Audio

Extract frames using a pixel resolution upper limit and include an MP3 file.

fxp_videoclipper exporter \
  --input path/to/sample_video.mp4 \
  --output path/to/output_frames \
  --pixel-limit 1920 \
  --audio path/to/sample_audio.mp3 \
  --duration 45000 \
  --fps 30

Explanation:

• Uses a pixel limit of 1920 to ensure frames do not exceed this resolution.
• An optional audio file (sample_audio.mp3) is provided.
• The video clip is cut to 45 seconds with 30 frames per second.

Example 3: Minimal Command Usage

For a simple extraction without audio or pixel limitations, just provide the essential parameters.

fxp_videoclipper exporter -i sample_video.mp4 -o frames_output -d 20000 -f 15

Explanation:

• Uses shorthand flags for input (-i) and output (-o).
• Extracts frames from the first 20 seconds at 15 FPS.

Sampler Command

Sampler mode extracts frames evenly across a video. It supports several options for flexible sampling:

• -i, –input: Input video file.
• -o, –output: Output directory where the sampled frames will be saved. (Optional)
• -u, –multiple: Flag to enable extraction of multiple frames. (Optional)
• -n, –number: Specifies the number of frames to extract when using multiple sampling. (Optional)
• -a, –audio: Optional path to an MP3 file to accompany the sampling. (Optional)
• -d, –duration: Duration in milliseconds to cut the video for sampling. (Optional)

Below are some usage examples:

Example 1: Basic Single Frame Sampling

This command samples frames evenly across the video using default settings.

fxp_videoclipper sampler -i path/to/video.mp4

Explanation:

• Samples frames from video.mp4.
• No output directory is specified, so the default location is used, either the current directory or a directory retrieved from init configuration.

Example 2: Multiple Frame Sampling with Specified Number

Extract a fixed number of frames from the video and specify an output directory.

fxp_videoclipper sampler -i path/to/video.mp4 -o path/to/sampled_frames -u -n 10

Explanation:

• Uses the `–multiple` flag to extract multiple frames.
• Extracts 10 frames and saves them to the sampled_frames directory.

Example 3: Sampling with Audio Overlay and Custom Duration

Sample frames from a portion of the video and synchronize with an audio track.

fxp_videoclipper sampler -i path/to/video.mp4 -o path/to/sampled_frames -a path/to/audio.mp3 -d 30000

Explanation:

• Cuts the video to a 30,000 millisecond (30 seconds) clip.
• Uses an MP3 file for audio synchronization.
• Saves the sampled frames to the specified output directory.

Merger Command Guide

The merger command allows you to merge images from two different directories. The primary input directory is provided using the `–input` option, while the second directory is specified with `–second-directory`. You can also set an opacity level to control the blending effect.

• -i, –input: Input directory for the first set of images.
• -r, –second-directory: Path to the second image directory. (Optional)
• -o, –output: Output directory where merged images will be saved. (Optional)
• -t, –opacity: Opacity level for merging images. (Optional)

Example Usage

Here is an example of how to merge two directories with a custom opacity level:

fxp_videoclipper merger \
  --input path/to/first_directory \
  --second-directory path/to/second_directory \
  --output path/to/output_directory \
  --opacity 0.7

Explanation:

• Input Directory (`–input`) : The first directory containing images to merge.
• Second Directory (`–second-directory`): The second set of images to be merged.
• Output Directory (`–output`): The location where the merged images will be saved.
• Opacity (`–opacity`): Adjusts the blending; in this example, the opacity is set to 0.7.

With these instructions, users should be able to effectively utilize the merger functionality in fxp_videoclipper.

Gmicer Command Guide

The `gmicer` command processes each image in the input directory by applying a GMIC command with specified arguments. Additional GMIC arguments can be provided to customize the image processing, and an output directory may be specified to store the processed images.

• -i, –input: Input directory containing the images to process.
• -o, –output: Output directory where the processed images will be saved. (Optional)
• [GMIC_ARGS]…: Arguments that are directly passed to the GMIC command. (Optional)

Example Usage

Below is an example that applies a GMIC command to all images in the input directory:

fxp_videoclipper gmicer \
  --input path/to/input_directory \
  --output path/to/output_directory \
  -fx_dreamsmooth 10,0.5,0.8,1

Explanation

• Input Directory (`–input`): Specifies the folder containing the images you want to process.
• Output Directory (`–output`): Defines where the processed images will be saved; if omitted, the program may use default handling.
• GMIC Arguments (`[GMIC_ARGS]…`): Additional arguments passed to GMIC, allowing for customizable image processing. In the example, the GMIC command `-fx_dreamsmooth 10,0.5,0.8,1` is applied to each image.

This guide helps users understand how to leverage the GMIC functionality within `fxp_videoclipper` for batch image processing.

Clutter Command

Clutter mode transfers colors using a CLUT (Color Look-Up Table) file. This mode applies a color transfer effect to images from a given input directory. The available options are:

Usage: fxp_videoclipper clutter [OPTIONS] –input <INPUT> –clut <CLUT_IMAGE>

Options:

• -i, –input: Input directory.
• -o, –output: Output directory. (Optional)
• -l, –clut: Path to the source image used for CLUT. (Optional)
  • -h, –help: Print help.

Example 1: Basic CLUT Transfer

Apply a CLUT file to images in a directory, saving the output to a specified location.

fxp_videoclipper clutter \
  --input path/to/input_images \
  --output path/to/output_images \
  --clut path/to/clut_image.png

Explanation:

• Applies the color transfer using the CLUT image provided.
• Processes all images from input_images and outputs them to output_images.

Clipper Command

The clipper mode creates a complete videoclip by assembling processed frames. It supports the following options:

Usage: fxp_videoclipper clipper [OPTIONS] –input <INPUT>

Options:

• -i, –input: Input directory.
• -o, –output: Output video. (Optional)
• -a, –audio: Optional path to the MP3 file. (Optional)
• -f, –fps: Frames per second to extract. (Optional)
• -h, –help: Print help.

Example 1: Create Videoclip without Audio

Generate a videoclip from a series of frames stored in an input directory and output the final video.

fxp_videoclipper clipper \
  --input path/to/processed_frames \
  --output path/to/videoclip.mp4 \
  --fps 25

Explanation:

• Takes frames from processed_frames and assembles them into a video.
• The resulting video is saved as final_video.mp4.
• The clip is generated at 25 frames per second.

Example 2: Create Videoclip with Audio

Generate a videoclip from frames and synchronize it with an optional MP3 audio file.

fxp_videoclipper clipper \
  --input path/to/processed_frames \
  --output path/to/final_video.mp4 \
  --audio path/to/audio.mp3 \
  --fps 30

Explanation:

• Processes frames from processed_frames.
• The final video is output as final_video.mp4.
• An audio file (audio.mp3) is integrated.
• The video is created at 30 frames per second.

Init Command

fxp_videoclipper init
#Enter the default AUDIO path (current: None) (leave empty to skip): None
#Enter the default FPS value (current: 30): 30
#Enter the default Pixel Upper Limit (current: 480): 480
#Enter the default number of frames to sample (current: 1): 1
#Enter the overall opacity value (0.0 - 1.0, current: 0.5): 0.5

By running the above command, the user can save some default configuration for each videoclipper’s run.

By seting the audio path, exporter mode tries to find an audio file at the path defined. Sampler’s and Clipper’s mode output gets redirected directly to that directory or file. By typing None invalidates the audio path, and the default output for all modes becomes the current directory.

When running init, by continuous pressing [Enter], all the way through, no saved value is affected. All values will stay the same.

Installation

Before building and using fxp_videoclipper, ensure that you have the following tools installed with the required minimum versions:

Dependencies

• Rust and Cargo
  • Required for building the project.
  • Installation instructions: [https://www.rust-lang.org/tools/install]
• ffmpeg (version 6.1.1 or later)
  • Required for the exporter, sampler, and clipper subcommands.
    • On Ubuntu/Debian:

      sudo apt update && sudo apt install ffmpeg
                  

    • On macOS (using Homebrew):

      brew install ffmpeg
                  

    • Alternatively, download from: [https://ffmpeg.org/download.html]
• gmic (version 3.5.0 or later)
  • Required for the gmicer subcommand.
    • On Ubuntu/Debian:

      sudo apt update && sudo apt install gmic
                  

    • On macOS (using Homebrew):

      brew install gmic
                  

    • Alternatively, download from: [https://gmic.eu/download.html]
• ImageMagick (convert, version 6.9.12-98 or later)
  • Required for the clutter subcommand.
    • On Ubuntu/Debian:

      sudo apt update && sudo apt install imagemagick
                  

    • On macOS (using Homebrew):

      brew install imagemagick
                  

    • Alternatively, download from: [https://imagemagick.org/script/download.php]

Installing fxp_videoclipper

cargo install fxp_videoclipper

Help Options

The main command is `fxp_videoclipper`, which accepts global options and subcommands. To view the general help message:

fxp_videoclipper -h

For detailed help on each subcommand, append `-h` to the command name. For example, for the exporter:

fxp_videoclipper exporter -h

Contributing

Contributions are welcome!

License

fxp_videoclipper is released under the MIT License.