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

# Quickstart

> Get your first YouTube video generated in 10 minutes with the YouTube Automation Agent.

# Quickstart Guide

Get from zero to your first automatically generated video in just 10 minutes. This guide will walk you through the fastest path to generating content.

<Note>
  **Prerequisites**: Node.js 18+ installed. If you don't have it, [download Node.js here](https://nodejs.org/).
</Note>

## Quick Setup

<Steps>
  <Step title="Clone and Install">
    Get the repository and install dependencies:

    ```bash theme={null}
    git clone https://github.com/darkzOGx/youtube-automation-agent.git
    cd youtube-automation-agent
    npm install
    ```

    This will install all required packages including:

    * `googleapis` - YouTube API integration
    * `openai` / `@google/generative-ai` - AI content generation
    * `express` - API server
    * `sqlite3` - Database management
    * `node-cron` - Task scheduling
  </Step>

  <Step title="Run Setup Wizard">
    The interactive setup wizard will guide you through configuration:

    ```bash theme={null}
    npm run setup
    ```

    The setup wizard will:

    <AccordionGroup>
      <Accordion title="Create Directory Structure" icon="folder-tree">
        ```javascript theme={null}
        const directories = [
          'config',
          'logs',
          'data',
          'data/production',
          'data/assets',
          'data/videos',
          'data/audio',
          'data/scripts',
          'data/captions',
          'data/thumbnail-templates',
          'temp/processing',
          'uploads/thumbnails'
        ];
        ```

        All directories created automatically with proper permissions.
      </Accordion>

      <Accordion title="Initialize Database" icon="database">
        ```javascript theme={null}
        await this.database.initialize();
        // Creates SQLite database with tables:
        // - content_strategies
        // - scripts
        // - thumbnails
        // - seo_data
        // - productions
        // - publish_schedule
        // - analytics_reports
        // - keyword_performance
        ```
      </Accordion>

      <Accordion title="Configure Credentials" icon="key">
        Interactive prompts for:

        * YouTube API credentials (OAuth 2.0)
        * AI provider selection (OpenAI or Gemini)
        * API keys for chosen provider
        * Channel preferences and settings
      </Accordion>

      <Accordion title="Create Environment File" icon="file">
        ```bash theme={null}
        # Generated .env file with:
        NODE_ENV=production
        PORT=3456
        LOG_LEVEL=info
        YOUTUBE_REGION=US
        DEFAULT_PRIVACY_STATUS=public
        JWT_SECRET=<auto-generated>
        # ... and more
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Configure API Keys">
    You'll need two sets of credentials:

    ### YouTube Data API (Required - FREE)

    <Steps>
      <Step title="Create Google Cloud Project">
        1. Go to [Google Cloud Console](https://console.cloud.google.com/)
        2. Click **"Create Project"** (name it "YouTube Automation")
        3. Wait for project creation to complete
      </Step>

      <Step title="Enable YouTube API">
        1. Navigate to **"APIs & Services"** → **"Library"**
        2. Search for **"YouTube Data API v3"**
        3. Click **"Enable"**
      </Step>

      <Step title="Create OAuth Credentials">
        1. Go to **"Credentials"** → **"Create Credentials"** → **"OAuth client ID"**
        2. Choose **"Desktop app"** as application type
        3. Download the JSON file
        4. Save as `config/credentials.json`
      </Step>
    </Steps>

    ### AI Provider (Choose One)

    <CodeGroup>
      ```bash OpenAI (Recommended) theme={null}
      # 1. Visit https://platform.openai.com/
      # 2. Go to API Keys section
      # 3. Create new secret key
      # 4. Add to .env file:
      OPENAI_API_KEY=sk-proj-...

      # Cost: ~$0.10-0.30 per video
      # Add $5-10 credits to start
      ```

      ```bash Google Gemini (FREE) theme={null}
      # 1. Visit https://makersuite.google.com/
      # 2. Click "Get API Key"
      # 3. Create API key
      # 4. Add to .env file:
      GEMINI_API_KEY=AIza...

      # Cost: FREE (60 requests/minute)
      # Perfect for most users!
      ```
    </CodeGroup>
  </Step>

  <Step title="Start the System">
    Launch the automation agent:

    ```bash theme={null}
    npm start
    ```

    You should see:

    ```
    🎬 YouTube Automation Agent v1.0
    ──────────────────────────────────────────────────
    ✓ Database initialized
    ✓ Credentials loaded
    ✓ strategy agent initialized
    ✓ scriptWriter agent initialized
    ✓ thumbnailDesigner agent initialized
    ✓ seoOptimizer agent initialized
    ✓ production agent initialized
    ✓ publishing agent initialized
    ✓ analytics agent initialized

    ✅ YouTube Automation Agent running on port 3456
    ──────────────────────────────────────────────────
    📊 Dashboard: http://localhost:3456
    🔧 API Health: http://localhost:3456/health
    📅 Schedule: http://localhost:3456/schedule
    📈 Analytics: http://localhost:3456/analytics
    ──────────────────────────────────────────────────

    🤖 Automation is active. Content will be generated and posted daily.
    ```
  </Step>
</Steps>

## Generate Your First Video

Now let's create content! You have three options:

<Tabs>
  <Tab title="Automatic (Recommended)">
    ### Let the AI Choose

    The Content Strategy Agent will analyze trends and select the best topic:

    ```bash theme={null}
    curl -X POST http://localhost:3456/generate \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    This triggers the full workflow:

    ```javascript theme={null}
    async generateContent() {
      // 1. Analyze YouTube trends (50+ trending videos)
      const strategy = await this.agents.strategy.generateContentStrategy();
      
      // 2. Generate engaging script with hooks and CTAs
      const script = await this.agents.scriptWriter.generateScript(strategy);
      
      // 3. Create eye-catching thumbnail
      const thumbnail = await this.agents.thumbnailDesigner.generateThumbnail(script);
      
      // 4. Optimize for SEO (title, description, tags)
      const seoData = await this.agents.seoOptimizer.optimize(script, strategy);
      
      // 5. Process through production pipeline
      const productionData = await this.agents.production.processContent({
        strategy, script, thumbnail, seo: seoData
      });
      
      // 6. Schedule for optimal publish time
      const contentId = await this.db.saveProductionData(productionData);
      
      return { contentId, title: script.title, scheduledFor: productionData.scheduledPublishTime };
    }
    ```
  </Tab>

  <Tab title="Custom Topic">
    ### Specify Your Topic

    Generate content about a specific topic:

    ```bash theme={null}
    curl -X POST http://localhost:3456/generate \
      -H "Content-Type: application/json" \
      -d '{
        "topic": "Top 10 Life Hacks for Productivity",
        "style": "listicle"
      }'
    ```

    Available content types:

    * `tutorial` - Step-by-step guides
    * `listicle` - Top 10, Best of, etc.
    * `review` - Product or service reviews
    * `explainer` - Educational content
    * `news` - Breaking news format
    * `story` - Narrative-driven content
  </Tab>

  <Tab title="Test Mode">
    ### Run System Test

    Verify all components without creating actual content:

    ```bash theme={null}
    npm run test
    ```

    This validates:

    * Database connectivity
    * API credentials
    * Agent initialization
    * File system permissions
  </Tab>
