MCP Audio Tweaker

Instructions

Implementation Reference

• src/services/advanced-audio-processor.ts:38-82 (handler)

  Core handler function that generates multiple audio file variations by applying randomized pitch shifts, spectral changes, and other effects using FFmpeg.
  async generateVariations( inputFile: string, outputDirectory: string, variations: VariationOperation, baseOperations?: AudioOperations, overwrite: boolean = false ): Promise<ProcessingResult[]> { const results: ProcessingResult[] = []; try { await validateInputFile(inputFile); await ensureOutputDirectory(outputDirectory); const seed = variations.seed || Math.floor(Math.random() * 1000000); const rng = this.createSeededRandom(seed); for (let i = 0; i < variations.count; i++) { const variationOps: AudioOperations = { ...baseOperations, advanced: { ...baseOperations?.advanced, ...this.generateRandomVariation(variations, rng) } }; const outputFile = path.join(outputDirectory, `${path.parse(inputFile).name}_var${i + 1}${path.extname(inputFile)}` ); const result = await this.processAudioFile( inputFile, outputFile, variationOps, overwrite ); results.push(result); } return results; } catch (error) { throw new FFmpegError(`Variation generation failed: ${(error as Error).message}`); } }
• src/tools/index.ts:203-258 (schema)

  Tool definition including input schema for validating parameters like inputFile, outputDirectory, count, pitchRange, etc.
  export const generateVariationsTool: Tool = { name: 'generate_variations', description: 'Generate multiple variations of a sound from a single input - perfect for creating sound families', inputSchema: { type: 'object', properties: { inputFile: { type: 'string', description: 'Path to input audio file' }, outputDirectory: { type: 'string', description: 'Directory for output variations' }, count: { type: 'number', description: 'Number of variations to generate (1-20)', minimum: 1, maximum: 20, default: 5 }, pitchRange: { type: 'number', description: 'Pitch variation range in semitones (±)', minimum: 0, maximum: 12, default: 2 }, volumeRange: { type: 'number', description: 'Volume variation range in dB (±)', minimum: 0, maximum: 10, default: 3 }, spectralRange: { type: 'number', description: 'Spectral variation range in dB (±)', minimum: 0, maximum: 6, default: 2 }, seed: { type: 'number', description: 'Random seed for reproducible variations', optional: true }, overwrite: { type: 'boolean', description: 'Whether to overwrite existing output files', default: false } }, required: ['inputFile', 'outputDirectory'] } };
• src/tools/index.ts:593-623 (registration)

  MCP tool request handler case that dispatches 'generate_variations' calls to the AdvancedAudioProcessor.generateVariations method.
  case 'generate_variations': { const input = args as any; const variations = { count: input.count || 5, pitchRange: input.pitchRange || 2, volumeRange: input.volumeRange || 3, spectralRange: input.spectralRange || 2, seed: input.seed }; const results = await advancedProcessor.generateVariations( input.inputFile, input.outputDirectory, variations, undefined, input.overwrite || false ); return { content: [ { type: 'text', text: JSON.stringify({ success: true, variationsGenerated: results.length, results: results }, null, 2) } ] }; }
• src/tools/index.ts:732-742 (registration)

  Array of all available tools including generateVariationsTool, used for tool listing/discovery.
  export const tools = [ processAudioFileTool, batchProcessAudioTool, applyPresetTool, listPresetsTool, getQueueStatusTool, generateVariationsTool, createHarmonicsTool, advancedProcessTool, layerSoundsTool ];
