create_video_config

Instructions

Implementation Reference

• src/index.ts:577-638 (handler)

  The main handler for 'create_video_config'. Builds a video config object from arguments (width, height, fps, format, clips) and optional properties (fast, audioFilePath, loopAudio, outputVolume, keepSourceAudio, clipsAudioVolume, audioTracks, audioNorm, defaults). Returns the config wrapped in { type: 'video', config }.

  private async handleCreateVideoConfig(args: any) {
    const config: any = {
      width: args.width || 1280,
      height: args.height || 720,
      fps: args.fps || 25,
      format: args.format || 'mp4',
      clips: args.clips || [],
    };
  
    // Optional properties
    if (args.fast !== undefined) {
      config.fast = args.fast;
    }
  
    // Background audio
    if (args.audioFilePath) {
      config.audioFilePath = args.audioFilePath;
    }
    if (args.loopAudio !== undefined) {
      config.loopAudio = args.loopAudio;
    }
    if (args.outputVolume !== undefined) {
      config.outputVolume = args.outputVolume;
    }
    if (args.keepSourceAudio !== undefined) {
      config.keepSourceAudio = args.keepSourceAudio;
    }
    if (args.clipsAudioVolume !== undefined) {
      config.clipsAudioVolume = args.clipsAudioVolume;
    }
  
    // Audio tracks
    if (args.audioTracks && args.audioTracks.length > 0) {
      config.audioTracks = args.audioTracks;
    }
  
    // Audio normalization
    if (args.audioNorm) {
      config.audioNorm = args.audioNorm;
    }
  
    // Defaults
    if (args.defaults) {
      config.defaults = args.defaults;
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              type: 'video',
              config,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/index.ts:262-425 (schema)

  Tool registration and input schema for 'create_video_config' in the stdio server (src/index.ts). Defines the full description, workflow instructions, layer types, and detailed inputSchema with all properties (width, height, fps, format, fast, audioFilePath, loopAudio, outputVolume, keepSourceAudio, clipsAudioVolume, audioTracks, audioNorm, defaults, clips).

            name: 'create_video_config',
            description: `Create a JSON configuration for video generation based on jsoncut documentation.
            
  Returns a complete configuration object that can be used with the validate_config tool or submitted directly to the jsoncut API.
  
  **WORKFLOW:** 
  1. First get the schema (read resource schema://video or call get_video_schema) to understand all available options
  2. Create the configuration with this tool
  3. Call validate_config to verify the configuration (if user provided media file paths)
  
  **Video Structure:**
  - Built using clips (segments) that play sequentially
  - Each clip contains layers (rendered bottom to top)
  - Supports transitions between clips
  - Comprehensive audio system with multiple options
  
  **Layer Types:**
  - video: Display video files with timing control, Ken Burns effects, and enhanced positioning
  - image: Static images with positioning and Ken Burns effects
  - image-overlay: Images positioned over other content with timing
  - title: Large headline text with animation styles (fade-in, word-by-word, letter-by-letter) and enhanced positioning
  - subtitle: Smaller text for captions
  - news-title: Breaking news style with colored backgrounds
  - title-background: Titles with full-screen backgrounds
  - slide-in-text: Animated text that slides in
  - audio: Audio tracks tied to clips (requires keepSourceAudio: true)
  - detached-audio: Audio with clip-relative timing
  - fill-color: Solid color backgrounds
  - linear-gradient: Linear gradient backgrounds
  - radial-gradient: Radial gradient backgrounds
  - rainbow-colors: Animated rainbow effects
  - pause: Black screen pauses
  
  **Audio Options:**
  - audioFilePath + loopAudio: Background music throughout video
  - audioTracks: Multiple audio tracks with independent timing
  - audioNorm: Audio normalization with ducking
  - keepSourceAudio: Keep audio from video layers
  - Audio layers within clips
  
  **Video & title layer Positioning:**
  - Position objects: { x: 0-1, y: 0-1, originX: left|center|right, originY: top|center|bottom }
  - Position strings: center, top, bottom, top-left, top-right, center-left, center-right, bottom-left, bottom-right
  - Video layers support both position objects and strings
  - Title layers support enhanced positioning with position objects
  
  **Title Layer Animation Styles:**
  - fade-in: Smooth fade-in effect (default)
  - word-by-word: Words appear sequentially
  - letter-by-letter: Letters appear sequentially
  - Zoom effects automatically disabled for word-by-word and letter-by-letter styles
  
  **Transitions:** 75+ transition effects including fade, wipe, circle, cube, glitch, zoom, etc.
  
  File paths should be placeholders like "/input/userXXX/filename.ext".`,
            inputSchema: {
              type: 'object',
              properties: {
                width: {
                  type: 'number',
                  description: 'Width in pixels (default: 1280)',
                  default: 1280,
                },
                height: {
                  type: 'number',
                  description: 'Height in pixels (default: 720)',
                  default: 720,
                },
                fps: {
                  type: 'number',
                  description: 'Frames per second (24, 25, 30, 50, 60, 120)',
                  default: 25,
                  enum: [24, 25, 30, 50, 60, 120]
                },
                format: {
                  type: 'string',
                  description: 'Output format: mp4 or mov',
                  enum: ['mp4', 'mov'],
                  default: 'mp4',
                },
                fast: {
                  type: 'boolean',
                  description: 'Enable fast processing mode (for preview)',
                  default: false
                },
                audioFilePath: {
                  type: 'string',
                  description: 'Path to background audio file (plays throughout video)',
                },
                loopAudio: {
                  type: 'boolean',
                  description: 'Loop background audio if shorter than video',
                  default: false
                },
                outputVolume: {
                  type: 'number',
                  description: 'Final output volume (0-1)',
                  default: 1
                },
                keepSourceAudio: {
                  type: 'boolean',
                  description: 'Keep audio from video layers (required for audio layers)',
                  default: false
                },
                clipsAudioVolume: {
                  type: 'number',
                  description: 'Volume for audio from clips relative to tracks (0-1)',
                  default: 1
                },
                audioTracks: {
                  type: 'array',
                  description: 'Multiple audio tracks with independent timing',
                  items: {
                    type: 'object',
                    properties: {
                      path: { type: 'string', description: 'Audio file path' },
                      mixVolume: { type: 'number', description: 'Relative volume (0-1)', default: 1 },
                      start: { type: 'number', description: 'Start time in video (seconds)', default: 0 },
                      cutFrom: { type: 'number', description: 'Cut from in audio file (seconds)', default: 0 },
                      cutTo: { type: 'number', description: 'Cut to in audio file (seconds)' }
                    }
                  },
                },
                audioNorm: {
                  type: 'object',
                  description: 'Audio normalization with ducking',
                  properties: {
                    enable: { type: 'boolean', default: false },
                    gaussSize: { type: 'number', description: 'Gaussian filter size (1-10)', default: 5 },
                    maxGain: { type: 'number', description: 'Max gain in dB', default: 30 }
                  }
                },
                defaults: {
                  type: 'object',
                  description: 'Default properties for clips and layers',
                  properties: {
                    duration: { type: 'number', description: 'Default clip duration' },
                    transition: { type: 'object', description: 'Default transition' },
                    layer: { type: 'object', description: 'Default layer properties' },
                    layerType: { type: 'object', description: 'Defaults per layer type' }
                  }
                },
                clips: {
                  type: 'array',
                  description: 'Array of clip objects. Each clip has layers and optional duration/transition.',
                  items: {
                    type: 'object',
                    properties: {
                      duration: { type: 'number', description: 'Clip duration in seconds' },
                      layers: { type: 'array', description: 'Array of layer objects' },
                      transition: { 
                        type: 'object', 
                        description: 'Transition to next clip',
                        properties: {
                          name: { type: 'string', description: 'Transition name (fade, wipe, etc.)' },
                          duration: { type: 'number', description: 'Transition duration in seconds' }
                        }
                      }
                    }
                  },
                },
              },
              required: ['clips'],
            },

• src/index.ts:506-507 (registration)

  Routing in the CallToolRequestSchema handler that dispatches 'create_video_config' to handleCreateVideoConfig.

  case 'create_video_config':
    return await this.handleCreateVideoConfig(args);

• src/http-server.ts:308-317 (handler)

  The handler for 'create_video_config' in the HTTP server variant. Simpler implementation that just returns args as JSON (echo/proxy mode).

  private handleCreateVideoConfig(args: any) {
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(args, null, 2),
        },
      ],
    };
  }

• src/http-server.ts:183-207 (registration)

  Tool registration and input schema for 'create_video_config' in the HTTP server. Has simpler description and schema with fewer properties (width, height, fps, clips).

  name: 'create_video_config',
  description:
    'Create a JSON configuration for video generation. Returns a complete video config that can be sent to the Jsoncut API. Supports clips, multiple layer types, transitions, and audio.',
  inputSchema: {
    type: 'object',
    properties: {
      width: {
        type: 'number',
        description: 'Video width in pixels',
      },
      height: {
        type: 'number',
        description: 'Video height in pixels',
      },
      fps: {
        type: 'number',
        description: 'Frames per second',
      },
      clips: {
        type: 'array',
        description: 'Array of video clips',
      },
    },
    required: ['width', 'height', 'clips'],
  },

• src/http-server.ts:261-262 (registration)

  Routing in the CallToolRequestSchema handler dispatching 'create_video_config' to handleCreateVideoConfig in the HTTP server.

  case 'create_video_config':
    return this.handleCreateVideoConfig(args);