Video & Audio Editing MCP Server

Instructions

Implementation Reference

• server.py:1573-1646 (handler)

  The handler function implementing the 'add_basic_transitions' tool. It uses FFmpeg's 'fade' filter to apply fade-in or fade-out transitions to the video, with audio stream copying or re-encoding as fallback. Includes input validation and error handling. Automatically registered via @mcp.tool() decorator, with schema derived from type hints and docstring.

  @mcp.tool()
  def add_basic_transitions(video_path: str, output_video_path: str, transition_type: str, duration_seconds: float) -> str:
      """Adds basic fade transitions to the beginning or end of a video.
  
      Args:
          video_path: Path to the input video file.
          output_video_path: Path to save the video with the transition.
          transition_type: Type of transition. Options: 'fade_in', 'fade_out'.
                           (Note: 'crossfade_from_black' is like 'fade_in', 'crossfade_to_black' is like 'fade_out')
          duration_seconds: Duration of the fade effect in seconds.
      Returns:
          A status message indicating success or failure.
      """
      if not os.path.exists(video_path):
          return f"Error: Input video file not found at {video_path}"
      if duration_seconds <= 0:
          return "Error: Transition duration must be positive."
  
      try:
          props = _get_media_properties(video_path)
          video_total_duration = props['duration']
  
          if duration_seconds > video_total_duration:
              return f"Error: Transition duration ({duration_seconds}s) cannot exceed video duration ({video_total_duration}s)."
  
          input_stream = ffmpeg.input(video_path)
          video_stream = input_stream.video
          audio_stream = input_stream.audio
          
          processed_video = None
  
          if transition_type == 'fade_in' or transition_type == 'crossfade_from_black':
              processed_video = video_stream.filter('fade', type='in', start_time=0, duration=duration_seconds)
          elif transition_type == 'fade_out' or transition_type == 'crossfade_to_black':
              fade_start_time = video_total_duration - duration_seconds
              processed_video = video_stream.filter('fade', type='out', start_time=fade_start_time, duration=duration_seconds)
          else:
              return f"Error: Unsupported transition_type '{transition_type}'. Supported: 'fade_in', 'fade_out'."
  
          # Attempt to copy audio, fallback to re-encoding if necessary
          output_streams = []
          if props['has_video']:
              output_streams.append(processed_video)
          if props['has_audio']:
              output_streams.append(audio_stream) # Audio is passed through without fade
          else: # Video only
              pass
          
          if not output_streams:
              return "Error: No suitable video or audio streams found to apply transition."
  
          try:
              ffmpeg.output(*output_streams, output_video_path, acodec='copy').run(capture_stdout=True, capture_stderr=True)
              return f"Transition '{transition_type}' applied successfully (audio copied). Output: {output_video_path}"
          except ffmpeg.Error as e_acopy:
              # Fallback: re-encode audio (or just output video if no audio originally)
              try:
                  ffmpeg.output(*output_streams, output_video_path).run(capture_stdout=True, capture_stderr=True)
                  return f"Transition '{transition_type}' applied successfully (audio re-encoded/processed). Output: {output_video_path}"
              except ffmpeg.Error as e_recode:
                  err_acopy = e_acopy.stderr.decode('utf8') if e_acopy.stderr else str(e_acopy)
                  err_recode = e_recode.stderr.decode('utf8') if e_recode.stderr else str(e_recode)
                  return f"Error applying transition. Audio copy failed: {err_acopy}. Full re-encode failed: {err_recode}."
  
      except ffmpeg.Error as e:
          error_message = e.stderr.decode('utf8') if e.stderr else str(e)
          return f"Error applying basic transition: {error_message}"
      except ValueError as e: # For _parse_time or duration checks
          return f"Error with input values: {str(e)}"
      except RuntimeError as e: # For _get_media_properties error
          return f"Runtime error during transition processing: {str(e)}"
      except Exception as e:
          return f"An unexpected error occurred in add_basic_transitions: {str(e)}"

• server.py:1237-1269 (helper)

  Helper function called by add_basic_transitions to retrieve media properties such as duration, used to validate that transition duration does not exceed video length.

  def _get_media_properties(media_path: str) -> dict:
      """Probes media file and returns key properties."""
      try:
          probe = ffmpeg.probe(media_path)
          video_stream_info = next((s for s in probe['streams'] if s['codec_type'] == 'video'), None)
          audio_stream_info = next((s for s in probe['streams'] if s['codec_type'] == 'audio'), None)
          
          props = {
              'duration': float(probe['format'].get('duration', 0.0)),
              'has_video': video_stream_info is not None,
              'has_audio': audio_stream_info is not None,
              'width': int(video_stream_info['width']) if video_stream_info and 'width' in video_stream_info else 0,
              'height': int(video_stream_info['height']) if video_stream_info and 'height' in video_stream_info else 0,
              'avg_fps': 0, # Default, will be calculated if possible
              'sample_rate': int(audio_stream_info['sample_rate']) if audio_stream_info and 'sample_rate' in audio_stream_info else 44100,
              'channels': int(audio_stream_info['channels']) if audio_stream_info and 'channels' in audio_stream_info else 2,
              'channel_layout': audio_stream_info.get('channel_layout', 'stereo') if audio_stream_info else 'stereo'
          }
          if video_stream_info and 'avg_frame_rate' in video_stream_info and video_stream_info['avg_frame_rate'] != '0/0':
              num, den = map(int, video_stream_info['avg_frame_rate'].split('/'))
              if den > 0:
                  props['avg_fps'] = num / den
              else:
                  props['avg_fps'] = 30 # Default if denominator is 0
          else: # Fallback if avg_frame_rate is not useful
              props['avg_fps'] = 30 # A common default
  
          return props
      except ffmpeg.Error as e:
          raise RuntimeError(f"Error probing file {media_path}: {e.stderr.decode('utf8') if e.stderr else str(e)}")
      except Exception as e:
          raise RuntimeError(f"Unexpected error probing file {media_path}: {str(e)}")