> ## 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.

# SEOOptimizerAgent

> AI-powered YouTube SEO optimization agent

## Overview

The `SEOOptimizerAgent` optimizes video metadata for maximum YouTube discoverability. It generates optimized titles, descriptions, tags, hashtags, chapters, and calculates comprehensive SEO scores.

## Constructor

<ParamField path="db" type="Database" required>
  Database instance for keyword history and SEO data
</ParamField>

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

```javascript theme={null}
const { SEOOptimizerAgent } = require('./agents/seo-optimizer-agent');

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

## Properties

<ResponseField name="keywordDatabase" type="Map">
  Historical keyword performance data
</ResponseField>

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

## Methods

### initialize()

Initializes the agent and loads keyword history.

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

```javascript theme={null}
await agent.initialize();
// Loads keyword performance history for optimization
```

### optimize(script, strategy)

Generates complete SEO optimization for a video.

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

<ParamField path="strategy" type="Object" required>
  Content strategy object
</ParamField>

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

<ResponseField name="seoData.title" type="string">
  Optimized title (60-100 characters)
</ResponseField>

<ResponseField name="seoData.description" type="string">
  Comprehensive description (up to 5000 characters, first 125 optimized)
</ResponseField>

<ResponseField name="seoData.tags" type="Array<string>">
  Prioritized tags (max 500 characters total)
</ResponseField>

<ResponseField name="seoData.hashtags" type="Array<string>">
  15 relevant hashtags
</ResponseField>

<ResponseField name="seoData.chapters" type="Array<Object>">
  Video chapters with timestamps
</ResponseField>

<ResponseField name="seoData.endScreen" type="Object">
  End screen strategy
</ResponseField>

<ResponseField name="seoData.seoScore" type="number">
  Overall SEO score (0-100)
</ResponseField>

<ResponseField name="seoData.metadata" type="Object">
  Additional metadata (keywords, category, language)
</ResponseField>

```javascript theme={null}
const seoData = await agent.optimize(script, strategy);

console.log(seoData);
// {
//   title: 'Ultimate JavaScript Tutorial - Master JS in 2026',
//   description: 'JavaScript Tutorial - In this video, you\'ll discover...',
//   tags: ['javascript', 'tutorial', 'programming', 'how to javascript', ...],
//   hashtags: ['#JavaScript', '#Tutorial', '#Programming', ...],
//   chapters: [
//     { time: '00:00', title: 'Introduction', seconds: 0 },
//     { time: '00:20', title: 'The Challenge', seconds: 20 },
//     ...
//   ],
//   endScreen: { elements: [...], startTime: -20, template: 'standard' },
//   seoScore: 87,
//   metadata: {
//     primaryKeyword: 'javascript',
//     secondaryKeywords: ['tutorial', 'programming', 'coding', 'learn'],
//     targetLength: '10-15 minutes',
//     language: 'en',
//     category: 28
//   },
//   createdAt: '2026-03-05T10:00:00.000Z'
// }
```

### optimizeTitle(originalTitle, strategy)

Optimizes video title for searchability and CTR.

<ParamField path="originalTitle" type="string" required>
  Original title from script
</ParamField>

<ParamField path="strategy" type="Object" required>
  Content strategy
</ParamField>

<ParamField path="return" type="Promise<string>">
  Optimized title (max 100 characters)
</ParamField>

```javascript theme={null}
const optimized = await agent.optimizeTitle(
  'JavaScript Tutorial',
  { keywords: ['javascript', 'programming'], contentType: 'Tutorial' }
);
// 'Ultimate JavaScript Tutorial (2026) - Programming'

// Optimization includes:
// - Power words (Ultimate, Complete, Essential, etc.)
// - Current year if under 70 characters
// - Primary keyword inclusion
// - Proper title case formatting
// - Length optimization (60-70 characters ideal)
```

### generateDescription(script, strategy)

Generates comprehensive, SEO-optimized video description.

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

<ParamField path="strategy" type="Object" required>
  Content strategy
</ParamField>

<ParamField path="return" type="Promise<string>">
  Full description (up to 5000 characters)
</ParamField>

```javascript theme={null}
const description = await agent.generateDescription(script, strategy);

