# ToneParcel — Audio Mastering & Loudness API (`epubpreflight/toneparcel-api`) Actor

Batch audio mastering with six presets, loudness normalization and measured output.

- **URL**: https://apify.com/epubpreflight/toneparcel-api.md
- **Developed by:** [Ezra Evercreech](https://apify.com/epubpreflight) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $40.00 / 1,000 audio master 1mins

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

## ToneParcel — Audio Mastering & Loudness API

Batch basic mastering with six presets, optional sound controls, loudness normalization, and measured output. Analyze or normalize files without applying the mastering effects when desired.

### Input

```json
{
  "urls": ["https://example.com/your-audio.wav"],
  "options": {
    "mode": "master",
    "preset": "warm-tape",
    "targetLufs": -14,
    "truePeakCeiling": -1,
    "format": "wav",
    "effects": { "warmth": 45, "stereoWidth": 105 }
  }
}
```

Replace the example URL with your public WAV/MP3 file. Maximum 10 URLs per run, 0.4–300 decoded seconds, 60 MiB per file, mono/stereo, and 44.1/48 kHz input. WAV must contain PCM audio. Output supports 44.1/48 kHz WAV (16/24-bit) or MP3 (128/192/256/320 kbps). Files are processed sequentially.

| Option | Default | Meaning |
|---|---|---|
| mode | master | master, normalize or analyze |
| preset | transparent | Mastering preset; only accepted in master mode |
| targetLufs | Preset target, otherwise -14 | -30 to -9 LUFS |
| truePeakCeiling | Preset ceiling capped at -1 | -6 to -0.3 dBTP |
| format | wav | wav or mp3 |
| sampleRate | 48000 | 44100 or 48000 |
| bitDepth | 24 | 16 or 24; WAV only |
| mp3Bitrate | 192 | 128, 192, 256, 320; MP3 only |
| effects | Preset values | Optional overrides in master mode |

Presets: **Transparent, Warm Tape, Crystal Air, Punch Glue, Wide Cinema, Loud & Clear**. A preset sets a processing configuration; individual effects then override it. There is no genre classifier, model inference, stem separation or reference-track matching.

Available effect overrides: `warmth`, `clarity`, `air`, `lowEndClean`, `glueCompression`, `autoLevelStrength` (0–100), `stereoWidth` (0–150; 100 keeps the original width), and `monoBassAnchor` (boolean). Stereo controls have no effect on mono inputs. The existing preset's depth setting remains part of its sound. Transparent applies mild processing; use `mode: "normalize"` to avoid mastering coloration.

### Processing and output

The mastering DSP runs in a Node worker using its **export** chain. FFmpeg decodes inputs, applies final two-pass loudness normalization and encodes the result. Metered input/output LUFS and true peak come from FFmpeg. MP3 is measured after encoding; if encoding creates excess peaks, the output is attenuated and measured again. The returned `target_met` indicates whether actual LUFS is within 0.5 LU of the target. Peak protection can take precedence and leave output quieter than requested.

The Dataset returns `index`, `status`, duration, channels, actual settings, engine version, input/output measurements, `billable_minutes`, `billing_event`, and `output_url`/`output_key` for processed audio. Analysis returns measurements without an audio output. Silent/below-gate input returns `lufs: null` and `measurement_status: "unmeasurable"` in analysis; normalization/mastering rejects it. Sub-400ms inputs are rejected rather than assigned an invented LUFS value.

Per-file errors are free of result charges, and other files continue. If all files fail, the run fails. `SUMMARY` records outcomes and acknowledged billing events. Read the measured output and warnings rather than assuming every target is reachable. Synthetic regression tests do not establish subjective mastering quality or standards certification.

Downloads permit public HTTP(S) URLs only, reject private/reserved addresses and pin DNS results. Files are downloaded into a random per-item temporary directory and removed afterward. The DSP worker is terminated after 300 seconds; each FFmpeg stage has a 120-second deadline. Output metadata is stripped. No input audio is sent to an external AI service.

Output URLs refer to shareable records in the run's Apify key-value store; anyone holding a URL may be able to download it. Retention follows Apify store settings, without guaranteed fixed-hour deletion or permanent hosting. Save results to your own storage. Input JSON and result rows remain subject to platform retention.

### Launch pricing (USD, platform usage included)

| Mode | Each started minute, per successful file |
|---|---:|
| Analyze | $0.010 |
| Normalize | $0.020 |
| Master, any preset | $0.040 |

Each run also costs **$0.005**, including runs with failed files. Duration is rounded up separately for each file: 60 seconds = 1 minute, 60.1 seconds = 2. A 3-minute master is **$0.125 total**, and a 5-minute master is **$0.205**. No subscription or preset surcharge.

Each file generates one event for its mode and 1–5-minute duration tier. This avoids charging only some minutes of an indivisible output. Budget checks occur before download and after decoded duration is known; insufficient budget stops the batch without delivering or charging that file. Preparation can incur compute before its exact duration is known.

The fixed 2 GB run uses two automatic start events at $0.0025 each, totaling $0.005. There is no separate Dataset-row charge.

### Call from your application

Start an asynchronous run using your Apify token and an explicit spending limit:

```bash
curl -X POST "https://api.apify.com/v2/acts/epubpreflight~toneparcel-api/runs?maxTotalChargeUsd=1" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @input.json
```

Save `data.id` from the response. Poll `GET /v2/actor-runs/{runId}` with the same authorization header until the run finishes. Read `GET /v2/datasets/{defaultDatasetId}/items` to obtain result rows and download each successful `output_url`. Analysis-only runs return measurements without an audio file.

Use only source files you have permission to process. For help, open an issue on this Actor and include the run ID, without posting confidential source URLs.

# Actor input Schema

## `urls` (type: `array`):

1–10 public WAV/MP3 URLs; 0.4–300 seconds, 60 MiB, mono/stereo, 44.1/48 kHz.

## `options` (type: `object`):

Choose a mastering preset or set mode to normalize/analyze. Preset and effects apply only in master mode. See README for options.

## Actor input object example

```json
{
  "urls": [
    "https://api.apify.com/v2/key-value-stores/gCIsrFeUhuWihl5jD/records/source-60.wav?signature=1n7tH5XUhii8sAFh3QmdX"
  ],
  "options": {
    "format": "wav",
    "targetLufs": -14,
    "truePeakCeiling": -1,
    "mode": "master",
    "preset": "warm-tape"
  }
}
```

# Actor output Schema

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

No description

## `summary` (type: `string`):

No description

# 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 = {
    "urls": [
        "https://api.apify.com/v2/key-value-stores/gCIsrFeUhuWihl5jD/records/source-60.wav?signature=1n7tH5XUhii8sAFh3QmdX"
    ],
    "options": {
        "format": "wav",
        "targetLufs": -14,
        "truePeakCeiling": -1,
        "mode": "master",
        "preset": "warm-tape"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("epubpreflight/toneparcel-api").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 = {
    "urls": ["https://api.apify.com/v2/key-value-stores/gCIsrFeUhuWihl5jD/records/source-60.wav?signature=1n7tH5XUhii8sAFh3QmdX"],
    "options": {
        "format": "wav",
        "targetLufs": -14,
        "truePeakCeiling": -1,
        "mode": "master",
        "preset": "warm-tape",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("epubpreflight/toneparcel-api").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 '{
  "urls": [
    "https://api.apify.com/v2/key-value-stores/gCIsrFeUhuWihl5jD/records/source-60.wav?signature=1n7tH5XUhii8sAFh3QmdX"
  ],
  "options": {
    "format": "wav",
    "targetLufs": -14,
    "truePeakCeiling": -1,
    "mode": "master",
    "preset": "warm-tape"
  }
}' |
apify call epubpreflight/toneparcel-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,epubpreflight/toneparcel-api"
        }
    }
}
```

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/K7V7FeeYUTc4hat4a/builds/hMCiXsZiVPzwbaEQR/openapi.json