# Facebook Ad Video Transcript and Creative Analyzer (`salehahmad/facebook-ad-video-transcript-analyzer`) Actor

Turn Meta Ad Library video ads into timestamped transcripts, English translations and a creative breakdown: hook, angle, offer, pain points, CTA and a reusable script template.

- **URL**: https://apify.com/salehahmad/facebook-ad-video-transcript-analyzer.md
- **Developed by:** [Saleh Ahmad](https://apify.com/salehahmad) (community)
- **Stats:** 2 total users, 1 monthly users, 75.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $40.00 / 1,000 video analyzeds

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

## Facebook Ad Video Transcript and Creative Analyzer

Turn competitors' Facebook and Instagram video ads into **transcripts, English translations and a ready-to-use creative breakdown**: the hook, angle, offer, pain points, call to action, script structure and a reusable script template. It takes seconds per ad, not days of watching ads one by one.

### Who it's for

- **Performance marketers and media buyers** who want to know why competitors' long-running ads work
- **Agencies** building swipe files and competitor research for clients
- **UGC creators and scriptwriters** who need proven hooks and script structures to adapt
- **E-commerce brands** checking what offers and angles their market is running right now
- **Teams in non-English markets**: ads in Urdu, Hindi, Spanish, Arabic and many other languages come back with a full English translation

### What you get for every ad

| Field | What it is |
|---|---|
| `hook` | The opening line that grabs attention, in English |
| `hookType` | Pain call-out, bold claim, question, curiosity gap, social proof... |
| `angle` | The core persuasion angle in one sentence |
| `offer` | Discount, free trial, bundle (empty if none) |
| `painPoints` | The problems the ad agitates |
| `callToAction` | What the viewer is told to do |
| `scriptStructure` | The ad broken into sections: Hook, Problem, Solution, Proof, Offer, CTA |
| `scriptTemplate` | A fill-in-the-blank version of the script you can reuse |
| `transcriptText` | Everything said in the ad, in its original language |
| `englishTranslation` | Full English translation (for English ads, the transcript itself) |
| `transcript` | Timestamped segments |
| `hookTranscript` | Exactly what is said in the first 3 seconds |
| `detectedLanguage`, `durationSeconds` | Spoken language and video length |
| `advertiser`, `adId`, `adLibraryUrl` | Who ran it and a link back to the Ad Library |

### Sample output

#### English ad

A real ad for a brow makeup stamp, shortened:

```json
{
  "advertiser": "BrowPro",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=1557442172039271",
  "status": "success",
  "durationSeconds": 45.29,
  "detectedLanguage": "english",
  "hookTranscript": "Flawless model brows without the drama. With the Brow Pro",
  "hook": "Flawless model brows without the drama.",
  "hookType": "bold claim",
  "angle": "Get salon-perfect, long-lasting brows in seconds with an easy-to-use stamp that eliminates smudging and messy pencils.",
  "offer": "50% off",
  "painPoints": [
    "Traditional brow pencils smudge and fade",
    "Creating symmetrical brows is time-consuming",
    "Brow makeup can melt with sweat, humidity, or water"
  ],
  "callToAction": "Grab yours now.",
  "scriptStructure": [
    { "section": "Hook", "summary": "Introduce flawless, drama-free brows." },
    { "section": "Problem", "summary": "Ordinary pencils smudge, fade and make symmetry hard." },
    { "section": "Solution", "summary": "The Brow Pro stamp: fill, stamp, done in seconds; six shapes designed by professional artists." },
    { "section": "Proof", "summary": "Before-and-after comparison; tested against sweat, humidity and water." },
    { "section": "Offer", "summary": "Mention 50% discount." },
    { "section": "CTA", "summary": "Encourage immediate purchase: \"Grab yours now.\"" }
  ],
  "scriptTemplate": "Hook: \"[POWERFUL CLAIM]\"\nProblem: \"[COMMON ISSUE] like smudging, fading, or uneven shape makes makeup a hassle.\"\nSolution: \"Introducing the [PRODUCT NAME] - just fill, stamp, and you're done in seconds.\"\nProof: \"Tested against sweat, humidity, and even underwater - it stays put.\"\nOffer: \"Get it now at [DISCOUNT]% off.\"\nCTA: \"[CALL TO ACTION]\"",
  "transcriptText": "Flawless model brows without the drama. With the Brow Pro Simone stamp, you get perfectly sculpted symmetrical brows in seconds. Just fill, stamp, done...",
  "transcript": [
    { "start": 0, "end": 5.44, "text": "Flawless model brows without the drama. With the Brow Pro Simone stamp, you get perfectly sculpted" },
    { "start": 5.44, "end": 13.82, "text": "symmetrical brows in seconds. Just fill, stamp, done. Just look at this difference between my" }
  ]
}
```

#### Spanish ad, with English translation

A real ad for a dog supplement, shortened:

```json
{
  "advertiser": "Dogelthy",
  "adLibraryUrl": "https://www.facebook.com/ads/library/?id=3739599176334600",
  "status": "success",
  "durationSeconds": 52.5,
  "detectedLanguage": "spanish",
  "hookTranscript": "No dejes que tus perros sufran en silencio, pueden estar sintiendo mucho",
  "hook": "Don't let your dogs suffer in silence, they may be feeling a lot of pain.",
  "hookType": "pain call-out",
  "angle": "A 100% natural supplement can safely restore mobility and reduce joint pain in senior dogs that can't undergo surgery or conventional therapy.",
  "offer": "",
  "painPoints": [
    "Dogs silently enduring joint and mobility pain",
    "Sudden loss of ability to walk",
    "Owners' heartbreak watching their pets struggle"
  ],
  "callToAction": "If your dog is also struggling to walk, try Mobility for that extra boost.",
  "scriptStructure": [
    { "section": "Hook", "summary": "A stark warning not to let dogs suffer in silence." },
    { "section": "Problem", "summary": "Introduce Luna, a 15-year-old dog who stopped walking overnight." },
    { "section": "Solution Intro", "summary": "Discovery of Mobility, a 100% natural supplement." },
    { "section": "Proof", "summary": "Luna gradually moving again with more strength and less pain." },
    { "section": "CTA", "summary": "Invite viewers with struggling dogs to try Mobility." }
  ],
  "scriptTemplate": "Hook: \"Don't let your [PETS] suffer in silence...\"\nProblem: \"[NAME] is [AGE] years old and suddenly stopped walking.\"\n...\nCTA: \"If your dog is also struggling to walk, try [PRODUCT NAME].\"",
  "transcriptText": "No dejes que tus perros sufran en silencio, pueden estar sintiendo mucho dolor. Luna tiene 15 años...",
  "englishTranslation": "Don't let your dogs suffer in silence, they may be feeling a lot of pain. Luna is 15 years old...",
  "transcript": [
    { "start": 0, "end": 3.66, "text": "No dejes que tus perros sufran en silencio, pueden estar sintiendo mucho dolor." },
    { "start": 3.8, "end": 7.66, "text": "Luna tiene 15 años, hace un año dejó de caminar de un día para otro." }
  ]
}
```

In Apify Console the results open in three views: **Creative breakdown**, **Transcripts**, and **Status and errors**. Export them to Excel, CSV, JSON or Google Sheets.

### How to use it

#### Option 1: Paste video links

Paste direct video file links (`video.xx.fbcdn.net/...mp4`) into **Video URLs**. To copy one by hand, right-click a video in the Ad Library and choose "Copy video address".

Ad Library page links (`facebook.com/ads/library/?id=...`) are not video files. Use option 2 for those.

#### Option 2: After a Facebook Ad Library scraper (recommended)

1. Run a Facebook Ad Library scraper, for example [Facebook Ads Scraper](https://apify.com/apify/facebook-ads-scraper). Search for a competitor or keyword and set the media type to **video**.
2. Open this Actor and pick that run's dataset in **Ad Library scraper dataset ID**.
3. Start. Video ads are processed automatically and image ads are skipped.

Run this Actor soon after the scraper: Facebook video links expire, usually within 1 to 4 days.

### Pricing

You only pay for ads that are actually analysed.

| What | Price |
|---|---|
| Each analysed ad (video up to 5 minutes) | **$0.04** |
| Each started minute beyond 5 minutes | $0.005 |
| Each run | $0.005 |
| Failed ads, expired links, music-only ads with no speech | **free** |

Examples: 100 typical ads cost about **$4**. A 7-minute ad costs $0.055.

### Input

| Field | Description |
|---|---|
| **Video URLs** | Direct links to ad video files |
| **Ad Library scraper dataset ID** | A dataset from a Facebook Ad Library scraper run |
| **Max ads to analyse** | Optional limit per run (up to 10,000) |
| **Proxy configuration** | Usually not needed |

You can use video URLs, a dataset, or both in the same run.

Example input:

```json
{
  "datasetId": "YOUR_SCRAPER_DATASET_ID",
  "maxAds": 50
}
```

### Feedback

Found a bug or want a feature, such as TikTok ads, more output languages or custom questions about each ad? Open an issue on the **Issues** tab. We reply within 12 hours.

### Questions? Email me

Need help setting it up, want a custom version for your agency, or have ads in a language you'd like tested first? Email me at **<salehahmad2106@gmail.com>** and I'll get back to you.

# Actor input Schema

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

Direct links to ad video files, for example the .mp4 links (video.xx.fbcdn.net) that Facebook Ad Library scrapers return. Ad Library page links do not work here; use the dataset option below instead.

## `datasetId` (type: `string`):

Pick (or paste the ID of) a dataset produced by a Facebook Ad Library scraper on Apify. Video ads are picked up automatically, image ads are skipped. Run the scraper shortly before this Actor: Facebook video links expire after a few days.

## `maxAds` (type: `integer`):

Stop after this many ads. Leave empty to analyse every video ad in the input (up to 10,000 per run).

## `proxyConfiguration` (type: `object`):

Proxy used to download the videos. Usually not needed.

## Actor input object example

```json
{
  "videoUrls": [
    "https://video.xx.fbcdn.net/v/t42.1790-2/123456789_n.mp4"
  ],
  "datasetId": "aBcD1234eFgH5678i",
  "maxAds": 50,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

One row per ad: hook, angle, offer, pain points, call to action and script template.

## `transcripts` (type: `string`):

Full transcript, English translation and timestamped segments for each ad.

## `status` (type: `string`):

Which ads were analysed, skipped (no speech) or failed, and why.

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

Totals for the run: status counts, success rate, languages and the most common errors.

# 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://images-assets.nasa.gov/video/NHQ_2019_0719_We%20Go%20as%20the%20Artemis%20Generation/NHQ_2019_0719_We%20Go%20as%20the%20Artemis%20Generation~mobile.mp4"
    ],
    "maxAds": 1,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("salehahmad/facebook-ad-video-transcript-analyzer").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://images-assets.nasa.gov/video/NHQ_2019_0719_We%20Go%20as%20the%20Artemis%20Generation/NHQ_2019_0719_We%20Go%20as%20the%20Artemis%20Generation~mobile.mp4"],
    "maxAds": 1,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("salehahmad/facebook-ad-video-transcript-analyzer").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://images-assets.nasa.gov/video/NHQ_2019_0719_We%20Go%20as%20the%20Artemis%20Generation/NHQ_2019_0719_We%20Go%20as%20the%20Artemis%20Generation~mobile.mp4"
  ],
  "maxAds": 1,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call salehahmad/facebook-ad-video-transcript-analyzer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,salehahmad/facebook-ad-video-transcript-analyzer"
        }
    }
}
```

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/dIRW5sZxywkU7CyE9/builds/hvKCqETj6kHprid70/openapi.json