YouTube Viral Title & Description Generator

An Apify actor that analyzes YouTube videos or playlists and generates optimized, viral-ready titles and descriptions with emojis and hashtags.

Features

• 🎯 Video Analysis: Analyzes existing YouTube videos to identify improvement opportunities
• 📝 Viral Title Generation: Creates catchy, click-worthy titles optimized for YouTube SEO
• ✨ Optimized Descriptions: Generates descriptions with emojis, hashtags, and engaging content
• 📊 Playlist Support: Process entire playlists or individual videos
• 🤖 AI-Powered: Uses open-source Hugging Face models for intelligent content generation (100% free!)

Input Parameters

• youtubeUrl (required): URL of a YouTube video or playlist

  • Single Video: https://www.youtube.com/watch?v=VIDEO_ID
  • YouTube Shorts: https://www.youtube.com/shorts/VIDEO_ID
  • Playlist: https://www.youtube.com/playlist?list=PLAYLIST_ID
  • When a playlist URL is provided, the actor will analyze each video in the playlist and provide improvement suggestions for all videos

• huggingFaceApiKey (required): Your Hugging Face API key (required). Get one free at https://huggingface.co/settings/tokens. The router endpoint requires authentication.

• model (optional): Open-source AI model to use

  • Options: meta-llama/Llama-3.2-1B-Instruct (recommended), meta-llama/Llama-3.2-3B-Instruct, meta-llama/Llama-2-7b-chat-hf, microsoft/Phi-3-mini-4k-instruct
  • Default: meta-llama/Llama-3.2-1B-Instruct

• maxVideos (optional): Maximum number of videos to process from a playlist

  • Only applies when processing playlists - ignored for single videos
  • Default: 10
  • Range: 1-50
  • The actor will process up to this many videos from the playlist

Output

The actor returns an array of results. For playlists, you'll get one result object for each video in the playlist (up to maxVideos).

For each video, the actor returns:

{
  "videoId": "VIDEO_ID",
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "originalTitle": "Original video title",
  "originalDescription": "Original video description",
  "currentViews": "1,234 views",
  "currentLikes": "56",
  "channelName": "Channel Name",
  "duration": "10:30",
  "category": "Sports",
  "engagementRatio": "2.5%",
  "improvements": "Detailed analysis of what should be improved...",
  "viralTitle": "New optimized viral title 🚀",
  "viralDescription": "New description with emojis and call-to-action (hashtags provided separately)",
  "viralHashtags": "#fitness, #workout, #squats, #gym, #strengthtraining, #exercise, #fitnessmotivation"
}

Usage

Local Development

1. Install dependencies:

$npm install

2. Install Playwright browsers (if not already installed):

$npx playwright install chromium

3. Set up your input (create INPUT.json or use the provided example):

For a single video:

{
  "youtubeUrl": "https://www.youtube.com/watch?v=YOUR_VIDEO_ID",
  "huggingFaceApiKey": "hf_YOUR_API_KEY",
  "model": "meta-llama/Llama-3.2-1B-Instruct",
  "maxVideos": 1
}

For a playlist:

{
  "youtubeUrl": "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID",
  "huggingFaceApiKey": "hf_YOUR_API_KEY",
  "model": "meta-llama/Llama-3.2-1B-Instruct",
  "maxVideos": 10
}

4. Run the actor:

$npm start

Note: See TESTING.md for detailed local testing instructions and troubleshooting.

Apify Platform

1. Push the actor to Apify:

$apify push

2. Configure the actor in Apify Console with your input parameters

3. Run the actor and view results in the dataset

How It Works

1. URL Parsing: Extracts video IDs from the provided YouTube URL (supports single videos and playlists)

2. Web Scraping: Uses Playwright to scrape video metadata including:

   • Title and description
   • View count and engagement metrics
   • Channel information
   • Video duration

3. AI Analysis: Sends video data to Hugging Face Inference API (open-source models) with a specialized prompt informed by:

   • Tube Virality datasets: Trending video metadata patterns from multiple countries
   • YouTube Trending Videos Analytics: Historical viral content patterns
   • Regional viral content data: Cross-market trend analysis

   The AI uses these insights to:

   • Analyze what can be improved for better engagement
   • Generate viral, trending titles following proven patterns
   • Create optimized descriptions with strategic emojis and hashtags

4. Output: Returns structured data with original and optimized content

Requirements

• Node.js 18+
• Hugging Face API key (required - get one free at https://huggingface.co/settings/tokens)
• Apify account (for cloud deployment)

Notes

• The actor uses Playwright with headless browser to scrape YouTube
• Rate limiting is implemented with delays between requests
• YouTube's structure may change, requiring selector updates
• 100% Free: Uses open-source models via Hugging Face Inference API
• First request to a model may take longer as the model loads (cold start)
• Hugging Face free tier has rate limits; API key recommended for production use

Data Sources & Insights

The actor's AI analysis is informed by viral content patterns from:

• Tube Virality (GitHub): Open-source trending video data collector with daily metrics from multiple countries
• YouTube Trending Videos Analytics Dataset: Historical trending video data with views, likes, comments patterns
• Regional Viral Content Datasets: Cross-market trend analysis for better global reach

These insights help the AI understand:

• What makes titles click-worthy (curiosity gaps, emotional triggers, numbers)
• Optimal description structure (hook-first, strategic hashtags, emoji placement)
• Hashtag strategies that increase discoverability
• Engagement patterns from successful viral videos

License

ISC