MCP FFmpeg Video Processor

Instructions

Implementation Reference

• src/mcp-ffmpeg.ts:249-356 (handler)

  The handler function for the 'extract-audio' tool. It resolves paths, checks file existence and permissions, requests user permission, determines audio codec based on format, executes FFmpeg command to extract audio without video (-vn -acodec), and returns success or error response.

  async ({ videoPath, format, outputDir }) => {
    try {
      // Resolve the absolute path
      const absVideoPath = path.resolve(videoPath);
  
      // Check if file exists
      try {
        await fs.access(absVideoPath);
      } catch (error) {
        return {
          isError: true,
          content: [{
            type: "text" as const,
            text: `Error: Video file not found at ${absVideoPath}`
          }]
        };
      }
  
      // Determine output directory
      let outputDirectory = outputDir ? path.resolve(outputDir) : await ensureDirectoriesExist();
  
      // Check if output directory exists and is writable
      try {
        await fs.access(outputDirectory, fs.constants.W_OK);
      } catch (error) {
        return {
          isError: true,
          content: [{
            type: "text" as const,
            text: `Error: Output directory ${outputDirectory} does not exist or is not writable`
          }]
        };
      }
  
      // Format command for permission request
      const permissionMessage = `Extract ${format} audio from video ${path.basename(absVideoPath)}`;
  
      // Ask for permission
      const permitted = await askPermission(permissionMessage);
  
      if (!permitted) {
        return {
          isError: true,
          content: [{
            type: "text" as const,
            text: "Permission denied by user"
          }]
        };
      }
  
      // Get video filename without extension
      const videoFilename = path.basename(absVideoPath, path.extname(absVideoPath));
      const outputFilename = `${videoFilename}.${format}`;
      const outputPath = path.join(outputDirectory, outputFilename);
  
      // Determine audio codec based on format
      let audioCodec;
      switch (format) {
        case 'mp3':
          audioCodec = 'libmp3lame';
          break;
        case 'aac':
          audioCodec = 'aac';
          break;
        case 'wav':
          audioCodec = 'pcm_s16le';
          break;
        case 'ogg':
          audioCodec = 'libvorbis';
          break;
        default:
          audioCodec = 'libmp3lame';
      }
  
      // Build FFmpeg command
      const command = `ffmpeg -i "${absVideoPath}" -vn -acodec ${audioCodec} "${outputPath}"`;
  
      try {
        // Execute FFmpeg command
        const { stdout, stderr } = await execAsync(command);
  
        return {
          content: [{
            type: "text" as const,
            text: `Successfully extracted audio to: ${outputPath}`
          }]
        };
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          isError: true,
          content: [{
            type: "text" as const,
            text: `Error extracting audio: ${errorMessage}`
          }]
        };
      }
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        isError: true,
        content: [{
          type: "text" as const,
          text: `Error extracting audio: ${errorMessage}`
        }]
      };
    }
  }

• src/mcp-ffmpeg.ts:244-248 (schema)

  Input schema using Zod for the 'extract-audio' tool, defining videoPath (required string), format (enum mp3|aac|wav|ogg, default mp3), outputDir (optional string).

  {
    videoPath: z.string().describe("Path to the video file to extract audio from"),
    format: z.enum(["mp3", "aac", "wav", "ogg"]).default("mp3").describe("Audio format to extract"),
    outputDir: z.string().optional().describe("Optional directory to save the output file (defaults to a temporary directory)")
  },

