Video Reuse Monitor — Clip Matching & Usage Tracking

Connect existing ad-scraper datasets to your original video library. Find full-video reuse and overlapping clips, group observed ads by reference asset, and track newly observed placements across runs.

This Actor analyzes supplied media. It does not search the whole internet or scrape ad libraries itself. It processes real video files with FFmpeg, visual perceptual fingerprints and temporal matching; no paid AI API, language-model key, GPU service or face recognition is needed.

What you get

• Exact-file matches, even for static files.
• Perceptual matches for re-encoding/resizing and supported same-speed excerpts.
• Start/end timestamps in both your reference and the inspected video.
• Reference-linked families: multiple ads using an original share its asset-family ID. A montage may match several originals; different originals are not falsely collapsed into one family.
• First observed / still observed / observed again and conservative not-observed records.
• Optional supplied usage-window checks, with active-record and unverified-activity flags separated.
• An HTML report with paired comparison frames, JSON and spreadsheet-safe CSV.
• Persistent fingerprint reuse and bounded history when you supply a named state store.

Quick start: real videos

Set Mode to monitor, add references, then add direct comparison URLs or an existing dataset ID.

{
  "mode": "monitor",
  "references": [
    {
      "id": "asset-01",
      "name": "Summer product demo",
      "url": "https://your-public-media-host.example/original.mp4",
      "usageEnd": "2026-12-31"
    }
  ],
  "videos": [
    {
      "id": "ad-01",
      "url": "https://your-public-media-host.example/ad.mp4",
      "pageUrl": "https://www.facebook.com/ads/library/?id=YOUR_AD_ID",
      "advertiser": "Your client",
      "platform": "meta",
      "isActive": true
    }
  ],
  "stateStoreName": "vrm-my-project",
  "monitorId": "client-01"
}

Replace example media URLs with your actual direct downloadable MP4/MOV/WebM URLs. An Instagram/TikTok/YouTube page URL is not a video file. HLS/DASH manifests and authenticated downloads are not supported. A hosting link returning HTML rather than the actual file will fail explicitly.

IDs must be stable. Reference IDs must be unique. One comparison video can match multiple references.

Existing scraper datasets

Set datasetId to an existing dataset you can access. The Actor reads it; it does not start or charge for another scraper.

Supported automatic layouts include:

• Meta: snapshot.videos[].video_hd_url (or video_sd_url) and snapshot.cards[].
• Generic: videoUrl, downloadUrl, download_url, video_hd_url, video_sd_url.
• Downloaded TikTok media: mediaUrls[] and common direct download fields.

For another layout, set datasetMediaField to a dotted path such as snapshot.videos.0.video_hd_url and optionally datasetIdField to your stable ID field. A custom media field can contain a URL or a list of URLs.

For input datasets and named history storage, configure the Actor to allow that storage access. Limited permissions may prevent reading other datasets or named stores. Direct URLs without cross-run history need no external storage access.

Rows without usable direct video URLs are disclosed in the summary. Dataset row/video caps are disclosed; incomplete datasets never generate a missing-video inference.

Genuine self-test

Run with:

{"mode":"self-test"}

This generates and encodes real MP4 files, then uses the same decoding and matching pipeline to inspect an identical copy, a resized/re-encoded copy, a montage containing an excerpt, and unrelated footage. It does not return canned detection results. SUMMARY.selfTestPassed must be true.

Self-test does not charge the custom processing event. Platform compute/storage or a platform-configured actor-start fee can still apply. Do not publish a self-test task as the product's actual customer workflow.

Outputs

Output	Contents
Default dataset	Match rows, explicit failures, optional unmatched rows and not-observed records
REPORT.html	Standalone evidence report; first 100 match rows can have comparison frames
RESULTS.json	Full structured results
RESULTS.csv	CSV with timestamp segments and protection against formula injection
SUMMARY	Coverage, counts, limits, failures, cache usage and processing-event count

Match rows contain referenceId, candidateId, familyId, confidence, method, similarity, matchedSeconds, coverage ratios and segments with start/end positions in both videos.

Interpret matches correctly

