> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/darkzOGx/youtube-automation-agent/llms.txt
> Use this file to discover all available pages before exploring further.

# ThumbnailDesignerAgent

> AI-powered thumbnail design and optimization agent

## Overview

The `ThumbnailDesignerAgent` generates eye-catching YouTube thumbnails optimized for high click-through rates. It uses Sharp for image processing and creates thumbnails with strategic text overlays, color schemes, and visual elements.

## Constructor

<ParamField path="db" type="Database" required>
  Database instance for storing thumbnail data
</ParamField>

<ParamField path="credentials" type="Credentials" required>
  Credentials manager for external services
</ParamField>

```javascript theme={null}
const { ThumbnailDesignerAgent } = require('./agents/thumbnail-designer-agent');

const agent = new ThumbnailDesignerAgent(db, credentials);
```

## Properties

<ResponseField name="templatesPath" type="string">
  Path to thumbnail template assets directory
</ResponseField>

<ResponseField name="logger" type="Logger">
  Logger instance for tracking thumbnail generation
</ResponseField>

## Methods

### initialize()

Initializes the agent and creates necessary directories.

<ParamField path="return" type="Promise<boolean>">
  Returns true when initialization is complete
</ParamField>

```javascript theme={null}
await agent.initialize();
// Creates data/thumbnail-templates and uploads/thumbnails directories
```

### generateThumbnail(script)

Generates a complete, optimized thumbnail for a video script.

<ParamField path="script" type="Object" required>
  Video script object
</ParamField>

<ParamField path="script.title" type="string" required>
  Video title
</ParamField>

<ParamField path="script.metadata.strategy" type="Object" optional>
  Content strategy with contentType
</ParamField>

<ParamField path="return" type="Promise<Object>">
  Thumbnail data object
</ParamField>

<ResponseField name="thumbnail.path" type="string">
  Path to optimized thumbnail file (JPEG, under 2MB)
</ResponseField>

<ResponseField name="thumbnail.concept" type="Object">
  Design concept with style, colors, elements
</ResponseField>

<ResponseField name="thumbnail.prompt" type="string">
  AI generation prompt used
</ResponseField>

<ResponseField name="thumbnail.dimensions" type="Object">
  Width and height (1280x720)
</ResponseField>

<ResponseField name="thumbnail.fileSize" type="number">
  File size in bytes
</ResponseField>

```javascript theme={null}
const script = {
  title: 'How to Master JavaScript in 30 Days',
  metadata: {
    strategy: {
      contentType: 'Tutorial',
      topic: 'JavaScript'
    }
  }
};

const thumbnail = await agent.generateThumbnail(script);

console.log(thumbnail);
// {
//   path: '/path/to/thumbnail_optimized_1234567890.jpg',
//   concept: {
//     title: 'How to Master JavaScript in 30 Days',
//     style: 'clean',
//     primaryText: 'MASTER',
//     secondaryText: 'STEP BY STEP',
//     colors: { primary: 'blue', secondary: 'white', accent: 'green' },
//     emotion: 'helpful',
//     composition: 'rule-of-thirds',
//     effects: { blur: false, vignette: false, glow: true, shadow: true, border: false }
//   },
//   dimensions: { width: 1280, height: 720 },
//   fileSize: 156789,
//   createdAt: '2026-03-05T10:00:00.000Z'
// }
```

### generateConcept(script)

Generates thumbnail design concept based on content type.

<ParamField path="script" type="Object" required>
  Video script object
</ParamField>

<ParamField path="return" type="Promise<Object>">
  Design concept object
</ParamField>

<ResponseField name="concept.title" type="string">
  Shortened title for thumbnail (max 5 words)
</ResponseField>

<ResponseField name="concept.style" type="string">
  Visual style: clean, informative, numbered, comparative, or dramatic
</ResponseField>

<ResponseField name="concept.primaryText" type="string">
  Main text overlay (impact word or number)
</ResponseField>

<ResponseField name="concept.secondaryText" type="string">
  Supporting text overlay
</ResponseField>

<ResponseField name="concept.elements" type="Array<string>">
  Visual elements to include
</ResponseField>

<ResponseField name="concept.colors" type="Object">
  Color scheme with primary, secondary, and accent colors
