Video Converter - Apify Actor

Converts one supplied video with FFmpeg, optionally extracts tracks or creates HLS/GIF/thumbnail derivatives, uploads the result to the selected destination, and writes a source-backed summary to the default dataset. Actual conversion requires FFmpeg and any credentials required by the selected source or destination.

What this actor does

The actor fetches one input video, probes it with ffprobe, performs a standard conversion, track extraction, HLS generation, or GIF generation, uploads the produced artifacts, and saves the final result to the dataset. It also writes the full success or error object to the fixed OUTPUT key in the default Apify Key-Value Store.

Code structure

The entrypoint in src/main.js only starts the Actor lifecycle. The workflow is split into focused modules: src/workflow.js orchestrates conversion, src/inputSource.js resolves input media, src/outputUploader.js handles destination uploads and HLS/track artifacts, and src/mediaSummary.js normalizes ffprobe facts and dataset records. Existing converter, handler, schema, and utility modules remain independently reusable.

Features

Input Sources

• URL: Direct video URLs with authentication support (Bearer, Basic, Custom Header)
• Google Drive: Download videos from Google Drive using file ID and service account
• Dropbox: Download videos from Dropbox shared links
• Cloud Storage: AWS S3, Google Cloud Storage
• Apify Storage: Load videos from Apify Key-Value Store

Output Formats

• Video: MP4, MOV, WEBM, MKV, AVI
• Animation: GIF
• Streaming: HLS (HTTP Live Streaming), opt-in

Video Codecs

• H.264/AVC - Most compatible
• H.265/HEVC - Better compression
• VP8/VP9 - WebM/Open format
• AV1 - Newest, best compression

Audio Codecs

• AAC - Most compatible
• MP3 - Universal support
• Opus - Best quality/compression
• Vorbis - Open format

Output Destinations

• Apify Key-Value Store - Default, provides public URL
• AWS S3 - Amazon Simple Storage Service
• Google Cloud Storage (GCS) - Google's object storage
• Dropbox - Upload to Dropbox account

Advanced Features

• Track Extractor - Split video into separate video, audio, and subtitle files
• Video trimming/cutting
• Watermarks (text and image)
• Audio controls (volume, mute, replace audio)
• Thumbnail generation
• GIF preview generation
• Webhooks (URL only or with file attachment)

Input Examples

Basic URL Input

{
    "inputType": "url",
    "videoUrl": "https://example.com/video.mp4",
    "outputFormat": "mp4",
    "videoCodec": "h264",
    "audioCodec": "aac",
    "quality": "medium",
    "outputDestination": "apify"
}

URL with Bearer Token Authentication

{
    "inputType": "url",
    "videoUrl": "https://api.example.com/protected/video.mp4",
    "urlAuthType": "bearer",
    "urlAuthBearerToken": "your-api-token",
    "outputFormat": "mp4"
}

URL with Basic Auth

{
    "inputType": "url",
    "videoUrl": "https://secure.example.com/video.mp4",
    "urlAuthType": "basic",
    "urlAuthUsername": "user",
    "urlAuthPassword": "pass",
    "outputFormat": "webm"
}

URL with Custom Header Auth

{
    "inputType": "url",
    "videoUrl": "https://api.example.com/video.mp4",
    "urlAuthType": "header",
    "urlAuthHeaderName": "X-API-Key",
    "urlAuthHeaderValue": "your-api-key",
    "outputFormat": "mp4"
}

Google Drive Input

{
    "inputType": "googleDrive",
    "googleDriveFileId": "1abc123def456",
    "googleDriveCredentials": {
        "private_key": "-----BEGIN PRIVATE KEY-----...",
        "client_email": "service@project.iam.gserviceaccount.com"
    },
    "outputFormat": "mp4"
}

Dropbox Input

{
    "inputType": "dropbox",
    "dropboxFileUrl": "https://www.dropbox.com/s/abc123/video.mp4?dl=0",
    "dropboxAccessToken": "your-dropbox-token",
    "outputFormat": "webm"
}

HLS Output

{
    "inputType": "url",
    "videoUrl": "https://example.com/video.mp4",
    "outputFormat": "hls",
    "videoCodec": "h264",
    "audioCodec": "aac"
}

Output Destination Examples

AWS S3 Upload

{
    "outputDestination": "s3",
    "s3Bucket": "my-video-bucket",
    "s3Region": "us-east-1",
    "s3AccessKeyId": "AKIA...",
    "s3SecretAccessKey": "...",
    "s3Path": "converted/video.mp4"
}

Google Cloud Storage Upload