• exact_sha256: identical file bytes. high evidence for file identity.
• temporal_perceptual: visually consistent frame fingerprints across time. Conservative high or review tier.
• similarity measures fingerprint agreement. It is not a calibrated probability.
• No match means no match passed these thresholds; it does not prove originality.
• Shared stock footage, templates and recurring logo animations can legitimately match; a match does not establish ownership.
• Match boundaries are approximate (normally within roughly one sample interval for supported edits), not frame-accurate forensic timestamps.

History and repeat runs

Use the same stateStoreName, monitorId, reference IDs and candidate IDs for repeat runs. A named key-value store persists content fingerprints and sightings. No state-store name means a one-off cloud comparison without cross-run history.

Run one job at a time per monitor. Key-value stores do not provide transactional locking; overlapping schedules for the same monitor are unsupported. Use different monitor IDs or storage names for independent projects.

Files are downloaded again so changed content behind a URL can be detected. A cached content fingerprint skips decoding, not network transfer. Cache identity includes the algorithm and sampling rate. New metadata or usage dates are evaluated again; stored fingerprints do not preserve stale contract decisions.

Histories retain up to 10,000 recently observed reference/video pairs. Each monitor tracks up to 5,000 cached fingerprints; old entries are evicted. Apify storage and network costs remain applicable.

first_observed is the first sighting by this monitor, not the platform's upload date. observed_again means it returned after not being observed in an earlier completed input snapshot. not_observed_in_current_input means absent from supplied input, not that an ad ended. Failed, truncated or unsupported inputs suppress missing inference.

Usage-window flags

Dates are optional and supplied by the user, inclusive YYYY-MM-DD, compared using the UTC observation date. An outside-window match is flagged only at high match confidence. The flag distinguishes active input records, inactive records and unknown activity.

The Actor does not independently verify ad delivery, rights ownership, license exceptions, continuous advertising, infringements or amounts owed. A media URL remaining reachable is not proof that an advertisement is running.

Pricing for developers

The implemented custom event is video-minute-processed.

• One event per started minute of each newly fingerprinted file (references and candidates), after a successful decode.
• Identical file content is fingerprinted/charged once within the run; valid stored fingerprints are not charged again.
• Failed downloads/decodes do not charge this event.
• Fingerprinting is the priced operation. A successfully fingerprinted video can have no matches or hit the bounded comparison limit.
• Match rows do not create additional processing charges.
• Budget availability is checked before decoding each new file. When the requested processing units will not fit, the run saves partial results and stops.
• Disable the default automatic apify-default-dataset-item charge; using it would charge customers for each evidence row. The Actor rejects that conflicting pricing configuration.
• The Actor's price is configured in Apify Console, not in source code. No claim of a validated profitable price is included.

A fixed actor-start fee is optional, platform-managed, and separate from this event. It is not included in the processing count. Start fees may scale with memory; a processing-only price is clearer for this product.

Limits and appropriate scope

This first version is visual matching for short videos (default 180 seconds; hard cap 300), approximately unchanged playback speed. It is not a generic semantic similarity model or a face/person identifier.

Heavy cropping, mirror flips, different speeds, large overlays, occlusion, very short clips, low-information slides and severe edits may be missed or need review. Audio is not matched in version 1. Automated cross-platform discovery and private/authenticated videos are outside the scope.

The comparison index skips saturated low-information buckets and bounds frame comparisons. This can miss difficult/repetitive matches rather than spending unbounded CPU. Check summary/failure records instead of assuming complete coverage.

Media downloads validate public DNS addresses and redirect targets; private networks and non-HTTP schemes are blocked. Only downloaded local files enter FFmpeg, with protocol restrictions, duration/file/resolution limits and timeouts. This is a bounded media processor, not a general URL fetcher.

Development

Python 3.12, FFmpeg/ffprobe with H.264 support, dependencies in requirements.txt.

python main.py --input example-self-test.json --output local-output

Run python -m pytest tests after installing pytest and jsonschema. Use python tools/package.py to regenerate the five-file upload variant and release ZIP. The simplified upload main.py bundles the same auditable vrm/ source; no separate detection implementation is used.

Release status

Version 1.0 implements the described scoped workflow. Local generated-video, state, billing, adapter and package checks are recorded in VALIDATION.md. It has not been deployed or validated against your live ad library/account as part of this delivery. Broad commercial accuracy requires a representative real-media benchmark.