</ResponseField>

<ResponseField name="concept.emotion" type="string">
  Emotional tone: helpful, curious, exciting, analytical, or intriguing
</ResponseField>

<ResponseField name="concept.composition" type="string">
  Layout composition style
</ResponseField>

<ResponseField name="concept.effects" type="Object">
  Visual effects to apply (blur, vignette, glow, shadow, border)
</ResponseField>

```javascript theme={null}
const concept = await agent.generateConcept(script);
// Content type-specific concepts:
// Tutorial: clean style, blue/white/green, educational elements
// Explainer: informative, purple/yellow/white, question marks
// List: numbered, red/yellow/black, countdown elements
// Review: comparative, orange/gray/white, rating stars
// Story: dramatic, dark blue/gold/white, emotional imagery
```

## Thumbnail Concepts by Content Type

<CodeGroup>
  ```javascript Tutorial theme={null}
  {
    style: 'clean',
    elements: ['step numbers', 'arrows', 'progress indicators'],
    colors: ['blue', 'white', 'green'],
    emotion: 'helpful'
  }
  ```

  ```javascript Explainer theme={null}
  {
    style: 'informative',
    elements: ['icons', 'diagrams', 'question marks'],
    colors: ['purple', 'yellow', 'white'],
    emotion: 'curious'
  }
  ```

  ```javascript List theme={null}
  {
    style: 'numbered',
    elements: ['large numbers', 'countdown', 'highlights'],
    colors: ['red', 'yellow', 'black'],
    emotion: 'exciting'
  }
  ```

  ```javascript Review theme={null}
  {
    style: 'comparative',
    elements: ['product image', 'rating stars', 'vs symbol'],
    colors: ['orange', 'gray', 'white'],
    emotion: 'analytical'
  }
  ```

  ```javascript Story theme={null}
  {
    style: 'dramatic',
    elements: ['faces', 'emotion', 'journey path'],
    colors: ['dark blue', 'gold', 'white'],
    emotion: 'intriguing'
  }
  ```
</CodeGroup>

### createThumbnail(concept)

Creates base thumbnail image with gradient background.

<ParamField path="concept" type="Object" required>
  Design concept from generateConcept()
</ParamField>

<ParamField path="return" type="Promise<string>">
  Path to base thumbnail PNG file
</ParamField>

```javascript theme={null}
const basePath = await agent.createThumbnail(concept);
// Creates 1280x720 PNG with gradient background
```

### addTextOverlay(imagePath, concept)

Adds text overlay to thumbnail image.

<ParamField path="imagePath" type="string" required>
  Path to base thumbnail image
</ParamField>

<ParamField path="concept" type="Object" required>
  Design concept with primaryText and secondaryText
</ParamField>

<ParamField path="return" type="Promise<string>">
  Path to thumbnail with text overlay
</ParamField>

```javascript theme={null}
const withText = await agent.addTextOverlay(basePath, concept);
// Adds large primary text (120px) and secondary text (60px)
// Includes shadow effect for readability
```

### optimizeForYouTube(imagePath)

Optimizes thumbnail for YouTube specifications.

<ParamField path="imagePath" type="string" required>
  Path to thumbnail image
</ParamField>

<ParamField path="return" type="Promise<string>">
  Path to optimized JPEG file
</ParamField>

<ResponseField name="format" type="string">
  JPEG with progressive encoding
</ResponseField>

<ResponseField name="quality" type="number">
  90% quality, reduced to 80% if file exceeds 2MB
</ResponseField>

<ResponseField name="dimensions" type="Object">
  1280x720 (YouTube recommended size)
</ResponseField>

<ResponseField name="maxFileSize" type="number">
  2MB (YouTube limit)
</ResponseField>

```javascript theme={null}
const optimized = await agent.optimizeForYouTube(withTextPath);
// Ensures file is under 2MB limit
// JPEG format with high quality and progressive loading
```

### generateABVariants(concept)

Generates multiple thumbnail variants for A/B testing.

<ParamField path="concept" type="Object" required>
  Base design concept
</ParamField>

<ParamField path="return" type="Promise<Array<string>>">
  Array of paths to thumbnail variants
</ParamField>

