Video Thumbnail Generator

An automated Apify Actor that generates high-quality thumbnail images from video files. This Actor supports multiple video formats (MP4, AVI, MOV, WebM) and provides flexible thumbnail generation options with batch processing capabilities.

Features

• Multiple Format Support: MP4, AVI, MOV, WebM, and other FFmpeg-compatible formats
• Automatic Frame Extraction: Intelligently extracts visually appealing frames at optimal intervals
• Custom Timestamp Selection: Precise control over thumbnail generation with specific timestamps
• Batch Processing: Handle multiple videos simultaneously for efficient workflow integration
• Flexible Output Options: JPEG and PNG formats with customizable resolution and quality settings
• Video Metadata Extraction: Automatically captures video duration, resolution, codec, and bitrate information
• Scalable Processing: Configurable timeout and resource settings for various video sizes

Installation

1. Clone or download this repository
2. Ensure you have Node.js 20+ installed
3. Install dependencies:

   $npm install
   

Usage

Local Testing

Create an input.json file with your configuration:

{
  "videoUrls": [
    "https://example.com/video1.mp4",
    "https://example.com/video2.mp4"
  ],
  "thumbnailCount": 3,
  "outputFormat": "jpeg",
  "imageWidth": 320,
  "imageQuality": 85,
  "includeMetadata": true,
  "timeout": 300
}

Run the Actor locally:

$npm start

Apify Deployment

1. Push this code to your Apify Actor repository
2. The Actor will automatically build using the provided Dockerfile
3. Configure input parameters through the Apify Console UI (auto-generated from INPUT_SCHEMA.json)
4. Run the Actor and access results from the dataset and key-value store

Input Parameters

Parameter	Type	Required	Default	Description
videoUrls	Array	Yes	-	Array of video URLs to process
thumbnailCount	Integer	No	3	Number of thumbnails per video (1-10)
customTimestamps	Array	No	[]	Custom timestamps in seconds (overrides thumbnailCount)
outputFormat	String	No	jpeg	Output format: "jpeg" or "png"
imageWidth	Integer	No	320	Thumbnail width in pixels (160-1920)
imageQuality	Integer	No	85	JPEG quality (1-100, PNG only)
includeMetadata	Boolean	No	true	Extract and save video metadata
timeout	Integer	No	300	Processing timeout per video in seconds

Output

The Actor generates two types of outputs:

Dataset Records

Each thumbnail generates a dataset record with:

{
  "videoUrl": "https://example.com/video.mp4",
  "thumbnailUrl": "https://api.apify.com/v2/key-value-stores/...",
  "thumbnailKey": "thumbnail_abc123_0.jpeg",
  "timestamp": 10,
  "format": "jpeg",
  "width": 320,
  "height": 180,
  "fileSize": 12345,
  "processingTime": 5000,
  "metadata": {
    "duration": 120,
    "width": 1920,
    "height": 1080,
    "codec": "h264",
    "bitrate": "5000k",
    "fps": 30
  },
  "status": "success"
}

Key-Value Store

Thumbnail images are stored in the key-value store with keys like:

• thumbnail_abc123_0.jpeg
• thumbnail_abc123_1.jpeg
• thumbnail_abc123_2.jpeg

System Requirements

The Actor requires:

• Memory: Minimum 1024 MB (recommended 2048 MB)
• Timeout: 300-3600 seconds depending on video size
• Dependencies: FFmpeg and ImageMagick (included in Docker image)

Supported Video Formats

The Actor supports any video format compatible with FFmpeg:

• MP4 (H.264, H.265)
• AVI
• MOV
• WebM
• MKV
• FLV
• WMV
• And many others

Error Handling

The Actor includes robust error handling:

• Failed videos are logged with error messages
• Processing continues for remaining videos even if one fails
• Detailed error information is saved to the dataset
• Timeout protection prevents hanging on problematic videos

Performance Tips

1. Batch Processing: Process multiple videos in one run for better resource utilization
2. Image Width: Smaller widths (160-480px) process faster than larger dimensions
3. JPEG Format: Use JPEG for faster processing; PNG is slower but lossless
4. Thumbnail Count: Fewer thumbnails = faster processing
5. Custom Timestamps: Use specific timestamps instead of auto-distribution for known key moments

Troubleshooting

"Failed to download video"

• Verify the video URL is publicly accessible
• Check that the URL returns HTTP 200 status
• Ensure the URL is not behind authentication

"Could not determine video duration"

• The video file may be corrupted
• FFmpeg may not support this video format
• Try with a different video format

"Image conversion failed"

• ImageMagick may not have sufficient memory
• Try reducing the image width
• Check that the temporary directory has write permissions

License

MIT

Support

For issues, questions, or feature requests, please contact the Actor maintainer or submit an issue on the repository.

Version History

1.0.0

• Initial release
• Support for MP4, AVI, MOV, WebM formats
• Automatic and custom timestamp extraction
• Batch processing capabilities
• JPEG and PNG output formats
• Video metadata extraction