# Merge Videos: Concatenate, Join & Combine Video Clips (`data-done-right/video-concat-merger`) Actor

Merge video clips from direct URLs into one MP4, in the order you list them. Re-encodes to a common size and frame rate, optional crossfade (0-2 s), loudness normalising and background music. Signed download link per merged video. Direct files only, no YouTube.

- **URL**: https://apify.com/data-done-right/video-concat-merger.md
- **Developed by:** [Data Done Right](https://apify.com/data-done-right) (community)
- **Categories:** Videos, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $64.00 / 1,000 video mergeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Merge Videos: Concatenate, Join & Combine Video Clips

This tool lets you **merge videos** from direct video file URLs: list the clips in the order they should play and it **concatenates them into one MP4**, converting clips with different sizes, frame rates or formats to one common format. You can add a **crossfade** of 0 to 2 seconds between clips, level the loudness, and lay a **background music track** under the result. It runs ffmpeg in the cloud, so there is nothing to install and no API key.

> **What it does not do.** It reads **direct video files** (mp4, mov, webm, mkv, avi) from a public URL. It **does not download from YouTube, Vimeo, TikTok, Instagram or other streaming sites** and rejects those links without charge. HLS/DASH playlists (.m3u8, .mpd) are not supported. It **always re-encodes** (H.264 + AAC), it never does a lossless stream copy, and the output is always MP4. It does not edit, trim, add titles, captions or watermarks. It does not fetch files that a site's robots.txt disallows. It has no proxy support and does not work around blocks or logins. Use it only on videos and music you own or have the right to process.

**What you get**

- One dataset row per merged video: a signed download link, measured duration, size, frame rate, per-input details and a status or a clear error.
- A merge never silently drops a clip: if any input fails, the merge fails with a reason per input and costs nothing (or set `skipFailedInputs` to merge the rest and be told which were left out).
- Failed, skipped and rejected merges are free.

### How to merge videos from URLs

1. Paste two or more **direct video URLs** in `videoUrls`, in playing order. The same URL may appear more than once; it is downloaded once and played each time.
2. Run it. Open the dataset: the row has a `url` to the merged MP4 and an `inputs` list that shows what each clip was (length, size, frame rate, sound).
3. Optional: set `crossfadeSeconds`, `normalizeAudio`, `musicUrl`, `width` / `height` / `fps`. The defaults take the size and frame rate of the first clip.

### How to join videos with different sizes or frame rates

Every clip is scaled to one output size and converted to one frame rate before joining. By default the output takes the size and frame rate of the **first** clip; set `width`, `height` and `fps` to choose your own. `fit: pad` keeps the whole picture and adds black bars where the shapes differ, `fit: crop` fills the frame and cuts the edges. A clip without sound gets silence of its own length, so the audio stays in sync. If none of the clips has sound (and there is no music), the result has no audio track.

### How to add a crossfade between clips

Set `crossfadeSeconds` between 0 and 2 (for example `0.5`). Each join then overlaps the end of one clip with the start of the next, with a video and audio fade, so the merged video is shorter than the clips added up by the crossfade times the number of joins. In a local test, two clips of 5.005 s and 5.059 s with a 1 s crossfade produced a 9.1 s file. Every clip must be at least twice as long as the crossfade; a shorter clip makes the merge fail (free) with a message naming it.

### How to add background music to merged videos

Set `musicUrl` to a direct audio link (mp3, wav, m4a, flac, ogg) and `musicVolume` (0 to 1, default 0.25). The track is looped or cut to the length of the merged video and fades out over the last 2 seconds. With `normalizeAudio` on, the clips' sound is levelled to about -16 LUFS first and the music is mixed in afterwards. Loudness levelling is a single pass, so it is approximate. A video with no sound of its own gets the music as its only audio.

### Input

| Field | Default | What it does |
|---|---|---|
| `videoUrls` | 2 sample videos | Direct video links in playing order (two or more). |
| `merges` | empty | More merged videos in the same run: `[{"name", "videoUrls", "musicUrl", "crossfadeSeconds"}]`. |
| `crossfadeSeconds` | 0 | Fade between clips, 0 to 2 s (0 = hard cut). |
| `normalizeAudio` | off | Level the clips' loudness to about -16 LUFS. |
| `musicUrl` / `musicVolume` | none / 0.25 | Background music track and its volume. |
| `width` / `height` | 0 / 0 | Output size (0 = first clip's size; max 3840 x 2160). |
| `fit` | `pad` | `pad` (black bars) or `crop` (fill the frame). |
| `fps` | 0 | Output frame rate (0 = first clip's, max 60). |
| `crf` | 23 | H.264 quality (16 best, 35 smallest). |
| `audioBitrateKbps` | 192 | AAC bitrate. |
| `skipFailedInputs` | off | Merge the inputs that worked instead of failing the whole merge. |
| `maxInputsPerVideo` | 20 | Inputs per merged video (max 50). |
| `maxTotalMinutes` | 5 | Added-up length of the inputs of one merge (max 60). |
| `maxMergesPerRun` | 20 | Hard cap on merged videos per run (max 500). |
| `maxVideoSizeMb` | 500 | Size cap per input file (max 2048). |
| `maxTotalDownloadMb` | 2048 | Cap on everything downloaded for one merge (max 8192). |
| `videoTimeoutSecs` | 600 | Timeout per download. |
| `encodeTimeoutMinutes` | 30 | Time allowed for joining one merged video. |
| `outputStoreName` | empty | Save merged videos in a named store that is kept until you delete it. |

Input example:

```json
{
  "videoUrls": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm"
  ],
  "crossfadeSeconds": 1,
  "normalizeAudio": true,
  "musicUrl": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
  "musicVolume": 0.3,
  "width": 1280,
  "height": 720
}
```

### Output

From a real local run of the input above (two real downloads, about 3 s in total; the `inputs` list is shortened here to one entry):

```json
{
  "mergeIndex": 1, "name": null, "inputCount": 2, "inputsMerged": 2,
  "totalInputSeconds": 10.064, "crossfadeSeconds": 1.0, "normalizedAudio": true, "backgroundMusic": true,
  "durationSeconds": 9.1, "width": 1280, "height": 720, "fps": 29.97, "hasAudio": true, "format": "mp4",
  "bytes": 1242064,
  "url": "https://api.apify.com/v2/key-value-stores/<store>/records/merged-01.mp4",
  "key": "merged-01.mp4", "status": "ok", "error": null, "note": null,
  "inputs": [
    {"index": 2, "url": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm", "status": "ok",
     "durationSeconds": 5.059, "width": 960, "height": 540, "fps": 29.97, "hasAudio": true, "sizeBytes": 554058,
     "error": null, "videoCodec": "vp8", "audioCodec": "vorbis"}
  ],
  "processingSecs": 2.1
}
```

A merge that cannot be made gives one row with `status: "error"`, the reason in `error` and the state of every input in `inputs`, for example `1 of 3 inputs could not be used, so nothing was merged (input 2: download failed: HTTP 404)`. On Apify the `url` is a signed link that downloads without a token. `status` is `ok`, `error` or `skipped` (spending limit or `maxMergesPerRun` reached). The `SUMMARY` record lists every merge.

### Use with the Apify API, MCP, n8n and Make

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("data-done-right/video-concat-merger").call(run_input={
    "videoUrls": ["https://example.com/intro.mp4", "https://example.com/main.mp4", "https://example.com/outro.mp4"],
    "crossfadeSeconds": 0.5, "width": 1920, "height": 1080})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["status"], row["url"] or row["error"])
```

JavaScript:

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: '<APIFY_TOKEN>' });
const run = await client.actor('data-done-right/video-concat-merger').call({
  videoUrls: ['https://example.com/a.mp4', 'https://example.com/b.mp4'] });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

In n8n or Make use the Apify node with the actor name and the same JSON. With Apify's MCP server (mcp.apify.com) an AI assistant can call it: "join these three mp4 files into one video". Only the video URLs are needed.

### Use cases

- Stitch the segments an AI video or text-to-video pipeline produces into one finished video.
- Join intro, main recording and outro into one file for upload.
- Combine screen recordings or webinar parts into a single video.
- Add a music bed under a sequence of short clips.
- Assemble many videos from lists in one run with `merges`.

### How much does it cost

Pay per event: **$0.02 per merged video delivered** (`video-merged`, $20 per 1,000). Failed and skipped merges, rejected links and the `SUMMARY` record are free. Plan discounts apply (Silver about 10%, Gold and higher about 20%).

- 100 merged videos: $2.
- 1,000 merged videos: $20.
- 10,000 merged videos: $200.

The price is per merged video whatever the number of inputs, the crossfade or the music; Apify platform usage is included. `maxMergesPerRun` caps a run, and if you set a maximum spend per run the Actor stops cleanly when it is reached and removes the file it could not charge for. Because every clip is re-encoded, long or high-resolution merges take longer, which is why `maxTotalMinutes` defaults to 5 (raise it up to 60).

### FAQ

#### Can it merge YouTube videos?

No. YouTube, Vimeo, TikTok, Instagram and other streaming-site links are rejected with a message and no charge. Use a direct link to a video file that you have the rights to.

#### Is the merge lossless?

No. Every clip is decoded and re-encoded to H.264 (CRF 23 by default) and AAC, so there is one generation of compression. Use `crf` 18 for near-lossless quality, at the cost of a larger file. The Actor does not do a stream copy.

#### What if my clips have different sizes, frame rates or codecs?

That is the normal case. All clips are scaled to one size (the first clip's unless you set `width` and `height`), converted to one frame rate and to stereo 48 kHz audio. Mixed MP4 and WebM inputs worked in local tests, as did a clip without sound and different frame rates (15, 25, 30 fps).

#### What happens if one of the inputs fails?

By default the whole merge fails, costs nothing, and the row names the input and the reason, so you never get a video with a missing part by accident. Turn on `skipFailedInputs` to merge the inputs that worked; the row's `note` says which were left out.

#### Why was a file not fetched although the link works in my browser?

The Actor reads robots.txt of the host before fetching a file and skips files it disallows (or when robots.txt cannot be read because the server errors). A missing robots.txt means everything is allowed. It identifies itself as `VideoConcatMerger`, does not use proxies, and does not try to get around blocks.

#### Which limits apply?

Two to 50 inputs per merged video (default 20), at most 60 minutes of input per merge (default 5), up to 2 GB per file and 8 GB downloaded per merge (defaults 500 MB and 2 GB), output up to 3840 x 2160, up to 60 fps, up to 500 merges per run. Links to private or internal addresses are blocked. Whole files are downloaded first, so very large inputs take time.

#### How long are the merged files kept?

Merged files live in the run's key-value store, which expires with your plan's retention period. Set `outputStoreName` to keep them in a named store until you delete them.

### Related tools

- **Video Frame Extractor: Keyframes, Scenes & Thumbnails for AI** pulls still images from the same videos.
- **Cut Video: Video Trimmer, Clip Cutter & Video to GIF** cuts the clips you want before you merge them.
- **Extract Audio from Video: MP3, WAV & FLAC in Bulk** turns a merged video into an audio file.
- **Video Converter & Compressor: MP4, WebM, GIF, MP3, Images** converts or shrinks the merged file.

# Actor input Schema

## `videoUrls` (type: `array`):

Direct links to video files (mp4, mov, webm, mkv, avi), in the order they should play. Example: https://example.com/part1.mp4. Two or more. The same URL may appear twice. YouTube, Vimeo, TikTok and other streaming-site page links are rejected, with no charge. Files that robots.txt disallows are not fetched.

## `merges` (type: `array`):

Optional extra merged videos, each its own list: \[{"name": "promo", "videoUrls": \["https://example.com/a.mp4", "https://example.com/b.mp4"], "musicUrl": "https://example.com/track.mp3", "crossfadeSeconds": 1}]. Only videoUrls is required per entry; name, musicUrl and crossfadeSeconds override the run-level settings for that merge. Each merge is one charged video. Runs in addition to 'Video URLs'.

## `crossfadeSeconds` (type: `number`):

Length of the fade between clips, 0 to 2 seconds. 0 = hard cut. Example: 0.5. Every clip must be at least twice as long as the crossfade. The merged video is shorter than the sum of the clips by the crossfade times the number of joins.

## `normalizeAudio` (type: `boolean`):

Even out the volume of the joined audio to about -16 LUFS (single-pass EBU R128 loudnorm, approximate). Applied to the sound of the clips before background music is mixed in.

## `musicUrl` (type: `string`):

Optional direct link to an audio file (mp3, wav, m4a, flac, ogg). Example: https://example.com/track.mp3. It is looped or cut to the length of the merged video and fades out over the last 2 seconds. Use music you have the rights to.

## `musicVolume` (type: `number`):

Volume of the background music relative to its original level, 0 to 1. Example: 0.25 sits quietly under speech.

## `width` (type: `integer`):

Width of the merged video in pixels. 0 = the size of the first clip. Every clip is scaled to this size. Example: 1280. With only a width, the height follows the first clip's aspect ratio. Maximum 3840.

## `height` (type: `integer`):

Height of the merged video in pixels. 0 = the size of the first clip. Example: 720. Maximum 2160.

## `fit` (type: `string`):

How a clip with a different aspect ratio is fitted into the output size.

## `fps` (type: `number`):

Frames per second of the merged video, 1 to 60. 0 = the frame rate of the first clip (25 if unknown). Example: 30. Clips with another rate are converted.

## `crf` (type: `integer`):

H.264 quality. Lower = better quality and bigger files: 18 is near-lossless, 23 is the default, 28 is small.

## `audioBitrateKbps` (type: `integer`):

AAC bitrate of the merged audio. 128 is fine for speech, 192 to 320 for music.

## `skipFailedInputs` (type: `boolean`):

Off (default): if any input cannot be downloaded or read, the merge fails with a reason per input and costs nothing. On: the failed inputs are left out, the rest is merged and the row says which were skipped.

## `maxInputsPerVideo` (type: `integer`):

A merge with more URLs than this fails without charge. Example: 20. Maximum 50.

## `maxTotalMinutes` (type: `number`):

Cap on the added-up length of the inputs of one merged video. Longer merges fail without charge. Example: 10 = ten minutes (maximum 60). Every clip is re-encoded, so long and high-resolution merges take time.

## `maxMergesPerRun` (type: `integer`):

Hard cap on merged videos in one run (and so on what you can be charged). Merges past the cap are listed as skipped.

## `maxVideoSizeMb` (type: `integer`):

Input files above this size are rejected before the download finishes.

## `maxTotalDownloadMb` (type: `integer`):

Cap on all files downloaded for one merged video (clips plus music), so a long list cannot fill the disk.

## `videoTimeoutSecs` (type: `integer`):

Applies separately to each download.

## `encodeTimeoutMinutes` (type: `integer`):

Time allowed for joining one merged video after the downloads. A merge that takes longer fails without charge.

## `outputStoreName` (type: `string`):

Optional key-value store name. Named stores are kept until you delete them, while a run's own store expires after your plan's retention period. Example: my-merged-videos.

## Actor input object example

```json
{
  "videoUrls": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm"
  ],
  "crossfadeSeconds": 0,
  "normalizeAudio": false,
  "musicVolume": 0.25,
  "width": 0,
  "height": 0,
  "fit": "pad",
  "fps": 0,
  "crf": 23,
  "audioBitrateKbps": 192,
  "skipFailedInputs": false,
  "maxInputsPerVideo": 20,
  "maxTotalMinutes": 5,
  "maxMergesPerRun": 20,
  "maxVideoSizeMb": 500,
  "maxTotalDownloadMb": 2048,
  "videoTimeoutSecs": 600,
  "encodeTimeoutMinutes": 30
}
```

# Actor output Schema

## `results` (type: `string`):

One row per merged video with its download link, duration, size, per-input details and status, as JSON, CSV, Excel and more.

## `records` (type: `string`):

Key-value store records: the merged MP4 files and the run summary.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "videoUrls": [
        "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
        "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("data-done-right/video-concat-merger").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "videoUrls": [
        "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
        "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("data-done-right/video-concat-merger").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "videoUrls": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
    "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.webm"
  ]
}' |
apify call data-done-right/video-concat-merger --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,data-done-right/video-concat-merger"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/vI3RjrbFhTlPbGB1W/builds/WuAq4bjNs9v2eJUr0/openapi.json
