MCP FFmpeg Helper

Instructions

Implementation Reference

• src/tools/handlers.ts:149-186 (handler)

  The handler function for the 'trim_audio' tool. It processes input arguments, builds an FFmpeg command to trim the audio file based on start time, duration or end time, optionally re-encodes with a specified format or copies the codec, ensures output directory exists, executes the command, and returns a success message with FFmpeg output.

  case "trim_audio": {
    const inputPath = validatePath(String(args?.inputPath), true);
    const outputPath = validatePath(String(args?.outputPath));
    const startTime = String(args?.startTime || "0");
    const duration = String(args?.duration || "");
    const endTime = String(args?.endTime || "");
    const format = String(args?.format || "");
    
    await ensureDirectoryExists(outputPath);
    
    // Build the FFmpeg command
    let command = `-i "${inputPath}" -ss ${startTime}`;
    
    // Add duration or end time if provided
    if (duration) {
      command += ` -t ${duration}`;
    } else if (endTime) {
      command += ` -to ${endTime}`;
    }
    
    // Add format if specified, otherwise use copy codec
    if (format) {
      command += ` -acodec ${format}`;
    } else {
      command += ` -acodec copy`;
    }
    
    command += ` "${outputPath}" -y`;
    
    const result = await runFFmpegCommand(command);
    
    return {
      content: [{
        type: "text",
        text: `Audio trimming completed: ${inputPath} → ${outputPath}\n\n${result}`
      }]
    };
  }

• src/tools/definitions.ts:158-191 (schema)

  The input schema and metadata definition for the 'trim_audio' tool, specifying required and optional parameters with descriptions.

  {
    name: "trim_audio",
    description: "Trim an audio file to a specific duration",
    inputSchema: {
      type: "object",
      properties: {
        inputPath: {
          type: "string",
          description: "Path to the input audio file"
        },
        outputPath: {
          type: "string",
          description: "Path for the output audio file"
        },
        startTime: {
          type: "string",
          description: "Start time (format: HH:MM:SS.mmm or seconds)"
        },
        duration: {
          type: "string",
          description: "Duration (format: HH:MM:SS.mmm or seconds)"
        },
        endTime: {
          type: "string",
          description: "End time (format: HH:MM:SS.mmm or seconds)"
        },
        format: {
          type: "string",
          description: "Audio format for output (mp3, aac, etc.)"
        }
      },
      required: ["inputPath", "outputPath"]
    }
  },

• src/index.ts:46-50 (registration)

  Registers the 'trim_audio' tool (along with others) by providing the toolDefinitions array in response to ListTools requests.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: toolDefinitions
    };
  });

• src/index.ts:56-68 (registration)

  Registers the handleToolCall dispatcher which routes 'trim_audio' calls to its specific handler implementation.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      return await handleToolCall(request.params.name, request.params.arguments);
    } catch (error: any) {
      console.error("Tool execution error:", error.message);
      return {
        content: [{
          type: "text",
          text: `Error: ${error.message}`
        }]
      };
    }
  });