Video/Audio Metadata Extractor

Extract comprehensive metadata from video and audio files using FFmpeg/FFprobe. Perfect for content creators, podcast producers, media managers, and developers who need structured media file information without technical complexity.

🎯 What it does

This Actor extracts detailed metadata from media files including:

• Duration (seconds)
• Bitrate (kbps)
• Codec information
• Resolution (for video files)
• Frame rate/FPS (for video files)
• Audio channels (for audio files)
• File size and format
• Optional thumbnails from video files

🚀 Quick Start

Input

{
  "mediaUrl": "https://www.w3schools.com/html/mov_bbb.mp4",
  "extractThumbnail": true
}

Output

{
  "duration": 10.027,
  "bitrate": 629,
  "codec": "h264",
  "resolution": "320x176",
  "fps": 25,
  "fileSize": 788493,
  "format": "mov,mp4,m4a,3gp,3g2,mj2",
  "audioChannels": 2,
  "thumbnailUrl": "https://api.apify.com/v2/key-value-stores/.../thumbnail.jpg",
  "sourceUrl": "https://www.w3schools.com/html/mov_bbb.mp4"
}

📋 Input Parameters

Parameter	Type	Required	Default	Description
mediaUrl	string	Yes	-	URL to video or audio file (HTTP/HTTPS)
extractThumbnail	boolean	No	false	Extract video thumbnail at 00:00:01

📊 Output Fields

Field	Type	Description
duration	number	Duration in seconds
bitrate	number	Bitrate in kbps
codec	string	Video or audio codec (e.g., h264, aac)
resolution	string	Video resolution (e.g., "1920x1080")
fps	number	Frames per second (video only)
fileSize	number	File size in bytes
format	string	Container format
audioChannels	number	Number of audio channels
thumbnailUrl	string	URL to extracted thumbnail (if requested)
sourceUrl	string	Original media file URL

💰 Pricing

This Actor uses pay-per-event pricing:

• Actor Start: $0.01 (one-time charge when processing begins)
• Successful Extraction: $0.005 per successfully processed media file

You only pay for what you use. No charges for failed processing or errors.

🎬 Supported Formats

Video Formats

• MP4, MOV, AVI, MKV, WebM, FLV, WMV, MPEG, 3GP
• H.264, H.265/HEVC, VP8, VP9, AV1 codecs

Audio Formats

• MP3, AAC, WAV, FLAC, OGG, M4A, WMA
• Various audio codecs and bitrates

Image/Thumbnail Output

• JPEG format
• Extracted at 1-second timestamp
• Stored in Apify Key-Value Store

🔧 Technical Details

• Runtime: Node.js 22 with TypeScript
• Media Processing: FFmpeg/FFprobe
• Download Timeout: 2 minutes per file
• Maximum File Size: Limited by available memory (typically 2GB)
• Error Handling: Graceful degradation with detailed error messages

📖 Use Cases

Podcast Hosts

Automatically extract episode duration, format, and technical specs for publishing platforms.

Video Creators

Batch process video libraries to generate metadata for content management systems.

Music Platforms

Analyze audio files for codec compatibility and streaming optimization.

Content Agencies

Track video metrics (resolution, FPS, duration) for client reporting and quality control.

Developers

Integrate media analysis into workflows without managing FFmpeg infrastructure.

⚡ Performance

• Processing Speed: Typically 2-10 seconds per file (depending on file size)
• Concurrent Processing: Single file per run (optimized for reliability)
• Memory Usage: Efficient streaming for large files
• Automatic Cleanup: Temporary files removed after processing

🛡️ Error Handling

The Actor handles various error scenarios:

• Invalid URLs
• Network timeouts
• Unsupported file formats
• Corrupted media files
• FFmpeg processing errors

All errors are logged and returned in the output dataset for debugging.

🔍 Example Results

Video File Example

{
  "duration": 120.5,
  "bitrate": 2500,
  "codec": "h264",
  "resolution": "1920x1080",
  "fps": 30,
  "fileSize": 37821450,
  "format": "mp4",
  "audioChannels": 2,
  "thumbnailUrl": "https://api.apify.com/v2/.../thumbnail.jpg",
  "sourceUrl": "https://example.com/video.mp4"
}

Audio File Example

{
  "duration": 180.25,
  "bitrate": 192,
  "codec": "mp3",
  "fileSize": 4325400,
  "format": "mp3",
  "audioChannels": 2,
  "sourceUrl": "https://example.com/podcast.mp3"
}

🚀 Getting Started

1. Input your media URL (video or audio file)
2. Optionally enable thumbnail extraction for video files
3. Run the Actor and receive structured metadata
4. Access results in the Apify dataset or via API

💡 Tips

• Use direct file URLs for best performance
• Enable thumbnail extraction only for video files
• Check the dataset for error messages if processing fails
• Large files may take longer to process

🔗 Resources

• Apify SDK Documentation
• FFmpeg Documentation
• Apify Platform

📞 Support

For issues, questions, or feature requests, please contact support or create an issue in the project repository.

---

Ready to extract media metadata? Start using the Video/Audio Metadata Extractor today!