{
    "outputDestination": "gcs",
    "gcsBucket": "my-gcs-bucket",
    "gcsCredentials": {
        "type": "service_account",
        "project_id": "your-project",
        "private_key": "-----BEGIN PRIVATE KEY-----...",
        "client_email": "service@project.iam.gserviceaccount.com"
    },
    "gcsPath": "videos/output.mp4"
}

Dropbox Upload

{
    "outputDestination": "dropbox",
    "dropboxAccessToken": "your-dropbox-token",
    "dropboxPath": "/Videos/converted.mp4"
}

Webhook Configuration

URL Only Webhook (Default)

Sends JSON payload with video URL and metadata:

{
    "webhookUrl": "https://api.example.com/webhook",
    "webhookAuthHeader": "Bearer webhook-secret"
}

Webhook with Video File

Sends multipart form data with actual video file attached:

{
    "webhookUrl": "https://api.example.com/upload",
    "webhookSendFile": true,
    "webhookFileFieldName": "video",
    "webhookAuthHeader": "Bearer webhook-secret"
}

Webhook Payload Structure (URL Only)

{
    "status": "success",
    "downloadUrl": "https://api.apify.com/v2/key-value-stores/.../records/video.mp4",
    "outputProvider": "apify",
    "inputFormat": "mp4",
    "outputFormat": "webm",
    "duration": 120.5,
    "fileSize": 15234567,
    "executionTime": 45.2,
    "thumbnails": [],
    "timestamp": "2024-01-15T10:30:00.000Z",
    "metadata": {
        "videoCodec": "vp9",
        "audioCodec": "opus",
        "resolution": "1920x1080"
    }
}

Advanced Processing

Video Trimming

{
    "trimStart": "00:00:30",
    "trimEnd": "00:02:00"
}

Add Text Watermark

{
    "watermarkEnabled": true,
    "watermarkType": "text",
    "watermarkText": "© My Company",
    "watermarkPosition": "bottom-right",
    "watermarkOpacity": "0.8",
    "watermarkFontSize": 24,
    "watermarkFontColor": "white"
}

Add Image Watermark

{
    "watermarkEnabled": true,
    "watermarkType": "image",
    "watermarkImageUrl": "https://example.com/logo.png",
    "watermarkPosition": "top-left",
    "watermarkOpacity": "0.5"
}

Generate Thumbnails

{
    "thumbnailsEnabled": true,
    "thumbnailsCount": 5,
    "thumbnailsFormat": "jpg",
    "thumbnailsWidth": 640
}

Generate GIF Preview

{
    "gifPreviewEnabled": true,
    "gifPreviewStartTime": "00:00:05",
    "gifPreviewDuration": 3,
    "gifPreviewWidth": 480,
    "gifPreviewFps": 10
}

Audio Controls

{
    "audioVolume": "1.5",
    "audioNormalize": true,
    "audioReplaceUrl": "https://example.com/music.mp3"
}

HLS Streaming Output

HLS is opt-in. Set outputFormat to hls to create a playlist and segments:

{
    "inputType": "url",
    "videoUrl": "https://example.com/video.mp4",
    "outputFormat": "hls",
    "videoCodec": "h264",
    "audioCodec": "aac"
}

Track Extractor

The extractor feature allows you to split a video file into separate video, audio, and subtitle tracks. This is useful for:

• Extracting audio from videos (e.g., for podcasts or music)
• Getting video without audio (for adding custom audio later)
• Extracting embedded subtitles/captions

Basic Extraction - All Tracks

{
    "inputType": "url",
    "videoUrl": "https://example.com/movie.mkv",
    "extractorEnabled": true,
    "extractorExtractVideo": true,
    "extractorExtractAudio": true,
    "extractorExtractSubtitles": true
}

Extract Audio Only (MP3)

{
    "inputType": "url",
    "videoUrl": "https://example.com/video.mp4",
    "extractorEnabled": true,
    "extractorExtractVideo": false,
    "extractorExtractAudio": true,
    "extractorExtractSubtitles": false,
    "extractorAudioFormat": "mp3",
    "extractorAudioBitrate": "320k"
}

Extract Audio as High-Quality FLAC

{
    "inputType": "url",
    "videoUrl": "https://example.com/concert.mp4",
    "extractorEnabled": true,
    "extractorExtractVideo": false,
    "extractorExtractAudio": true,
    "extractorAudioFormat": "flac"
}

Extract Video Without Audio

{
    "inputType": "url",
    "videoUrl": "https://example.com/video.mp4",
    "extractorEnabled": true,
    "extractorExtractVideo": true,
    "extractorExtractAudio": false,
    "extractorVideoCodec": "copy"
}

Extractor Output Example