</Tabs>

## Understanding the Response

When you generate content, you'll receive:

```json theme={null}
{
  "success": true,
  "result": {
    "contentId": "production_1234567890_abc123",
    "title": "The Ultimate Guide to AI Content Creation in 2025",
    "scheduledFor": "2026-03-12T14:00:00.000Z"
  }
}
```

<CardGroup cols={3}>
  <Card title="contentId" icon="fingerprint">
    Unique identifier for tracking through production pipeline
  </Card>

  <Card title="title" icon="heading">
    SEO-optimized title generated by the system
  </Card>

  <Card title="scheduledFor" icon="calendar">
    Optimal publish time based on audience analysis
  </Card>
</CardGroup>

## Monitoring Your Content

### View Dashboard

Access the web dashboard:

```bash theme={null}
open http://localhost:3456
```

### Check Health Status

```bash theme={null}
curl http://localhost:3456/health
```

Response:

```json theme={null}
{
  "status": "healthy",
  "initialized": true,
  "agents": [
    "strategy",
    "scriptWriter",
    "thumbnailDesigner",
    "seoOptimizer",
    "production",
    "publishing",
    "analytics"
  ],
  "timestamp": "2026-03-05T12:00:00.000Z"
}
```

### View Publishing Schedule

```bash theme={null}
curl http://localhost:3456/schedule
```

