Video & Audio Editing MCP Server

Instructions

Implementation Reference

• server.py:666-772 (handler)

  The primary handler function implementing the 'add_image_overlay' MCP tool. It uses FFmpeg to overlay an image on a video, handling scaling, opacity, positioning (including presets like top_right), timing, and audio stream copying with fallback to re-encoding.
  def add_image_overlay(video_path: str, output_video_path: str, image_path: str, position: str = 'top_right', opacity: float = None, start_time: str = None, end_time: str = None, width: str = None, height: str = None) -> str: """Adds an image overlay (watermark/logo) to a video. Args: video_path: Path to the input video file. output_video_path: Path to save the video with the image overlay. image_path: Path to the image file for the overlay. position: Position of the overlay. Options: 'top_left', 'top_right', 'bottom_left', 'bottom_right', 'center'. Or specify custom coordinates like 'x=10:y=10'. opacity: Opacity of the overlay (0.0 to 1.0). If None, image's own alpha is used. start_time: Start time for the overlay (HH:MM:SS or seconds). If None, starts from beginning. end_time: End time for the overlay (HH:MM:SS or seconds). If None, lasts till end. width: Width for the overlay image (e.g., '100', 'iw*0.1'). Original if None. height: Height for the overlay image (e.g., '50', 'ih*0.1'). Original if None. Returns: A status message indicating success or failure. """ try: if not os.path.exists(video_path): return f"Error: Input video file not found at {video_path}" if not os.path.exists(image_path): return f"Error: Overlay image file not found at {image_path}" main_input = ffmpeg.input(video_path) overlay_input = ffmpeg.input(image_path) # Process the overlay image (scale, opacity) processed_overlay = overlay_input # Apply scaling if requested if width or height: scale_params = {} if width: scale_params['width'] = width if height: scale_params['height'] = height if width and not height: scale_params['height'] = '-1' # Auto-height maintaining aspect if height and not width: scale_params['width'] = '-1' # Auto-width maintaining aspect processed_overlay = processed_overlay.filter('scale', **scale_params) # Apply opacity if requested if opacity is not None and 0.0 <= opacity <= 1.0: # Ensure image has alpha channel, then apply opacity processed_overlay = processed_overlay.filter('format', 'rgba') # Ensure alpha channel exists processed_overlay = processed_overlay.filter('colorchannelmixer', aa=str(opacity)) # Determine overlay position coordinates overlay_x_pos = '0' overlay_y_pos = '0' if position == 'top_left': overlay_x_pos, overlay_y_pos = '10', '10' elif position == 'top_right': overlay_x_pos, overlay_y_pos = 'main_w-overlay_w-10', '10' elif position == 'bottom_left': overlay_x_pos, overlay_y_pos = '10', 'main_h-overlay_h-10' elif position == 'bottom_right': overlay_x_pos, overlay_y_pos = 'main_w-overlay_w-10', 'main_h-overlay_h-10' elif position == 'center': overlay_x_pos, overlay_y_pos = '(main_w-overlay_w)/2', '(main_h-overlay_h)/2' elif ':' in position: pos_parts = position.split(':') for part in pos_parts: if part.startswith('x='): overlay_x_pos = part.split('=')[1] if part.startswith('y='): overlay_y_pos = part.split('=')[1] # Prepare overlay filter parameters overlay_filter_kwargs = {'x': overlay_x_pos, 'y': overlay_y_pos} # Add time-based enabling condition if specified if start_time is not None or end_time is not None: actual_start_time = start_time if start_time is not None else '0' if end_time is not None: enable_expr = f"between(t,{actual_start_time},{end_time})" else: # Only start_time is provided enable_expr = f"gte(t,{actual_start_time})" overlay_filter_kwargs['enable'] = enable_expr try: # Attempt 1: Create overlay with audio copying video_with_overlay = ffmpeg.filter([main_input, processed_overlay], 'overlay', **overlay_filter_kwargs) output_node = ffmpeg.output(video_with_overlay, main_input.audio, output_video_path, acodec='copy') output_node.run(capture_stdout=True, capture_stderr=True) return f"Image overlay added successfully (audio copied) to {output_video_path}" except ffmpeg.Error as e_acopy: try: # Attempt 2: Re-encode audio if copying fails # We need to reconstruct the filter chain video_with_overlay_fallback = ffmpeg.filter([main_input, processed_overlay], 'overlay', **overlay_filter_kwargs) output_node_fallback = ffmpeg.output(video_with_overlay_fallback, main_input.audio, output_video_path) output_node_fallback.run(capture_stdout=True, capture_stderr=True) return f"Image overlay added successfully (audio re-encoded) to {output_video_path}" except ffmpeg.Error as e_recode: err_acopy_msg = e_acopy.stderr.decode('utf8') if e_acopy.stderr else str(e_acopy) err_recode_msg = e_recode.stderr.decode('utf8') if e_recode.stderr else str(e_recode) return f"Error adding image overlay. Audio copy attempt: {err_acopy_msg}. Full re-encode attempt: {err_recode_msg}" except ffmpeg.Error as e: error_message = e.stderr.decode('utf8') if e.stderr else str(e) return f"Error processing image overlay: {error_message}" except FileNotFoundError: return f"Error: An input file was not found (video: '{video_path}', image: '{image_path}'). Please check paths." except Exception as e: return f"An unexpected error occurred in add_image_overlay: {str(e)}"