When extraction is complete, the output includes URLs for each extracted track:

{
    "status": "success",
    "extractedTracks": {
        "videoUrl": "https://api.apify.com/v2/key-value-stores/.../records/video_video.mp4",
        "audioUrl": "https://api.apify.com/v2/key-value-stores/.../records/video_audio.mp3",
        "subtitleUrls": [
            {
                "url": "https://api.apify.com/v2/key-value-stores/.../records/video_subtitle_eng.srt",
                "language": "eng",
                "title": "English",
                "index": 0
            }
        ]
    },
    "streamInfo": {
        "hasVideo": true,
        "hasAudio": true,
        "hasSubtitles": true,
        "streams": {
            "video": [{ "codec": "h264", "width": 1920, "height": 1080 }],
            "audio": [{ "codec": "aac", "channels": 2, "sampleRate": "48000" }],
            "subtitle": [{ "codec": "subrip", "language": "eng" }]
        }
    }
}

Extractor Parameters

Parameter	Type	Default	Description
extractorEnabled	Boolean	false	Enable extractor mode
extractorExtractVideo	Boolean	true	Extract video track (without audio)
extractorExtractAudio	Boolean	true	Extract audio track
extractorExtractSubtitles	Boolean	true	Extract subtitle/caption tracks
extractorVideoCodec	String	copy	Video codec (h264, h265, vp9, copy)
extractorAudioFormat	String	mp3	Audio format (mp3, aac, wav, flac, ogg, opus)
extractorAudioBitrate	String	-	Audio bitrate (e.g., 128k, 320k)
extractorSubtitleFormat	String	srt	Subtitle format (srt, ass, vtt)

Input Parameters Reference

Parameter	Type	Required	Default	Description
inputType	String	Yes	url	url, dropbox, googleDrive, cloudStorage, apifyStorage
videoUrl	String	Conditional	-	Video URL (required for url input)
urlAuthType	String	No	none	none, bearer, basic, header
outputFormat	String	Yes	hls	mp4, mov, webm, mkv, avi, gif, hls
videoCodec	String	No	h264	h264, h265, vp8, vp9, av1, copy
audioCodec	String	No	aac	aac, mp3, opus, vorbis, copy, none
quality	String	No	medium	low, medium, high, veryhigh
preset	String	No	medium	FFmpeg preset (affects speed/quality)
outputDestination	String	No	apify	apify, s3, gcs, dropbox
webhookUrl	String	No	-	Webhook URL for notifications
webhookSendFile	Boolean	No	false	Send video file in webhook

Output

The Actor saves results to:

1. Apify Dataset - Conversion results and metadata
2. Apify Key-Value Store - Converted video file (if outputDestination is apify)
3. OUTPUT Key - Full result object

Output Structure

{
    "status": "success",
    "inputSource": "url",
    "inputFormat": "mp4",
    "outputFormat": "webm",
    "outputUrl": "https://api.apify.com/v2/key-value-stores/.../records/video.webm",
    "outputDestination": "apify",
    "outputFileSizeBytes": 12345678,
    "outputDurationSeconds": 120.5,
    "executionTimeSeconds": 45.2,
    "thumbnails": [],
    "timestamp": "2024-01-15T10:30:00.000Z"
}

Supported Input Formats

• MP4, MOV, AVI, MKV, WEBM, FLV, WMV, 3GP, OGV

Resource Requirements

• Memory: 4096 MB recommended for HD video
• CPU: 1-4 cores depending on video length

Output schema and storage

The default dataset contains one successful result record with source media facts, output facts, the primary URL, optional thumbnail/GIF/HLS links, and optional extracted-track or stream information. The OUTPUT key contains the same result object on success or an error summary on failure. Uploaded binaries use generated or configured keys in the same key-value store and are not dataset rows.

Cost and limits

Runtime depends on input duration, resolution, codec, processing mode, and upload destination. Large conversions need more memory and may create multiple stored artifacts. External storage, webhook, proxy, and API charges are controlled by the services you configure.

FAQ

Is HLS the default?

No. Standard MP4 conversion is the default. Set outputFormat to hls to create a playlist and segments.

What happens when conversion fails?

The actor writes an error object to OUTPUT, cleans temporary files, and rethrows the error so the run is marked failed. A failed conversion does not create a successful dataset result.

Does the actor keep temporary source files?

Temporary working files are cleaned up after the run. Persisted files depend on the selected output destination and options such as thumbnails, GIF previews, HLS, or track extraction.

Disclaimer

Use only media you are authorized to download, transform, and redistribute. Follow copyright, privacy, licensing, and third-party storage requirements. Never place long-lived credentials in public input or logs.

License

MIT