# Supplied English Transcript Aligner (`madrasco/supplied-transcript-aligner`) Actor

Align your supplied English script to a recording up to 30 seconds. Get estimated word timestamps in JSON, with conditional single-cue SRT and VTT exports. Audio comes from your selected Apify key-value store.

- **URL**: https://apify.com/madrasco/supplied-transcript-aligner.md
- **Developed by:** [Jack Valmadre](https://apify.com/madrasco) (community)
- **Categories:** AI, For creators, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 completed alignments

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?

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

## Supplied English Transcript Aligner

Get estimated word timestamps for a short English recording using the script you already have. Upload the audio to an Apify key-value store and paste the matching text. JSON keeps your supplied text and includes character spans and word start/end times.

For short narration workflows that need to preserve a script, such as matching a voiceover to text in an application. You supply both the audio and the transcript.

### Example output

For the recorded sentence “I read the abstract before the full article.”, the JSON result includes:

```json
{
  "text": "abstract",
  "charStart": 11,
  "charEnd": 19,
  "start": 0.42,
  "end": 0.88,
  "status": "estimated"
}
```

Times are in seconds. These are acoustic estimates, not frame-exact boundaries. When every word has an estimate and the recognition check agrees, the run also saves SRT and VTT files. Each contains one cue for the whole script; it does not split captions into readable lines or generate karaoke cues.

### Input and limits

- One audio record in your Apify key-value store, at most 30 seconds and 32 MiB. WAV, FLAC, MP3, M4A and OGG are supported.
- Matching English text, at most 6000 characters and 440 model tokens. A short script can still exceed the token limit.
- Confirmation that you hold the rights to use the recording and text, and that it is nonpersonal English narration.

Use clear spoken narration. Singing, lyrics, meetings, interviews and personal records are outside the scope. There is no URL downloader or batch input. Longer recordings need another tool. Self-hosted open-source alignment tools are an alternative if you can provide your own setup and compute.

### Try the demo

The prefilled input aligns a 1.96-second fiction clip with the text “HOW WOULD THE PAPERS TALK ABOUT IT”. Start it unchanged to try the JSON and caption outputs; the normal completion and start fees apply. The demo audio store is public-read and contains only the licensed sample and attribution.

The rights checkbox stays unchecked for the demo. Demo mode works only while no audio store is selected, the key is `AUDIO`, and the transcript matches this sample exactly. Selecting any store requires your own rights confirmation, even when demo mode is enabled. To use your audio, select your store, replace the text, and explicitly confirm your rights and the narration requirement. API requests that omit `rightsConfirmed` keep a false default; they must explicitly set `useDemo: true` to use the licensed demo.

Demo: unmodified LibriSpeech clip `2277-149896-0004`, based on LibriVox audiobooks. Attribution: Vassil Panayotov, Guoguo Chen, Daniel Povey and Sanjeev Khudanpur (2015), [LibriSpeech/OpenSLR](https://www.openslr.org/12/), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

### Run it with your audio

1. Upload your audio as a record in your Apify key-value store.
2. Select that store in **Audio key-value store** and enter its record key. The default key is `AUDIO`.
3. Paste the matching transcript, confirm the rights and narration requirement, and start the run.
4. Read the result in the dataset or the run's `OUTPUT` record. Download `CAPTIONS.srt` and `CAPTIONS.vtt` from the run's key-value store when `captionExportAllowed` is true.

The Actor requests read access to the selected audio store. Outputs go to the run's default storage. No external speech-service key is needed.

### When captions are withheld

A separate speech-recognition pass checks agreement with your script. Disagreement, invalid alignment or unresolved words withhold the caption files. The JSON result explains the reason and can contain partial results with null times for unresolved words. Silence and invalid input are rejected.

Names, rare words and words the recogniser splits differently (such as 'upon' heard as 'up on') often cause a refusal; refused runs carry no completion fee. Agreement does not prove every word was spoken correctly. Review timings before using them in a finished project.

Recognition can also substitute an ordinary word and refuse a correct script. The result's `comparison` field shows the recognized text and each difference from your script. Your original script is in `suppliedText`. Keep your intended script; do not change it just to satisfy the recognition check.

JSON preserves the supplied text exactly. Caption files collapse whitespace and escape markup.

### Fees

US$0.01 per complete estimated alignment, plus an Actor start charge of US$0.00005 per run (one start event per GB of memory; this Actor runs at 1 GB). Refused or unaligned results have no completion fee; the start charge still applies. Restarting a run through resurrection adds another start event. No subscription or external speech-service key is required.

### Storage and privacy

Speech processing runs inside the Actor. It reads the selected audio record into temporary run disk and removes that temporary file after decoding. Your source audio record stays in your store. Input text, recognized text, hashes and outputs remain in Apify storage under your retention settings. Ending a run does not automatically erase that storage.

Built and maintained with AI agents by Madrasco. For support, use the Actor's Issues tab or support@madrasco.dev. Platform replies may be AI-assisted; the human owner can be reached on request.

# Actor input Schema

## `useDemo` (type: `boolean`):

Runs only the fixed public CC BY clip with its matching prefilled text and AUDIO key. Selecting your own store overrides demo mode and requires your rights confirmation.

## `audioStoreId` (type: `string`):

Leave empty for the licensed demo. For your own audio, select your private Apify key-value store. Only read access is requested; confirm your own rights below.

## `audioRecordKey` (type: `string`):

One audio file uploaded as a record, at most 32 MiB and 30 seconds. WAV, FLAC, MP3, M4A or OGG.

## `transcript` (type: `string`):

Paste matching English text, at most 6000 characters and 440 model tokens. JSON preserves the supplied text exactly.

## `rightsConfirmed` (type: `boolean`):

For your own inputs, confirm you have rights to use both audio and text and they are nonpersonal English narration. Leave unchecked for the supplied licensed demo. No interviews, meetings, personal records, singing or lyrics.

## Actor input object example

```json
{
  "useDemo": true,
  "audioRecordKey": "AUDIO",
  "transcript": "HOW WOULD THE PAPERS TALK ABOUT IT",
  "rightsConfirmed": false
}
```

# Actor output Schema

## `OUTPUT` (type: `string`):

No description

## `CAPTIONS.srt` (type: `string`):

No description

## `CAPTIONS.vtt` (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 = {
    "useDemo": true,
    "audioRecordKey": "AUDIO",
    "transcript": "HOW WOULD THE PAPERS TALK ABOUT IT"
};

// Run the Actor and wait for it to finish
const run = await client.actor("madrasco/supplied-transcript-aligner").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 = {
    "useDemo": True,
    "audioRecordKey": "AUDIO",
    "transcript": "HOW WOULD THE PAPERS TALK ABOUT IT",
}

# Run the Actor and wait for it to finish
run = client.actor("madrasco/supplied-transcript-aligner").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 '{
  "useDemo": true,
  "audioRecordKey": "AUDIO",
  "transcript": "HOW WOULD THE PAPERS TALK ABOUT IT"
}' |
apify call madrasco/supplied-transcript-aligner --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,madrasco/supplied-transcript-aligner"
        }
    }
}
```

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/QBxT1oIVDkG4zGaNf/builds/bNetbF1LUsJiusZKI/openapi.json