← Back to Server

📋FFmpeg Video Server

Config.json Documentation & Reference Guide

Overview File Structure Project Section Media Section Effects & Filters Examples Validation Best Practices

📚Table of Contents

📋Overview

The config.json file defines how your media files will be processed and assembled into a final video. This configuration-driven approach allows for flexible video composition, supporting multiple media types, transitions, and processing options.

Purpose

The config.json file serves as the blueprint for video assembly, specifying:

  • Project metadata and settings
  • Media file order and timing
  • Transitions between clips
  • Output video specifications
  • Processing parameters

📁File Structure

Basic Structure

{
  "project": {
    "name": "string",
    "description": "string",
    "event_type": "string",
    "output_settings": { }
  },
  "media": [
    {
      "file": "string",
      "type": "string",
      "duration": number,
      "transition": "string",
      "effects": { }
    }
  ],
  "global_settings": { },
  "metadata": { }
}

🎬Project Section

The project section contains overall project information and output settings.

Required Fields

Field Type Description Example
name Required string Project name for identification "Soccer Highlights 2024"

Optional Fields

Field Type Description Default Example
description string Project description "" "Championship game highlights"
event_type string Type of event being processed "custom" "sports", "wedding", "graduation"
created_at string ISO timestamp of creation auto "2024-01-15T10:30:00Z"

Output Settings

"output_settings": {
  "resolution": "1920x1080",
  "framerate": 30,
  "quality": "high",
  "format": "mp4",
  "audio_bitrate": "128k",
  "video_codec": "libx264",
  "audio_codec": "aac"
}
Field Type Options Default Description
resolution string "1920x1080", "1280x720", "3840x2160" "1920x1080" Output video resolution
framerate number 24, 30, 60 30 Frames per second
quality string "low", "medium", "high", "ultra" "high" Video quality preset

🎥Media Section

The media array defines the sequence of media files and how they should be processed.

Media Object Structure

{
  "file": "video1.mp4",
  "type": "video",
  "duration": 10.5,
  "start_time": 5.0,
  "end_time": 15.5,
  "transition": "dissolve",
  "effects": {
    "volume": 0.8,
    "speed": 1.0,
    "filters": []
  }
}

Media Types

Type Description Supported Formats Notes
video Video files MP4, MOV, AVI, MKV, WebM Can be trimmed with start/end times
image Static images JPG, JPEG, PNG Duration specifies display time
audio Audio overlay MP3, WAV, AAC Overlaid on video track

Transition Types

Transition Description Duration Effect
cut Direct cut, no transition 0s Instant switch
dissolve Cross-fade between clips 0.5s Smooth blend
fade Fade to black, then fade in 1.0s Black transition

⚙️Effects and Filters

Video Effects

"effects": {
  "volume": 0.8,
  "speed": 1.2,
  "brightness": 1.1,
  "contrast": 1.0,
  "saturation": 1.0,
  "filters": [
    "stabilize",
    "denoise"
  ]
}
Effect Type Range Default Description
volume number 0.0 - 2.0 1.0 Audio volume multiplier
speed number 0.25 - 4.0 1.0 Playback speed multiplier
brightness number 0.0 - 2.0 1.0 Video brightness

📝Example Configurations

⚽Basic Sports Highlight

{
  "project": {
    "name": "Soccer Game Highlights",
    "event_type": "sports",
    "output_settings": {
      "resolution": "1920x1080",
      "quality": "high"
    }
  },
  "media": [
    {
      "file": "goal1.mp4",
      "start_time": 5.0,
      "end_time": 15.0,
      "transition": "cut"
    },
    {
      "file": "celebration.jpg",
      "duration": 3.0,
      "transition": "dissolve"
    },
    {
      "file": "goal2.mp4",
      "start_time": 2.0,
      "end_time": 12.0,
      "transition": "fade"
    }
  ]
}

💒Wedding Ceremony Montage

{
  "project": {
    "name": "Wedding Ceremony Highlights",
    "event_type": "wedding",
    "description": "Beautiful moments from Sarah & Mike's wedding"
  },
  "media": [
    {
      "file": "processional.mp4",
      "start_time": 10.0,
      "end_time": 45.0,
      "effects": {
        "volume": 0.7
      },
      "transition": "dissolve"
    },
    {
      "file": "vows.mp4",
      "start_time": 0.0,
      "end_time": 30.0,
      "transition": "dissolve"
    },
    {
      "file": "rings.jpg",
      "duration": 4.0,
      "transition": "fade"
    }
  ],
  "global_settings": {
    "audio": {
      "background_music": "wedding_song.mp3",
      "background_volume": 0.2
    }
  }
}

🎂Birthday Party Memories

{
  "project": {
    "name": "Emma's 5th Birthday",
    "event_type": "birthday"
  },
  "media": [
    {
      "file": "party_setup.jpg",
      "duration": 2.5,
      "transition": "dissolve"
    },
    {
      "file": "candle_blowing.mp4",
      "start_time": 0.0,
      "end_time": 15.0,
      "transition": "cut"
    },
    {
      "file": "gift_opening.mp4",
      "start_time": 5.0,
      "end_time": 25.0,
      "effects": {
        "speed": 1.5
      },
      "transition": "dissolve"
    }
  ]
}

⚠️Validation Rules

File Requirements

  • All referenced media files must be uploaded along with the config
  • File names must match exactly (case-sensitive)
  • Supported formats: MP4, MOV, AVI, MKV, WebM, JPG, JPEG, PNG

Timing Constraints

  • start_time must be less than end_time
  • duration for images must be > 0 and ≤ 30 seconds
  • Total project duration should not exceed 10 minutes

Common Errors

Error Cause Solution
Invalid JSON format Syntax error in JSON Validate JSON syntax
Missing required field Required field not provided Add missing project.name
File not found Referenced file not uploaded Ensure all files are included

📚Best Practices

Naming Conventions

  • Use descriptive filenames: goal_minute_15.mp4 instead of video1.mp4
  • Keep project names concise but informative
  • Use consistent naming patterns within a project

Performance Optimization

  • Place most important content first in the media array
  • Use appropriate quality settings for your target audience
  • Consider file sizes when planning long compositions

Organization

  • Group related media files logically
  • Use metadata tags for easy searching and filtering
  • Include descriptions for complex projects

Testing

  • Test with a small subset of files first
  • Validate JSON syntax before uploading
  • Preview transitions and effects with short clips

🆔Schema Version

Current schema version: 1.0

For future compatibility, always include:

{
  "schema_version": "1.0",
  "project": {
    // ... rest of config
  }
}

📞Support

For additional help with config.json formatting:

  • Check the server logs for detailed error messages
  • Use the /health endpoint to verify server capabilities
  • Reference example configs provided with the server
  • Validate JSON syntax using online JSON validators