layer_sounds

Instructions

Implementation Reference

• src/services/advanced-audio-processor.ts:87-138 (handler)

  Core handler function implementing the layer_sounds tool logic using FFmpeg to layer multiple audio files with blending, timing, pitch, volume, and pan controls.

  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'
      };
    }
  }

• src/tools/index.ts:411-451 (schema)

  Tool metadata and input schema definition for validating parameters of the layer_sounds tool.

  export const layerSoundsTool: Tool = {
    name: 'layer_sounds',
    description: 'Layer multiple sounds together with advanced blending and timing',
    inputSchema: {
      type: 'object',
      properties: {
        inputFiles: {
          type: 'array',
          description: 'Array of input file paths to layer',
          items: { type: 'string' },
          minItems: 1,
          maxItems: 8
        },
        outputFile: {
          type: 'string',
          description: 'Path for output file'
        },
        layers: {
          type: 'array',
          description: 'Layer configuration for each input',
          items: {
            type: 'object',
            properties: {
              blend: { type: 'string', enum: ['mix', 'multiply', 'add', 'subtract'] },
              delay: { type: 'number', minimum: 0, maximum: 5000 },
              pitch: { type: 'number', minimum: -12, maximum: 12 },
              volume: { type: 'number', minimum: 0, maximum: 2 },
              pan: { type: 'number', minimum: -1, maximum: 1 }
            },
            required: ['blend']
          }
        },
        overwrite: {
          type: 'boolean',
          description: 'Whether to overwrite existing output files',
          default: false
        }
      },
      required: ['inputFiles', 'outputFile', 'layers']
    }
  };

• src/tools/index.ts:684-705 (registration)

  Registration and dispatch logic within the unified tool handler that routes layer_sounds calls to the AdvancedAudioProcessor.

  case 'layer_sounds': {
    const input = args as any;
    const layering = {
      layers: input.layers
    };
    
    const result = await advancedProcessor.layerSounds(
      input.inputFiles,
      input.outputFile,
      layering,
      input.overwrite || false
    );
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2)
        }
      ]
    };
  }

• src/services/advanced-audio-processor.ts:396-433 (helper)

  Supporting utility that generates the complex FFmpeg filter graph string for multi-layer audio blending with per-layer effects.

  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;
  }

• src/tools/index.ts:732-742 (registration)

  The tools export array includes layerSoundsTool for server registration.

  export const tools = [
    processAudioFileTool,
    batchProcessAudioTool,
    applyPresetTool,
    listPresetsTool,
    getQueueStatusTool,
    generateVariationsTool,
    createHarmonicsTool,
    advancedProcessTool,
    layerSoundsTool
  ];