See all upcoming content:

```json theme={null}
[
  {
    "id": "schedule_1234567890_xyz",
    "title": "The Ultimate Guide to AI Content Creation in 2025",
    "publish_time": "2026-03-12T14:00:00.000Z",
    "status": "scheduled",
    "priority": 50
  }
]
```

### Get Analytics

```bash theme={null}
curl http://localhost:3456/analytics
```

## What Happens Next?

With the system running, here's the automatic workflow:

<Steps>
  <Step title="Daily Content Generation (6:00 AM)">
    ```javascript theme={null}
    cron.schedule('0 6 * * *', async () => {
      // Checks content buffer (default: 3 days)
      const shouldGenerate = await this.shouldGenerateContentToday();
      
      if (shouldGenerate) {
        // Full content generation pipeline
        await this.runDailyContentGeneration();
      }
    });
    ```

    Generates new content if buffer is low.
  </Step>

  <Step title="Publishing Queue Processing (Every 15 Minutes)">
    ```javascript theme={null}
    cron.schedule('*/15 * * * *', async () => {
      // Checks for videos ready to publish
      await this.processPublishQueue();
    });
    ```

    Automatically uploads videos at scheduled times.
  </Step>

  <Step title="Analytics Collection (9:00 AM)">
    ```javascript theme={null}
    cron.schedule('0 9 * * *', async () => {
      const recentVideos = await this.getRecentlyPublishedVideos(7);
      
      for (const video of recentVideos) {
        await this.agents.analytics.analyzeVideoPerformance(video.youtube_id);
      }
    });
    ```

    Collects performance data for recent videos.
  </Step>

  <Step title="Optimization Tasks (10:00 PM)">
    ```javascript theme={null}
    cron.schedule('0 22 * * *', async () => {
      await this.optimizeExistingContent();
      await this.updateKeywordPerformance();
      await this.cleanupOldFiles();
    });
    ```

    Improves content and maintains system health.
  </Step>
</Steps>

## Customizing Your Workflow

### Change Posting Frequency

Edit your `.env` file:

```bash theme={null}
# Options: daily, every-2-days, 3-per-week, weekly
POSTING_FREQUENCY=daily

# Maintain content buffer (days ahead)
CONTENT_BUFFER_DAYS=3

# Maximum videos per day
MAX_DAILY_POSTS=1
```

### Configure Content Preferences

```bash theme={null}
# Target audience
CHANNEL_NAME=Your Channel Name
TARGET_AUDIENCE=Tech enthusiasts, developers

# Content settings
YOUTUBE_REGION=US
DEFAULT_PRIVACY_STATUS=public
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Setup fails with 'YouTube API quota exceeded'" icon="triangle-exclamation">
    **Solution**: Check your Google Cloud Console quotas:

    1. Go to [Google Cloud Console](https://console.cloud.google.com/)
    2. Navigate to **"APIs & Services"** → **"Quotas"**
    3. YouTube Data API v3 should have 10,000 units/day by default
    4. If exceeded, wait 24 hours or request quota increase
  </Accordion>

  <Accordion title="Content generation fails" icon="circle-exclamation">
    **Check**:

    ```bash theme={null}
    # Verify API keys are set
    cat .env | grep API_KEY

    # Check logs
    tail -f logs/application.log

    # Verify credentials
    npm run credentials:setup
    ```
  </Accordion>

  <Accordion title="Database errors" icon="database">
    **Reset database**:

    ```bash theme={null}
    # Backup first
    cp data/youtube_automation.db data/youtube_automation.backup.db

    # Reinitialize
    npm run db:init
    ```
  </Accordion>

  <Accordion title="Publishing fails" icon="upload">
    **Verify OAuth tokens**:

    1. Check `config/credentials.json` exists
    2. Ensure YouTube OAuth consent screen is configured
    3. Re-run authentication if needed

    ```bash theme={null}
    node authenticate.js
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="book" href="/installation">
    Deep dive into configuration and deployment options
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Complete API documentation and examples
  </Card>
</CardGroup>

<Note>
  **Success!** Your YouTube channel is now fully automated. The system will generate, optimize, and publish content according to your schedule.
</Note>