• src/services/advanced-audio-processor.ts:82-438 (helper)

  Helper method that generates randomized audio effect parameters for each variation based on specified ranges.
  } /** * Layer multiple sounds together with advanced blending */ async layerSounds( inputFiles: string[], outputFile: string, layering: LayeringOperation, overwrite: boolean = false ): Promise<ProcessingResult> { const startTime = Date.now(); try { if (inputFiles.length === 0) { throw new FFmpegError('No input files provided for layering'); } // Validate all input files for (const file of inputFiles) { await validateInputFile(file); } await ensureOutputDirectory(outputFile); await handleExistingOutput(outputFile, overwrite); const command = ffmpeg(); // Add all input files inputFiles.forEach(file => command.input(file)); // Build complex filter for layering const filterGraph = this.buildLayeringFilter(inputFiles, layering); command.complexFilter(filterGraph); // Execute command await executeFFmpegCommand(command, outputFile); return { success: true, inputFile: inputFiles.join(', '), outputFile, processingTime: Date.now() - startTime, operations: { advanced: { layering } } }; } catch (error) { return { success: false, inputFile: inputFiles.join(', '), outputFile, processingTime: Date.now() - startTime, operations: { advanced: { layering } }, error: error instanceof Error ? error.message : 'Unknown error' }; } } /** * Create harmonic variations by adding octaves and intervals */ async createHarmonicVariations( inputFile: string, outputDirectory: string, harmonics: HarmonicsOperation, overwrite: boolean = false ): Promise<ProcessingResult[]> { const results: ProcessingResult[] = []; const baseName = path.parse(inputFile).name; const harmonicIntervals = [ { name: 'octave_up', semitones: 12, mix: harmonics.octaveUp }, { name: 'octave_down', semitones: -12, mix: harmonics.octaveDown }, { name: 'fifth_up', semitones: 7, mix: harmonics.fifthUp }, { name: 'third_up', semitones: 4, mix: harmonics.thirdUp } ]; for (const interval of harmonicIntervals) { if (interval.mix && interval.mix > 0) { const outputFile = path.join(outputDirectory, `${baseName}_${interval.name}${path.extname(inputFile)}` ); const operations: AudioOperations = { advanced: { pitch: { semitones: interval.semitones }, layering: { layers: [ { blend: 'mix', volume: 1 - interval.mix }, { blend: 'add', volume: interval.mix, pitch: interval.semitones } ] } } }; const result = await this.processAudioFile( inputFile, outputFile, operations, overwrite ); results.push(result); } } return results; } /** * Override the base applyOperationsToCommand to include advanced effects */ 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); } } /** * Apply advanced operations to FFmpeg command */ protected applyAdvancedOperations(command: any, advanced: AdvancedEffectsOperation): void { const filters: string[] = []; // Pitch shifting if (advanced.pitch) { filters.push(this.buildPitchFilter(advanced.pitch)); } // Tempo adjustment if (advanced.tempo) { filters.push(this.buildTempoFilter(advanced.tempo)); } // Spectral processing if (advanced.spectral) { const spectralFilter = this.buildSpectralFilter(advanced.spectral); if (spectralFilter) { filters.push(spectralFilter); } } // Dynamics processing if (advanced.dynamics) { filters.push(...this.buildDynamicsFilters(advanced.dynamics)); } // Spatial processing if (advanced.spatial) { filters.push(...this.buildSpatialFilters(advanced.spatial)); } // Modulation effects if (advanced.modulation) { filters.push(...this.buildModulationFilters(advanced.modulation)); } // Apply all filters if (filters.length > 0) { command.audioFilters(filters); } } /** * Build pitch shifting filter */ private buildPitchFilter(pitch: PitchOperation): string { const totalCents = (pitch.semitones * 100) + (pitch.cents || 0); const ratio = Math.pow(2, totalCents / 1200); if (pitch.preserveFormants) { return `asetrate=44100*${ratio},aresample=44100,atempo=${1/ratio}`; } else { return `asetrate=44100*${ratio},aresample=44100`; } } /** * Build tempo adjustment filter */ private buildTempoFilter(tempo: TempoOperation): string { if (tempo.preservePitch) { return `atempo=${tempo.factor}`; } else { return `asetrate=44100*${tempo.factor},aresample=44100`; } } /** * Build spectral processing filter */ private buildSpectralFilter(spectral: SpectralOperation): string { const eqBands: string[] = []; if (spectral.bassBoost !== undefined) { eqBands.push(`bass=g=${spectral.bassBoost}`); } if (spectral.trebleBoost !== undefined) { eqBands.push(`treble=g=${spectral.trebleBoost}`); } if (spectral.midCut !== undefined) { eqBands.push(`equalizer=f=1000:width=500:g=${-Math.abs(spectral.midCut)}`); } if (spectral.warmth !== undefined) { // Add subtle low-mid boost for warmth const warmthGain = spectral.warmth * 3; eqBands.push(`equalizer=f=200:width=100:g=${warmthGain}`); } if (spectral.brightness !== undefined) { // Add high frequency presence const brightnessGain = spectral.brightness * 4; eqBands.push(`equalizer=f=8000:width=2000:g=${brightnessGain}`); } return eqBands.join(','); } /** * Build dynamics processing filters */ private buildDynamicsFilters(dynamics: DynamicsOperation): string[] { const filters: string[] = []; if (dynamics.compressor) { const comp = dynamics.compressor; filters.push( `acompressor=threshold=${comp.threshold}dB:ratio=${comp.ratio}:attack=${comp.attack}:release=${comp.release}${comp.knee ? `:knee=${comp.knee}` : ''}` ); } if (dynamics.gate) { const gate = dynamics.gate; filters.push( `agate=threshold=${gate.threshold}dB:ratio=${gate.ratio}${gate.attack ? `:attack=${gate.attack}` : ''}${gate.release ? `:release=${gate.release}` : ''}` ); } if (dynamics.limiter) { const limiter = dynamics.limiter; filters.push( `alimiter=limit=${limiter.threshold}dB${limiter.release ? `:release=${limiter.release}` : ''}` ); } return filters; } /** * Build spatial processing filters */ private buildSpatialFilters(spatial: SpatialOperation): string[] { const filters: string[] = []; if (spatial.stereoWidth !== undefined) { filters.push(`extrastereo=m=${spatial.stereoWidth}`); } if (spatial.panPosition !== undefined) { filters.push(`pan=stereo|c0=${1 - Math.abs(Math.min(0, spatial.panPosition))}*c0+${Math.max(0, -spatial.panPosition)}*c1|c1=${1 - Math.abs(Math.max(0, spatial.panPosition))}*c1+${Math.max(0, spatial.panPosition)}*c0`); } if (spatial.delayTime !== undefined) { const delaySeconds = spatial.delayTime / 1000; const feedback = spatial.delayFeedback || 0.3; filters.push(`adelay=${spatial.delayTime}|${spatial.delayTime}`); if (feedback > 0) { filters.push(`afeedback=feedback=${feedback}`); } } if (spatial.reverbSend !== undefined) { // Simple reverb using allpass filters filters.push(`aecho=0.8:0.9:${Math.floor(spatial.reverbSend * 1000)}:${spatial.reverbSend}`); } return filters; } /** * Build modulation effect filters */ private buildModulationFilters(modulation: ModulationOperation): string[] { const filters: string[] = []; if (modulation.tremolo) { const trem = modulation.tremolo; filters.push(`tremolo=f=${trem.rate}:d=${trem.depth}`); } if (modulation.vibrato) { const vib = modulation.vibrato; filters.push(`vibrato=f=${vib.rate}:d=${vib.depth}`); } if (modulation.chorus) { const chorus = modulation.chorus; const delayMs = chorus.delay; filters.push(`chorus=0.7:0.9:${delayMs}:0.25:${chorus.rate}:${chorus.depth}:t`); } return filters; } /** * Build layering filter for complex mixing */ private buildLayeringFilter(inputFiles: string[], layering: LayeringOperation): string { const layers = layering.layers; let filterGraph = ''; // Apply individual layer processing layers.forEach((layer, i) => { if (i < inputFiles.length) { let layerFilter = `[${i}:a]`; // Apply layer-specific effects if (layer.delay) { layerFilter += `adelay=${layer.delay}[delayed${i}];[delayed${i}]`; } if (layer.pitch) { const ratio = Math.pow(2, layer.pitch / 12); layerFilter += `asetrate=44100*${ratio},aresample=44100[pitched${i}];[pitched${i}]`; } if (layer.volume !== undefined) { layerFilter += `volume=${layer.volume}[vol${i}];[vol${i}]`; } if (layer.pan !== undefined) { layerFilter += `pan=stereo|c0=${1 - Math.abs(Math.min(0, layer.pan))}*c0+${Math.max(0, -layer.pan)}*c1|c1=${1 - Math.abs(Math.max(0, layer.pan))}*c1+${Math.max(0, layer.pan)}*c0[pan${i}];[pan${i}]`; } filterGraph += layerFilter + `[processed${i}];`; } }); // Mix all layers together const mixInputs = layers.map((_, i) => `[processed${i}]`).join(''); filterGraph += `${mixInputs}amix=inputs=${layers.length}:duration=longest:dropout_transition=2[final]`; return filterGraph; } /** * Generate random variation parameters */ private generateRandomVariation(variations: VariationOperation, rng: () => number): AdvancedEffectsOperation {