batch_process_audio

Process multiple audio files simultaneously by applying operations like normalization, compression, or format conversion to batches in specified directories.

Instructions

Apply audio processing operations to multiple files in a directory

Input Schema

TableJSON Schema

Name	Required	Description	Default
`inputDirectory`	Yes	Directory containing input files
`outputDirectory`	Yes	Directory for processed files
`filePattern`	No	Glob pattern for file matching	*.{mp3,wav,ogg,flac,m4a,aac}
`operations`	Yes	Audio processing operations to apply (same as process_audio_file)
`overwrite`	No	Whether to overwrite existing output files

Implementation Reference

src/tools/index.ts:501-537 (handler)

MCP tool handler for 'batch_process_audio': parses input schema, delegates to AudioProcessor.batchProcessAudio (with fallback to advanced processor), returns JSON result.

case 'batch_process_audio': {
  try {
    const input = BatchProcessAudioInputSchema.parse(args);
    const result = await audioProcessor.batchProcessAudio(
      { directory: input.inputDirectory, pattern: input.filePattern },
      { directory: input.outputDirectory },
      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.batchProcessAudio(
      { directory: (args as any).inputDirectory, pattern: (args as any).filePattern },
      { directory: (args as any).outputDirectory },
      (args as any).operations,
      (args as any).overwrite || false
    );
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2)
        }
      ]
    };
  }
}

src/schemas/validation.ts:128-144 (schema)

Zod input schema for batch_process_audio tool defining inputDirectory, outputDirectory, filePattern, and operations with transformations.

export const BatchProcessAudioInputSchema = z.object({
  inputDirectory: z.string().min(1),
  outputDirectory: z.string().min(1),
  filePattern: z.string().default('*.{mp3,wav,ogg,flac,m4a,aac}').optional(),
  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:89-121 (registration)

Tool registration object for 'batch_process_audio' exported and included in tools list for MCP ListToolsRequest.

 */
export const batchProcessAudioTool: Tool = {
  name: 'batch_process_audio',
  description: 'Apply audio processing operations to multiple files in a directory',
  inputSchema: {
    type: 'object',
    properties: {
      inputDirectory: {
        type: 'string',
        description: 'Directory containing input files'
      },
      outputDirectory: {
        type: 'string',
        description: 'Directory for processed files'
      },
      filePattern: {
        type: 'string',
        description: 'Glob pattern for file matching',
        default: '*.{mp3,wav,ogg,flac,m4a,aac}'
      },
      operations: {
        type: 'object',
        description: 'Audio processing operations to apply (same as process_audio_file)'
      },
      overwrite: {
        type: 'boolean',
        description: 'Whether to overwrite existing output files',
        default: false
      }
    },
    required: ['inputDirectory', 'outputDirectory', 'operations']
  }
};

src/tools/index.ts:732-734 (registration)
Tools array registration including batchProcessAudioTool for MCP server list tools handler.
```
export const tools = [
  processAudioFileTool,
  batchProcessAudioTool,
```

src/services/base-audio-processor.ts:84-133 (helper)

Core batchProcessAudio implementation in BaseAudioProcessor: discovers files, queues concurrent FFmpeg processing with operations, handles output paths and errors.

async batchProcessAudio(
  input: ProcessingInput,
  output: ProcessingOutput,
  operations: AudioOperations,
  overwrite: boolean = false
): Promise<BatchProcessingResult> {
  const startTime = Date.now();
  
  try {
    // Find input files
    const inputFiles = await this.findInputFiles(input);
    
    if (inputFiles.length === 0) {
      throw new FFmpegError('No audio files found matching the criteria');
    }
    
    logger.info(`Found ${inputFiles.length} files to process`);
    
    // Process files with concurrency control via PQueue
    const processingPromises = inputFiles.map((inputFile) =>
      this.queue.add(async () => {
        const outputFile = this.generateBatchOutputPath(inputFile, input, output);
        // Create a new command for each file
        const command = createFFmpegCommand(inputFile);
        // Apply operations
        this.applyOperationsToCommand(command, operations);
        // Execute command
        return this.processAudioFile(inputFile, outputFile, operations, overwrite);
      })
    );

    const allResults = await Promise.all(processingPromises);
    const results: ProcessingResult[] = allResults.filter((r): r is ProcessingResult => !!r);
    
    const totalProcessingTime = Date.now() - startTime;
    const successfulFiles = results.filter(r => r.success).length;
    const failedFiles = results.length - successfulFiles;
    
    return {
      totalFiles: results.length,
      successfulFiles,
      failedFiles,
      results,
      totalProcessingTime
    };
    
  } catch (error) {
    throw new FFmpegError(`Batch processing failed: ${(error as Error).message}`);
  }
}

MCP Audio Tweaker