• src/mcp-ffmpeg.ts:241-357 (registration)

  Registration of the 'extract-audio' tool on the MCP server using server.tool(), specifying name, description, input schema, and handler function.

  server.tool(
    "extract-audio",
    "Extract audio from a video file",
    {
      videoPath: z.string().describe("Path to the video file to extract audio from"),
      format: z.enum(["mp3", "aac", "wav", "ogg"]).default("mp3").describe("Audio format to extract"),
      outputDir: z.string().optional().describe("Optional directory to save the output file (defaults to a temporary directory)")
    },
    async ({ videoPath, format, outputDir }) => {
      try {
        // Resolve the absolute path
        const absVideoPath = path.resolve(videoPath);
  
        // Check if file exists
        try {
          await fs.access(absVideoPath);
        } catch (error) {
          return {
            isError: true,
            content: [{
              type: "text" as const,
              text: `Error: Video file not found at ${absVideoPath}`
            }]
          };
        }
  
        // Determine output directory
        let outputDirectory = outputDir ? path.resolve(outputDir) : await ensureDirectoriesExist();
  
        // Check if output directory exists and is writable
        try {
          await fs.access(outputDirectory, fs.constants.W_OK);
        } catch (error) {
          return {
            isError: true,
            content: [{
              type: "text" as const,
              text: `Error: Output directory ${outputDirectory} does not exist or is not writable`
            }]
          };
        }
  
        // Format command for permission request
        const permissionMessage = `Extract ${format} audio from video ${path.basename(absVideoPath)}`;
  
        // Ask for permission
        const permitted = await askPermission(permissionMessage);
  
        if (!permitted) {
          return {
            isError: true,
            content: [{
              type: "text" as const,
              text: "Permission denied by user"
            }]
          };
        }
  
        // Get video filename without extension
        const videoFilename = path.basename(absVideoPath, path.extname(absVideoPath));
        const outputFilename = `${videoFilename}.${format}`;
        const outputPath = path.join(outputDirectory, outputFilename);
  
        // Determine audio codec based on format
        let audioCodec;
        switch (format) {
          case 'mp3':
            audioCodec = 'libmp3lame';
            break;
          case 'aac':
            audioCodec = 'aac';
            break;
          case 'wav':
            audioCodec = 'pcm_s16le';
            break;
          case 'ogg':
            audioCodec = 'libvorbis';
            break;
          default:
            audioCodec = 'libmp3lame';
        }
  
        // Build FFmpeg command
        const command = `ffmpeg -i "${absVideoPath}" -vn -acodec ${audioCodec} "${outputPath}"`;
  
        try {
          // Execute FFmpeg command
          const { stdout, stderr } = await execAsync(command);
  
          return {
            content: [{
              type: "text" as const,
              text: `Successfully extracted audio to: ${outputPath}`
            }]
          };
        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          return {
            isError: true,
            content: [{
              type: "text" as const,
              text: `Error extracting audio: ${errorMessage}`
            }]
          };
        }
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        return {
          isError: true,
          content: [{
            type: "text" as const,
            text: `Error extracting audio: ${errorMessage}`
          }]
        };
      }
    }
  );

• src/mcp-ffmpeg.ts:30-56 (helper)

  Helper function to request user permission via desktop notification before executing FFmpeg operations, used by extract-audio handler.

  async function askPermission(action: string): Promise<boolean> {
    // Skip notification if DISABLE_NOTIFICATIONS is set
    if (process.env.DISABLE_NOTIFICATIONS === 'true') {
      console.log(`Auto-allowing action (notifications disabled): ${action}`);
      return true;
    }
  
    return new Promise((resolve) => {
      notifier.notify({
        title: 'FFmpeg Processor Permission Request',
        message: `${action}`,
        wait: true,
        timeout: 60,
        actions: 'Allow',
        closeLabel: 'Deny'
      }, (err, response, metadata) => {
        if (err) {
          console.error('Error showing notification:', err);
          resolve(false);
          return;
        }
  
        const buttonPressed = metadata?.activationValue || response;
        resolve(buttonPressed !== 'Deny');
      });
    });
  }

• src/mcp-ffmpeg.ts:61-70 (helper)

  Helper function to ensure output directory exists in temp folder, used by extract-audio to determine output path.

  async function ensureDirectoriesExist() {
    const outputDir = path.join(os.tmpdir(), 'ffmpeg-output');
    try {
      await fs.mkdir(outputDir, { recursive: true });
      return outputDir;
    } catch (error) {
      console.error('Error creating output directory:', error);
      return os.tmpdir();
    }
  }