# Audio Overlayer (`dead_minds/audio-overlayer`) Actor

Merge one or more audio tracks onto a base audio file at specific timestamps. The output duration always matches the base audio — overlapping tracks are automatically trimmed.

- **URL**: https://apify.com/dead\_minds/audio-overlayer.md
- **Developed by:** [dead minds](https://apify.com/dead_minds) (community)
- **Categories:** Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 88.5% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $8.00 / 1,000 audio overlay results

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

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🎵 Audio Overlay Actor

An [Apify](https://apify.com) Actor that merges one or more audio files on top of a base audio track, at specific points in time. Supports any combination of input formats — MP3, WAV, OGG, FLAC, AAC, OPUS, and more.

### How it works

- The **base audio** (`baseAudioUrl`) always determines the total duration of the output.
- Each audio in `overlays` is mixed in starting at its own `startTimeSec` (in seconds from the beginning of the result).
- If an overlay extends beyond the end of the base audio, it is automatically trimmed. The final duration **always** equals the duration of the base audio — no exceptions.
- Input tracks can be in **any format** — FFmpeg handles the conversion automatically. You can mix an MP3 base with a WAV overlay and export to FLAC, for example.

### Input

```json
{
  "baseAudioUrl": "https://example.com/base.mp3",
  "overlays": [
    {
      "audioUrl": "https://example.com/overlay.wav",
      "startTimeSec": 5
    }
  ],
  "outputFormat": "mp3"
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `baseAudioUrl` | string | ✅ | Public URL of the base audio file. Its duration defines the output duration. |
| `overlays` | array | ✅ | List of audio files to mix in, each with their own start time. Can be empty. |
| `overlays[].audioUrl` | string | ✅ | Public URL of the audio to overlay. Any format supported by FFmpeg. |
| `overlays[].startTimeSec` | number | ✅ | Second at which this overlay starts playing in the final result. Must be ≥ 0. |
| `outputFormat` | string | ❌ | Output file format (default: `mp3`). See supported formats below. |

### Supported formats

Input and output formats are handled by FFmpeg — inputs are detected automatically, no matter the file extension.

| Format | Input | Output |
|---|---|---|
| MP3 | ✅ | ✅ |
| WAV | ✅ | ✅ |
| OGG | ✅ | ✅ |
| FLAC | ✅ | ✅ |
| AAC | ✅ | ✅ |
| M4A | ✅ | ✅ |
| OPUS | ✅ | ✅ |
| WMA | ✅ | ✅ |

You can freely mix formats — e.g. MP3 base + WAV overlay → FLAC output.

### Supported audio sources

The Actor downloads audio files directly via URL. The URL must return the raw audio binary — not an HTML page or a redirect confirmation screen.

✅ Works: `raw.githubusercontent.com`, direct Dropbox links (`?dl=1`), any direct download URL.\
❌ Doesn't work: Google Drive share links, YouTube, SoundCloud, or any URL that requires login or redirects to a webpage.

### Multiple overlays example

You can mix more than one audio on top of the base:

```json
{
  "baseAudioUrl": "https://example.com/music.mp3",
  "overlays": [
    { "audioUrl": "https://example.com/voiceover.wav", "startTimeSec": 0 },
    { "audioUrl": "https://example.com/jingle.ogg", "startTimeSec": 30 }
  ],
  "outputFormat": "flac"
}
```

### Output

The Actor saves the resulting audio file to the run's Key-Value Store under the key `OUTPUT`. You can access it from:

- The **Storage** tab in the Apify Console after the run completes.
- Directly via the API:
  ```
  https://api.apify.com/v2/key-value-stores/{storeId}/records/OUTPUT
  ```

The run log also prints the full download URL at the end:

```
[INFO] Audio final disponible en: https://api.apify.com/v2/key-value-stores/.../records/OUTPUT
```

### Tech stack

- **Python 3.12**
- **Pydub** — audio mixing and processing
- **FFmpeg** — underlying audio engine, handles all format conversions automatically
- **Requests** — downloading audio files from URLs

### Roadmap (v2)

- \[ ] Per-overlay volume control (`volumeDb`)
- \[ ] Fade in / fade out
- \[ ] Audio sequencing (back-to-back, not just simultaneous)
- \[ ] Loop an overlay N times
- \[ ] Trim the base audio before processing

# Actor input Schema

## `baseAudioUrl` (type: `string`):

Public URL of the base audio file. Its duration determines the total duration of the output — regardless of the length of the overlaid tracks.

## `baseVolumeDb` (type: `integer`):

Volume adjustment for the base audio in decibels. 0 = no change, positive = louder, negative = quieter. Example: -6 cuts volume roughly in half.

## `bitrate` (type: `integer`):

Bitrate of the output file in kbps. Only applies to compressed formats (mp3, ogg, aac, opus). Lower = smaller file, lower quality. Typical values: 320 (max), 128 (standard), 64 (voice), 32 (light), 8 (minimum intelligible).

## `overlays` (type: `array`):

List of audio files to mix on top of the base audio. Each one starts playing at its own startTimeSec. Supports any format (mp3, wav, ogg, flac, aac, etc.).

## `outputFormat` (type: `string`):

Format of the output audio file. Input tracks can be in any format — they are automatically converted by FFmpeg.

## Actor input object example

```json
{
  "baseAudioUrl": "https://github.com/jere-idk/audio-overlay-actor-apify/raw/refs/heads/main/samples/audio%201_test.mp3",
  "baseVolumeDb": 0,
  "overlays": [
    {
      "audioUrl": "https://github.com/jere-idk/audio-overlay-actor-apify/raw/refs/heads/main/samples/audio%202_test.mp3",
      "startTimeSec": 0,
      "volumeDb": 0
    }
  ],
  "outputFormat": "mp3"
}
```

# Actor output Schema

## `audioFile` (type: `string`):

The resulting audio file with all overlays mixed in. Duration always equals the base audio.

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

Dataset item with the output URL, duration in seconds, and format of the resulting file.

# 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 = {
    "baseAudioUrl": "https://github.com/jere-idk/audio-overlay-actor-apify/raw/refs/heads/main/samples/audio%201_test.mp3",
    "overlays": [
        {
            "audioUrl": "https://github.com/jere-idk/audio-overlay-actor-apify/raw/refs/heads/main/samples/audio%202_test.mp3",
            "startTimeSec": 0,
            "volumeDb": 0
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("dead_minds/audio-overlayer").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 = {
    "baseAudioUrl": "https://github.com/jere-idk/audio-overlay-actor-apify/raw/refs/heads/main/samples/audio%201_test.mp3",
    "overlays": [{
            "audioUrl": "https://github.com/jere-idk/audio-overlay-actor-apify/raw/refs/heads/main/samples/audio%202_test.mp3",
            "startTimeSec": 0,
            "volumeDb": 0,
        }],
}

# Run the Actor and wait for it to finish
run = client.actor("dead_minds/audio-overlayer").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "baseAudioUrl": "https://github.com/jere-idk/audio-overlay-actor-apify/raw/refs/heads/main/samples/audio%201_test.mp3",
  "overlays": [
    {
      "audioUrl": "https://github.com/jere-idk/audio-overlay-actor-apify/raw/refs/heads/main/samples/audio%202_test.mp3",
      "startTimeSec": 0,
      "volumeDb": 0
    }
  ]
}' |
apify call dead_minds/audio-overlayer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=dead_minds/audio-overlayer",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/RJk7mt9UhJdcy7i2M/builds/fMT0WoVVbdsQfcTgJ/openapi.json