Skip to main content

IAB and Ad Suitability Guide

Partially available on Transcribe Pro Vision MAX

Video-level IAB categories (topic.iab, topic.general, topic.genre) are included in the Transcribe Pro Vision MAX free trial. Start free →

Scene-level IAB sections with Ad Score (topic.iab.section) require the AdScout subscription. Contact sales →

This guide explains how to use Valossa AI's IAB Content Taxonomy categories and Ad Score feature for contextual advertising, content profiling, and brand safety.

Quick Exploration with Metadata Reader

Before writing custom code, you can quickly inspect IAB categories using the Metadata Reader CLI tool:

# List all category tags including IAB
python -m metareader list-categories core_metadata.json

# List IAB topic detections
python -m metareader list-detections --type "topic.iab*" core_metadata.json

# Get a topic overview with screentime percentages
python -m metareader summary --type "topic.*" core_metadata.json

Overview​

Valossa AI classifies video content using two levels of IAB categorization:

Detection TypeScopeUse Case
topic.iabEntire videoMatch ads to whole videos
topic.iab.sectionTime-based sectionsMatch ads to specific moments within a video

With the optional Ad Score feature, you get a numeric value suggesting how suitable a specific video section is for a particular ad category.

Step 1: Get Video-Level IAB Categories​

import json

with open("core_metadata.json", "r") as f:
    metadata = json.load(f)

iab_ids = metadata["detection_groupings"]["by_detection_type"].get("topic.iab", [])

print("Video-level IAB categories:")
for det_id in iab_ids:
    detection = metadata["detections"][det_id]
    iab = detection["ext_refs"]["iab"]
    hierarchy = " > ".join(iab["labels_hierarchy"])
    scd = iab.get("is_scd_category", False)

    print(f"  {hierarchy} (ID: {iab['id']})")
    if scd:
        print(f"    ** Special Category Data (SCD) - sensitive for advertising **")

Step 2: Get Section-Level IAB Categories​

Section-level categories have time codes and optional Ad Score values:

section_ids = metadata["detection_groupings"]["by_detection_type"].get("topic.iab.section", [])

print("\nSection-level IAB categories:")
for det_id in section_ids:
    detection = metadata["detections"][det_id]
    iab = detection["ext_refs"]["iab"]
    hierarchy = " > ".join(iab["labels_hierarchy"])

    print(f"\n  {hierarchy} (ID: {iab['id']})")

    # Check source modalities
    sources = detection.get("a", {}).get("sources", [])
    print(f"    Sources: {', '.join(sources)}")

    # Detection-level Ad Score
    ad_score = detection.get("a", {}).get("ad_score", {})
    if ad_score:
        print(f"    Best Ad Score: {ad_score['max']:.3f} at {ad_score['s_max']:.0f}s")

    # Per-occurrence details
    for occ in detection.get("occs", []):
        occ_ad = occ.get("a", {}).get("ad_score", {})
        print(f"    Segment: {occ['ss']:.0f}s - {occ['se']:.0f}s (confidence: {occ.get('c', 0):.3f})")
        if occ_ad:
            print(f"      Ad Score: {occ_ad['max']:.3f} at {occ_ad['s_max']:.0f}s")

Step 3: Filter by SCD Categories​

Special Category Data (SCD) categories relate to sensitive matters. Filter these out when building ad targeting:

safe_categories = []
sensitive_categories = []

for det_id in iab_ids:
    detection = metadata["detections"][det_id]
    iab = detection["ext_refs"]["iab"]

    if iab.get("is_scd_category", False):
        sensitive_categories.append(detection["label"])
    else:
        safe_categories.append(detection["label"])

print(f"Safe for advertising: {safe_categories}")
print(f"Sensitive (SCD): {sensitive_categories}")

Step 4: Match Ads Using Ad Score​

The Ad Score indicates how well a specific ad category fits a specific video section. Higher scores suggest better suitability.

# Find the best ad placement opportunity for each category
ad_opportunities = []

for det_id in section_ids:
    detection = metadata["detections"][det_id]
    ad_score = detection.get("a", {}).get("ad_score", {})

    if ad_score and ad_score.get("max", 0) > 0.1:  # Minimum threshold
        iab = detection["ext_refs"]["iab"]
        ad_opportunities.append({
            "category": " > ".join(iab["labels_hierarchy"]),
            "iab_id": iab["id"],
            "score": ad_score["max"],
            "best_time": ad_score["s_max"],
            "is_scd": iab.get("is_scd_category", False)
        })

# Sort by Ad Score (highest first)
ad_opportunities.sort(key=lambda x: x["score"], reverse=True)

print("\nTop ad placement opportunities:")
for opp in ad_opportunities[:10]:
    scd_flag = " [SCD]" if opp["is_scd"] else ""
    print(f"  {opp['category']}{scd_flag}")
    print(f"    Score: {opp['score']:.3f}, Best time: {opp['best_time']:.0f}s")

Step 5: Combine with Content Compliance​

For brand safety, cross-reference IAB categories with content compliance data:

# Check if any detected content has compliance flags
has_compliance_issues = False
for det_id, detection in metadata["detections"].items():
    if "categ" in detection and "content_compliance" in detection["categ"]["tags"]:
        has_compliance_issues = True
        break

if has_compliance_issues:
    print("\nWARNING: Video contains content compliance flags.")
    print("Consider excluding this video from sensitive ad campaigns.")
else:
    print("\nVideo passed content compliance check.")

Complete Workflow Example​

def analyze_ad_suitability(metadata):
    """Analyze a video for advertising suitability."""
    result = {
        "video_categories": [],
        "section_opportunities": [],
        "scd_categories": [],
        "has_compliance_issues": False,
        "recommendation": "suitable"
    }

    # Video-level categories
    for det_id in metadata["detection_groupings"]["by_detection_type"].get("topic.iab", []):
        det = metadata["detections"][det_id]
        iab = det["ext_refs"]["iab"]
        cat = {"label": det["label"], "id": iab["id"], "scd": iab.get("is_scd_category", False)}
        result["video_categories"].append(cat)
        if cat["scd"]:
            result["scd_categories"].append(cat["label"])

    # Section-level with Ad Score
    for det_id in metadata["detection_groupings"]["by_detection_type"].get("topic.iab.section", []):
        det = metadata["detections"][det_id]
        ad = det.get("a", {}).get("ad_score", {})
        if ad:
            result["section_opportunities"].append({
                "category": det["label"],
                "score": ad["max"],
                "time": ad["s_max"]
            })

    # Content compliance check
    for det_id, det in metadata["detections"].items():
        if "categ" in det and "content_compliance" in det["categ"]["tags"]:
            result["has_compliance_issues"] = True
            result["recommendation"] = "review_required"
            break

    return result