youtube-automation/DIRECTUS_FLOW_SETUP.md

Directus Flow Setup Guide - YouTube Thumbnail Automation

Overview

This guide sets up a Directus Flow to automatically extract YouTube thumbnails when media_items are created or updated with type = youtube_video or youtube.

Prerequisites

1. Access to your Directus admin at https://enias.zeabur.app/admin
2. Admin permissions to create flows and modify collections

Step 1: Add youtube_thumbnail Field to media_items Collection

1. Go to Settings → Data Model → media_items
2. Click Create Field
3. Configure the field:
   • Field Name: youtube_thumbnail
   • Type: File
   • Interface: File (Image)
   • Display Template: Show thumbnail preview in layouts
   • Required: No
   • Default: null

Step 2: Create the YouTube Automation Flow

2.1 Create New Flow

1. Go to Settings → Flows
2. Click Create Flow
3. Configure basic settings:
   • Name: "YouTube Thumbnail Auto-Population"
   • Status: Active
   • Icon: smart_display (or video icon)
   • Color: #FF0000 (YouTube red)
   • Description: "Automatically extract and populate YouTube thumbnails"

2.2 Configure Trigger

1. Click Add Trigger
2. Select Event Hook trigger
3. Configure trigger:
   • Scope: Items
   • Actions: Update, Create
   • Collections: media_items

2.3 Add Filter Condition

In the trigger configuration, add a filter condition:

{
  "$and": [
    {
      "$or": [
        { "type": { "_eq": "youtube_video" } },
        { "type": { "_eq": "youtube" } }
      ]
    },
    {
      "url": { "_nnull": true }
    }
  ]
}

2.4 Create Operations

Operation 1: Extract Video ID (Run Script)

1. Add Run Script operation
2. Name: "Extract YouTube Video ID"
3. Code:

// Extract YouTube video ID from URL
function extractYouTubeId(url) {
  if (!url) return null;
  
  // Handle different YouTube URL formats
  const patterns = [
    /(?:youtube\.com\/watch\?v=)([a-zA-Z0-9_-]{11})/,
    /(?:youtu\.be\/)([a-zA-Z0-9_-]{11})/,
    /(?:youtube\.com\/embed\/)([a-zA-Z0-9_-]{11})/,
    /(?:youtube\.com\/v\/)([a-zA-Z0-9_-]{11})/
  ];
  
  for (const pattern of patterns) {
    const match = url.match(pattern);
    if (match) return match[1];
  }
  
  return null;
}

const videoId = extractYouTubeId($trigger.payload.url);
if (!videoId) {
  throw new Error('Could not extract YouTube video ID from URL: ' + $trigger.payload.url);
}

// Generate thumbnail URLs with quality fallback
const thumbnailUrls = [
  `https://img.youtube.com/vi/${videoId}/maxresdefault.jpg`,
  `https://img.youtube.com/vi/${videoId}/hqdefault.jpg`, 
  `https://img.youtube.com/vi/${videoId}/mqdefault.jpg`,
  `https://img.youtube.com/vi/${videoId}/default.jpg`
];

module.exports = {
  video_id: videoId,
  thumbnail_urls: thumbnailUrls
};

Operation 2: Download & Upload Thumbnail (Run Script)

1. Add Run Script operation
2. Name: "Download and Upload Thumbnail"
3. Code:

const axios = require('axios');

// Download thumbnail and upload to Directus
async function downloadAndUploadThumbnail(thumbnailUrls, videoId) {
  // Try each thumbnail URL until we find one that works
  for (const url of thumbnailUrls) {
    try {
      // Download thumbnail
      const response = await axios.get(url, { 
        responseType: 'arraybuffer',
        timeout: 10000,
        headers: {
          'User-Agent': 'Mozilla/5.0 (compatible; DirectusBot/1.0)'
        }
      });
      
      if (response.status === 200 && response.data.length > 1000) { // Ensure it's a valid image
        // Upload to Directus files collection
        const fileData = {
          title: `YouTube Thumbnail - ${videoId}`,
          filename_download: `youtube_${videoId}.jpg`,
          type: 'image/jpeg',
          storage: 'local',
          data: Buffer.from(response.data).toString('base64')
        };
        
        const uploadResult = await $directus.files.createOne(fileData);
        return uploadResult.id;
      }
    } catch (error) {
      console.log(`Failed to download from ${url}:`, error.message);
      continue; // Try next URL
    }
  }
  
  throw new Error('Failed to download thumbnail from any source');
}

const fileId = await downloadAndUploadThumbnail(
  $last.thumbnail_urls,
  $last.video_id
);

module.exports = { thumbnail_file_id: fileId };

Operation 3: Update Media Item (Update Data)

1. Add Update Data operation
2. Configure:
   • Collection: media_items
   • Key: {{$trigger.key}}
   • Payload:

     {
       "youtube_thumbnail": "{{$last.thumbnail_file_id}}"
     }
     

Step 3: Test the Flow

Test Data

Create or update a media_items record with:

• type: "youtube_video"
• url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Expected Result

The Flow should automatically:

1. Extract video ID: dQw4w9WgXcQ
2. Download the best available thumbnail
3. Upload it to Directus files
4. Update the youtube_thumbnail field with the file reference

Step 4: Verify Integration

1. Check Activity tab for flow execution logs
2. Verify youtube_thumbnail field is populated
3. Confirm thumbnail displays in collection layouts
4. Test with different YouTube URL formats

Troubleshooting

Common Issues

1. Flow not triggering: Check filter conditions and collection name
2. Thumbnail download fails: YouTube may block requests - add retry logic
3. File upload fails: Check Directus storage configuration
4. Permission errors: Ensure flow has file creation permissions

Debug Tips

1. Enable flow logging in Settings
2. Check Activity logs for error details
3. Test operations individually
4. Verify field permissions and data types

Alternative Approach: HTTP Request Operation

If the Run Script approach doesn't work, you can use HTTP Request operations:

1. HTTP Request to download thumbnail
2. HTTP Request to upload to Directus files API
3. Update Data to link the file

This approach uses the REST API instead of the JavaScript SDK.