```javascript theme={null}
const variants = await agent.generateABVariants(concept);
// Returns 3 variants:
// 1. Different color scheme (swapped primary/secondary)
// 2. Alternative text
// 3. Centered composition

console.log(variants);
// [
//   '/path/to/variant1.png',
//   '/path/to/variant2.png',
//   '/path/to/variant3.png'
// ]
```

### extractPrimaryText(title)

Extracts most impactful text from title.

<ParamField path="title" type="string" required>
  Video title
</ParamField>

<ParamField path="return" type="string">
  Primary text for thumbnail (uppercase)
</ParamField>

```javascript theme={null}
const primary = agent.extractPrimaryText('The Ultimate Guide to JavaScript');
// 'ULTIMATE' (found impact word)

const primary2 = agent.extractPrimaryText('Top 10 Tips for Beginners');
// '10' (found number)

const primary3 = agent.extractPrimaryText('Learn Python Quickly');
// 'LEARN' (first significant word)
```

### formatThumbnailTitle(title)

Shortens title for thumbnail display.

<ParamField path="title" type="string" required>
  Full video title
</ParamField>

<ParamField path="return" type="string">
  Shortened title (max 5 words)
</ParamField>

```javascript theme={null}
const short = agent.formatThumbnailTitle('The Complete Ultimate Guide to JavaScript Programming');
// 'The Complete Ultimate Guide to...'
```

### selectComposition()

Randomly selects a composition style.

<ParamField path="return" type="string">
  Composition style: rule-of-thirds, centered, diagonal, golden-ratio, or symmetrical
</ParamField>

```javascript theme={null}
const composition = agent.selectComposition();
// 'rule-of-thirds'
```

### selectEffects()

Randomly selects visual effects to apply.

<ParamField path="return" type="Object">
  Effects configuration object
</ParamField>

```javascript theme={null}
const effects = agent.selectEffects();
// {
//   blur: false,
//   vignette: true,
//   glow: false,
//   shadow: true,  // Always true
//   border: false
// }
```

## Usage Example

```javascript theme={null}
const { ThumbnailDesignerAgent } = require('./agents/thumbnail-designer-agent');
const fs = require('fs').promises;

const agent = new ThumbnailDesignerAgent(db, credentials);
await agent.initialize();

// Generate thumbnail from script
const script = {
  title: 'Master React Hooks in 15 Minutes',
  metadata: {
    strategy: {
      contentType: 'Tutorial'
    }
  }
};

const thumbnail = await agent.generateThumbnail(script);

console.log('Thumbnail generated:', thumbnail.path);
console.log('File size:', Math.round(thumbnail.fileSize / 1024), 'KB');
console.log('Primary text:', thumbnail.concept.primaryText);
console.log('Color scheme:', thumbnail.concept.colors);

// Generate A/B test variants
const variants = await agent.generateABVariants(thumbnail.concept);
console.log('Created', variants.length, 'variants for testing');

// Copy to final location
await fs.copyFile(thumbnail.path, './final-thumbnail.jpg');
```

## YouTube Thumbnail Requirements

<Accordion title="Dimensions">
  1280x720 pixels (16:9 aspect ratio) - YouTube's recommended size
</Accordion>

<Accordion title="File Size">
  Under 2MB - automatically enforced by optimizeForYouTube()
</Accordion>

<Accordion title="Format">
  JPEG recommended - PNG also supported but results in larger files
</Accordion>

<Accordion title="Quality">
  90% quality for best balance, reduced to 80% if file exceeds limit
</Accordion>

## Best Practices

<Accordion title="Use High Contrast Text">
  The agent automatically adds text shadows for readability. Primary text is large (120px) and bold.
</Accordion>

<Accordion title="Test Multiple Variants">
  Use generateABVariants() to create multiple thumbnails and test which performs best with your audience.
</Accordion>

<Accordion title="Match Content Type">
  Each content type has optimized colors and style. Tutorial thumbnails use educational blue/green, while list videos use attention-grabbing red/yellow.
</Accordion>

<Accordion title="Keep Text Minimal">
  Primary text is limited to one impactful word or number. Secondary text adds context but stays concise.
</Accordion>

<Accordion title="Monitor CTR">
  Track click-through rates and adjust concept generation based on what works for your audience.
</Accordion>