// Description includes:
// - Hook (first 125 characters - shown in search)
// - What you'll learn section
// - Timestamps/chapters
// - About this video (keyword-rich paragraph)
// - Useful links (channel, website, social)
// - Related videos
// - Tools & resources (for tutorials)
// - Business inquiries
// - Hashtags
// - Disclaimer
// - Copyright and music credits
```

### generateTags(script, strategy)

Generates and prioritizes video tags.

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

<ParamField path="strategy" type="Object" required>
  Content strategy
</ParamField>

<ParamField path="return" type="Promise<Array<string>>">
  Prioritized tags (max 500 characters total)
</ParamField>

```javascript theme={null}
const tags = await agent.generateTags(script, strategy);

// Tag sources:
// - Primary keywords from strategy
// - Topic variations (with spaces, without, with underscores)
// - Content type tags (tutorial, how to, guide, etc.)
// - Year tags (2026, JavaScript 2026)
// - Niche-specific tags (tech, gaming, education, etc.)
// - Long-tail keywords (how to javascript, javascript for beginners)
// - Channel branding tags

console.log(tags);
// ['javascript', 'tutorial', 'how to', 'programming', '2026', 
//  'javascript 2026', 'javascript tutorial', 'learn javascript', ...]
```

### generateHashtags(strategy)

Generates relevant hashtags for video.

<ParamField path="strategy" type="Object" required>
  Content strategy
</ParamField>

<ParamField path="return" type="Promise<Array<string>>">
  15 relevant hashtags
</ParamField>

```javascript theme={null}
const hashtags = await agent.generateHashtags(strategy);

// Includes:
// - Primary topic hashtag (#JavaScript)
// - Content type hashtag (#Tutorial)
// - Trending hashtags (#YouTube, #Subscribe, #Trending)
// - Niche hashtags (#Tech, #Programming)
// - Year hashtag (#2026)

console.log(hashtags);
// ['#JavaScript', '#Tutorial', '#YouTube', '#Tech', '#Programming', 
//  '#Subscribe', '#Video', '#2026', ...]
```

### generateChapters(script)

Generates video chapters with timestamps.

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

<ParamField path="return" type="Promise<Array<Object>>">
  Chapter objects with time, title, and seconds
</ParamField>

```javascript theme={null}
const chapters = await agent.generateChapters(script);

console.log(chapters);
// [
//   { time: '00:00', title: 'Introduction', seconds: 0 },
//   { time: '00:20', title: 'The Challenge', seconds: 20 },
//   { time: '00:50', title: 'The Solution', seconds: 50 },
//   { time: '03:05', title: 'Live Demo', seconds: 185 },
//   { time: '05:05', title: 'Conclusion & Next Steps', seconds: 305 }
// ]
```

### generateEndScreenStrategy()

Generates end screen element configuration.

<ParamField path="return" type="Promise<Object>">
  End screen strategy with elements and timing
</ParamField>

```javascript theme={null}
const endScreen = await agent.generateEndScreenStrategy();

console.log(endScreen);
// {
//   elements: [
//     { type: 'video', position: 'left', title: 'Recommended Video', duration: 20 },
//     { type: 'playlist', position: 'right', title: 'Watch More', duration: 20 },
//     { type: 'subscribe', position: 'center-bottom', duration: 20 }
//   ],
//   startTime: -20,  // 20 seconds before end
//   template: 'standard'
// }
```

### calculateSEOScore(title, description, tags)

Calculates comprehensive SEO score.

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

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

<ParamField path="tags" type="Array<string>" required>
  Video tags
</ParamField>

<ParamField path="return" type="Promise<number>">
  SEO score (0-100)
</ParamField>

```javascript theme={null}
const score = await agent.calculateSEOScore(title, description, tags);

// Scoring breakdown:
// Title (30 points max):
//   - Optimal length 60-70 chars: 10 points
//   - Contains number: 5 points
//   - Proper capitalization: 5 points
//   - Current year: 5 points
//   - Power words (how, what, why, best): 5 points
//
// Description (40 points max):
//   - Length >= 200 chars: 10 points
//   - Length >= 500 chars: 10 points
//   - Contains TIMESTAMPS: 5 points
//   - Contains links: 5 points
//   - Well formatted (10+ lines): 5 points
//   - Primary keyword in first 125 chars: 5 points
//
// Tags (30 points max):
//   - 10+ tags: 10 points
//   - 15+ tags: 5 points
//   - Contains long-tail keywords: 5 points
//   - Within 500 char limit: 5 points
//   - No duplicates: 5 points

