MCP Audio Tweaker

Instructions

Implementation Reference

• src/tools/index.ts:463-499 (handler)

  Main execution handler for the 'process_audio_file' tool. Parses input using Zod schema, attempts basic processor, falls back to advanced processor if validation fails, and returns JSON result.

  case 'process_audio_file': {
    try {
      const input = ProcessAudioFileInputSchema.parse(args);
      const result = await audioProcessor.processAudioFile(
        input.inputFile,
        input.outputFile,
        input.operations,
        (args as any).overwrite || false
      );
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (validationError) {
      // If validation fails, try with the advanced processor
      const result = await advancedProcessor.processAudioFile(
        (args as any).inputFile,
        (args as any).outputFile,
        (args as any).operations,
        (args as any).overwrite || false
      );
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    }
  }

• src/schemas/validation.ts:111-126 (schema)

  Zod validation schema for process_audio_file inputs, including file paths, operations for volume, format, and effects.

  export const ProcessAudioFileInputSchema = z.object({
    inputFile: FilePathSchema,
    outputFile: z.string().min(1),
    operations: AudioOperationsSchema
  }).transform((data) => {
    // Transform string values to numbers for format operations
    if (data.operations.format) {
      if (data.operations.format.sampleRate && typeof data.operations.format.sampleRate === 'string') {
        data.operations.format.sampleRate = parseInt(data.operations.format.sampleRate) as any;
      }
      if (data.operations.format.channels && typeof data.operations.format.channels === 'string') {
        data.operations.format.channels = parseInt(data.operations.format.channels) as any;
      }
    }
    return data;
  });

• src/tools/index.ts:19-85 (registration)

  MCP Tool registration object defining name, description, and JSON input schema for 'process_audio_file'.

  export const processAudioFileTool: Tool = {
    name: 'process_audio_file',
    description: 'Apply audio processing operations to a single file using FFmpeg',
    inputSchema: {
      type: 'object',
      properties: {
        inputFile: {
          type: 'string',
          description: 'Path to input audio file'
        },
        outputFile: {
          type: 'string',
          description: 'Path for output file'
        },
        operations: {
          type: 'object',
          description: 'Audio processing operations to apply',
          properties: {
            volume: {
              type: 'object',
              properties: {
                adjust: { type: 'number', minimum: -60, maximum: 20 },
                normalize: { type: 'boolean' },
                targetLUFS: { type: 'number' }
              }
            },
            format: {
              type: 'object',
              properties: {
                sampleRate: { type: 'number', enum: [8000, 16000, 22050, 44100, 48000, 96000, 192000] },
                bitrate: { type: 'number', minimum: 64, maximum: 320 },
                channels: { type: 'number', enum: [1, 2, 6, 8] },
                codec: { type: 'string', enum: ['pcm', 'mp3', 'aac', 'vorbis', 'flac'] }
              }
            },
            effects: {
              type: 'object',
              properties: {
                fadeIn: { type: 'number', minimum: 0 },
                fadeOut: { type: 'number', minimum: 0 },
                trim: {
                  type: 'object',
                  properties: {
                    start: { type: 'number', minimum: 0 },
                    end: { type: 'number', minimum: 0 }
                  }
                },
                loop: {
                  type: 'object',
                  properties: {
                    enabled: { type: 'boolean' },
                    count: { type: 'number', minimum: 1 }
                  }
                }
              }
            }
          }
        },
        overwrite: {
          type: 'boolean',
          description: 'Whether to overwrite existing output files',
          default: false
        }
      },
      required: ['inputFile', 'outputFile', 'operations']
    }
  };

• src/services/base-audio-processor.ts:34-79 (helper)

  Base implementation of processAudioFile method that validates inputs, builds FFmpeg command with operations, executes processing, and returns result. Used by both basic and advanced processors.

  async processAudioFile(
    inputFile: string,
    outputFile: string,
    operations: AudioOperations,
    overwrite: boolean = false
  ): Promise<ProcessingResult> {
    const startTime = Date.now();
    
    try {
      // Validate input
      await validateInputFile(inputFile);
      await ensureOutputDirectory(outputFile);
      await handleExistingOutput(outputFile, overwrite);
      
      // Create FFmpeg command
      const command = createFFmpegCommand(inputFile);
      
      // Apply operations
      this.applyOperationsToCommand(command, operations);
      
      // Execute command
      await executeFFmpegCommand(command, outputFile);
      
      const processingTime = Date.now() - startTime;
      
      return {
        success: true,
        inputFile,
        outputFile,
        processingTime,
        operations
      };
      
    } catch (error) {
      const processingTime = Date.now() - startTime;
      
      return {
        success: false,
        inputFile,
        outputFile,
        processingTime,
        operations,
        error: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }

• src/services/advanced-audio-processor.ts:194-202 (helper)

  Overridden applyOperationsToCommand in advanced processor that adds support for advanced effects like pitch, tempo, spectral, dynamics, and spatial processing beyond base capabilities.

  protected applyOperationsToCommand(command: any, operations: AudioOperations): void {
    // Apply base operations first (volume, format, basic effects)
    super.applyOperationsToCommand(command, operations);
    
    // Apply advanced operations
    if (operations.advanced) {
      this.applyAdvancedOperations(command, operations.advanced);
    }
  }