ffmpeg-mcp

Extract frames from a video file and save each frame with a unique UUID filename.

Behavior: - If number_of_frames is provided, extracts that many frames evenly across the video. If requested frames exceed total frames available, caps at total frames. - If timestamp_offset is provided (and number_of_frames is None), extracts frames at every given second interval. - If neither is provided, defaults to extracting one frame per second. - number_of_frames takes priority if both are provided.

Params: input_video_path (str): Path to the input video file. number_of_frames (Optional[int]): Total number of frames to extract evenly across the video. timestamp_offset (Optional[int]): Time interval in seconds between frames.

Returns: List[str]: List of file paths for the extracted frames with UUID-based filenames.

Function to extract audio from the given input video.

Params: input_video_path (str): Path to the input video.

Returns: audio_file_path (str): Path to the audio file.

Generate a video clip from the given video file using ffmpeg-python.

Args: input_video_path (str): Path to the source video file. start_timestamp (float, optional): Start time in seconds. Defaults to 0.0. duration (float, optional): Clip length in seconds. Defaults to 5.0.

Returns: str: Path to the generated clip, or an exception message string on failure.

Crop a video using ffmpeg-python.

Params: input_video_path: Path to input video (required) safe_crop: If True, allows exact cropping (ignores mod-2 restrictions). Default: False height: Output height (default: 480) width: Output width (default: 640) x_offset: Top-left X coordinate of crop (default: 0) y_offset: Top-left Y coordinate of crop (default: 0)

Returns: str: Path to the cropped video.

Make gif using video path provided by user.

Args: input_video_path (str): Path to the source video file. start_timestamp (float, optional): Start time in seconds. Defaults to 0.0. duration (float, optional): Clip length in seconds. Defaults to 4.0.

Returns: str: Path to the generated clip, or an exception message string on failure.

Concatenate multiple video clips with transitions.

Args: input_video_clips (List[str]): A list of file paths (strings) to the video clips that will be concatenated. transition_type (str, optional): The type of transition to apply between clips. Supported transitions include: - fade (default), fadeblack, fadewhite, distance - wipeleft, wiperight, wipeup, wipedown - slideleft, slideright, slideup, slidedown - smoothleft, smoothright, smoothup, smoothdown - circlecrop, rectcrop, circleclose, circleopen - horzclose, horzopen, vertclose, vertopen - diagbl, diagbr, diagtl, diagtr - hlslice, hrslice, vuslice, vdslice - dissolve, pixelize, radial, hblur - wipetl, wipetr, wipebl, wipebr - zoomin, fadegrays, squeezev, squeezeh - hlwind, hrwind, vuwind, vdwind - coverleft, coverright, coverup, coverdown transition_duration (float, optional): Duration of the transition effect in seconds.

Returns: str: The absolute path to the final concatenated video with transitions applied.

Normalize multiple video clips in parallel by adjusting resolution, frame rate, codec, and compression parameters.

Parameters: input_video_clips (list[str]): should give input video clips in the form of string resolution (tuple, optional): Target resolution as (width, height). Defaults to (1280, 720). frame_rate (int, optional): Target frame rate. Defaults to 30. crf (int, optional): Constant Rate Factor for quality control (lower = better quality). Defaults to 23. audio_bitrate (str, optional): Target audio bitrate. Defaults to '128k'. preset (str, optional): Encoding speed vs. compression efficiency preset. Defaults to 'fast'. max_workers (int, optional): Number of parallel worker threads. If None, uses os.cpu_count().

Returns: list: Sorted list of file paths to the successfully normalized video clips.

Notes: - Runs normalization tasks in parallel using ThreadPoolExecutor. - Includes a progress bar (tqdm) to track processing status. - Automatically determines the number of workers based on CPU cores if not specified. - Skips clips that encounter errors but continues processing the rest.

Overlay an image on top of a video with timing control.

Args: input_video_path (str): Path to background video. overlay_image_path (str): Path to image file. output_filename (str): Output video filename (saved inside VIDEO_OVERLAY_PATH). positioning (Literal): Where to place overlay. scale (tuple | None): (width, height) to resize image before placing. keep_audio (bool): Whether to keep background audio. opacity (float | None): Transparency level (0–1). None = no alpha applied. start_time (float): When to start showing overlay (seconds). duration (float | None): How long to show overlay (seconds). None = until end of video.

Returns: str: Path to generated video.

Overlay a video on top of another with simple positioning. Loops the overlay video until the background video ends, trimming any extra frames.

Args: input_video_path (str): Path to background video. overlay_video_path (str): Path to overlay video. output_filename (str): Name of the output video file (saved inside VIDEO_OVERLAY_PATH). positioning (Literal): Where to place overlay. scale (tuple): (width, height) to resize overlay video before placing. keep_audio (bool): Whether to keep background audio.

Returns: str: Path to the generated video.

Trim and concatenate multiple videos (portrait orientation, normalize format).

Args: inputs (list[dict]): Each dict must have: - 'path' (str): path to the video file - 'start_time' (str, optional): start time in seconds - 'end_time' (str, optional): end time in seconds width (int): Width to scale each video (portrait). height (int): Height to scale each video (portrait). x (int): X position for overlay (default 0). y (int): Y position for overlay (default 0).

Returns: str: Path to the output video if successful. None: If an error occurs.

Upscales a video to 1080p, 2K, or 4K using FFmpeg while preserving aspect ratio and color accuracy.

Args: input_video_path (str): Path to the input video file. resolution (str, optional): Target resolution for upscaling. Acceptable values are '1080p', '2k', or '4k'. Defaults to '1080p'.

Returns: str: Path to the upscaled video if successful.

Function to extract metadata of the given input video.

Params: input_video_path (str): Path to the input video.

Returns: JSON of the video metadata.