console.log('SEO Score:', score);
// 87
```

### identifyNiche(strategy)

Identifies content niche from strategy.

<ParamField path="strategy" type="Object" required>
  Content strategy
</ParamField>

<ParamField path="return" type="string">
  Niche category: technology, gaming, education, business, lifestyle, health, entertainment, or general
</ParamField>

```javascript theme={null}
const niche = agent.identifyNiche({ topic: 'Python Programming Tutorial' });
// 'technology'
```

### selectCategory(strategy)

Selects YouTube category ID.

<ParamField path="strategy" type="Object" required>
  Content strategy
</ParamField>

<ParamField path="return" type="number">
  YouTube category ID
</ParamField>

```javascript theme={null}
const categoryId = agent.selectCategory(strategy);
// 28 for technology/science
// 20 for gaming
// 27 for education
// 22 for people & blogs (default)
```

### calculateOptimalLength(contentType)

Calculates optimal video length for content type.

<ParamField path="contentType" type="string" required>
  Content type (Tutorial, Explainer, Review, List, Story)
</ParamField>

<ParamField path="return" type="string">
  Recommended duration range
</ParamField>

```javascript theme={null}
const length = agent.calculateOptimalLength('Tutorial');
// '10-15 minutes'

// Optimal lengths:
// Tutorial: 10-15 minutes
// Explainer: 5-10 minutes
// Review: 8-12 minutes
// List: 8-15 minutes
// Story: 10-20 minutes
```

## Usage Example

```javascript theme={null}
const { SEOOptimizerAgent } = require('./agents/seo-optimizer-agent');

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

const script = {
  title: 'JavaScript Promises Tutorial',
  mainContent: {
    sections: [
      { title: 'The Challenge', duration: 30 },
      { title: 'The Solution', duration: 90 },
      { title: 'Live Demo', duration: 120 }
    ]
  }
};

const strategy = {
  topic: 'JavaScript Promises',
  contentType: 'Tutorial',
  keywords: ['javascript', 'promises', 'async', 'tutorial'],
  targetAudience: 'Developers'
};

const seoData = await agent.optimize(script, strategy);

console.log('Optimized Title:', seoData.title);
console.log('SEO Score:', seoData.seoScore, '/100');
console.log('Tags:', seoData.tags.join(', '));
console.log('Chapters:', seoData.chapters.length);

// Use in video upload
const uploadMetadata = {
  title: seoData.title,
  description: seoData.description,
  tags: seoData.tags,
  categoryId: seoData.metadata.category.toString()
};
```

## Tag Categories

The agent generates tags from multiple sources:

<Accordion title="Primary Keywords">
  Direct keywords from content strategy (highest priority)
</Accordion>

<Accordion title="Topic Variations">
  Topic with spaces, without spaces, with underscores
</Accordion>

<Accordion title="Content Type Tags">
  Tutorial: how to, tutorial, guide, step by step, learn
  Explainer: explained, what is, understanding
  Review: review, comparison, vs, best, top
  List: top 10, best, list, countdown
</Accordion>

<Accordion title="Long-Tail Keywords">
  Multi-word phrases (e.g., "how to javascript", "javascript for beginners")
</Accordion>

<Accordion title="Niche Tags">
  Technology: tech, innovation, future tech
  Gaming: gaming, gameplay, walkthrough
  Education: educational, learning, study tips
</Accordion>

<Accordion title="Temporal Tags">
  Current year and "topic year" combinations
</Accordion>

## Best Practices

<Accordion title="Optimize First 125 Characters">
  The first 125 characters of the description appear in search results. Include primary keywords and a compelling hook.
</Accordion>

<Accordion title="Use All 500 Tag Characters">
  The agent prioritizes tags to use the full 500-character limit. Mix broad and long-tail keywords.
</Accordion>

<Accordion title="Add Timestamps">
  Chapters improve user experience and SEO. The agent automatically generates them from script sections.
</Accordion>

<Accordion title="Target 80+ SEO Score">
  Scores above 80 indicate well-optimized content. Below 60 needs improvement in title, description, or tags.
</Accordion>

<Accordion title="Update Keywords Database">
  Store performance data for keywords to improve future optimization recommendations.
</Accordion>

## Environment Variables

<ParamField path="WEBSITE_URL" type="string" optional>
  Your website URL for description links
</ParamField>

<ParamField path="SOCIAL_LINKS" type="string" optional>
  Social media links for description
</ParamField>

<ParamField path="BUSINESS_EMAIL" type="string" optional>
  Business inquiry email for description
</ParamField>

<ParamField path="CHANNEL_NAME" type="string" optional>
  Channel name for branding tags
</ParamField>