Ad Placement Recommender - clean deploy

.env.example

@@ -0,0 +1,3 @@
+YOUTUBE_API_KEY=your_api_key_here
+GOOGLE_CLIENT_SECRET_FILE=client_secret.json
+CHANNEL_ID=your_channel_id_here

.gitattributes

@@ -0,0 +1,2 @@
+*.png filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,27 @@
+# credentials & secrets
+client_secrets.json
+credentials.json
+token.json
+*.pickle
+.env
+
+# python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+
+# data files (too large for github)
+test_video/
+*.mp4
+
+# generated outputs
+features.csv
+ranked_candidates.json
+final_recommendations.json
+retention_curve.json
+shap_importance.png
+
+# streamlit
+.streamlit/secrets.toml
+client_secret.json

README.md

@@ -0,0 +1,37 @@
+# Retention-Aware Mid-Roll Ad Placement System
+
+## Project Structure
+```
+project/
+├── requirements.txt
+├── .env.example
+├── simulate_and_test.py       ← Start here (no video needed)
+├── component1_candidate_generator.py
+├── component2_feature_extractor.py
+├── candidates.json            ← Output of Component 1
+├── features.csv               ← Output of Component 2
+└── README.md
+```
+
+## Quick Start
+```bash
+# 1. Install dependencies
+pip install -r requirements.txt
+
+# 2. Test the pipeline (no video or API needed)
+python simulate_and_test.py
+python component2_feature_extractor.py
+
+# 3. Run on a real video
+python component1_candidate_generator.py your_video.mp4
+python component2_feature_extractor.py
+```
+
+## Phases
+- [x] Phase 1 — Environment Setup
+- [x] Phase 2 — Component 1: Candidate Generator
+- [x] Phase 3 — Component 2: Feature Extractor (simulated retention)
+- [ ] Phase 4 — Component 3: ML Ranker (LightGBM)
+- [ ] Phase 5 — Component 4: Ad Placement Recommender
+- [ ] Phase 6 — FastAPI + Dashboard
+- [ ] Phase 7 — Evaluation + Research Paper

candidates.json

@@ -0,0 +1,30 @@
+{
+  "total_duration": 454.26666666666665,
+  "candidates": [
+    {
+      "timestamp": 113.87,
+      "type": "scene_change",
+      "score": 92.046
+    },
+    {
+      "timestamp": 186.33,
+      "type": "scene_change",
+      "score": 32.416
+    },
+    {
+      "timestamp": 258.68,
+      "type": "silence",
+      "score": 1.65
+    },
+    {
+      "timestamp": 330.9,
+      "type": "scene_change",
+      "score": 95.956
+    },
+    {
+      "timestamp": 392.02,
+      "type": "silence",
+      "score": 7.15
+    }
+  ]
+}

component1_candidate_generator.py

@@ -0,0 +1,105 @@
+import librosa
+import cv2
+import numpy as np
+import whisper
+import json
+from pathlib import Path
+
+SILENCE_THRESHOLD = 0.01
+SILENCE_MIN_DURATION = 1.5   # seconds
+SCENE_THRESHOLD = 30.0        # frame diff threshold
+MIN_GAP_SECONDS = 60          # min gap between candidates
+
+def detect_silence(audio_path):
+    y, sr = librosa.load(audio_path, sr=None, mono=True)
+    frame_length = int(sr * 0.1)
+    hop_length = frame_length // 2
+    rms = librosa.feature.rms(y=y, frame_length=frame_length, hop_length=hop_length)[0]
+    times = librosa.frames_to_time(np.arange(len(rms)), sr=sr, hop_length=hop_length)
+    candidates = []
+    in_silence = False
+    silence_start = 0
+    for t, r in zip(times, rms):
+        if r < SILENCE_THRESHOLD and not in_silence:
+            in_silence = True
+            silence_start = t
+        elif r >= SILENCE_THRESHOLD and in_silence:
+            duration = t - silence_start
+            if duration >= SILENCE_MIN_DURATION:
+                candidates.append({"timestamp": round(silence_start + duration / 2, 2),
+                                   "type": "silence", "score": round(float(duration), 3)})
+            in_silence = False
+    return candidates
+
+def detect_scene_changes(video_path):
+    cap = cv2.VideoCapture(video_path)
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    candidates = []
+    prev_frame = None
+    frame_idx = 0
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+        if prev_frame is not None:
+            diff = np.mean(np.abs(gray.astype(float) - prev_frame.astype(float)))
+            if diff > SCENE_THRESHOLD:
+                t = round(frame_idx / fps, 2)
+                candidates.append({"timestamp": t, "type": "scene_change", "score": round(float(diff), 3)})
+        prev_frame = gray
+        frame_idx += 1
+    cap.release()
+    return candidates
+
+def detect_transcript_boundaries(audio_path):
+    model = whisper.load_model("base")
+    result = model.transcribe(audio_path, word_timestamps=True)
+    candidates = []
+    segments = result.get("segments", [])
+    for i in range(1, len(segments)):
+        gap = segments[i]["start"] - segments[i-1]["end"]
+        if gap > 1.0:
+            t = round((segments[i-1]["end"] + segments[i]["start"]) / 2, 2)
+            candidates.append({"timestamp": t, "type": "transcript_boundary", "score": round(gap, 3)})
+    return candidates
+
+def merge_candidates(all_candidates, total_duration, min_gap=MIN_GAP_SECONDS):
+    all_candidates.sort(key=lambda x: x["timestamp"])
+    # Remove candidates in first 20% and last 10%
+    start_cut = total_duration * 0.20
+    end_cut = total_duration * 0.90
+    filtered = [c for c in all_candidates if start_cut <= c["timestamp"] <= end_cut]
+    merged = []
+    last_t = -min_gap
+    for c in filtered:
+        if c["timestamp"] - last_t >= min_gap:
+            merged.append(c)
+            last_t = c["timestamp"]
+    return merged
+
+def run(video_path, output_path="candidates.json"):
+    print(f"[Component 1] Processing: {video_path}")
+    cap = cv2.VideoCapture(video_path)
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    frame_count = cap.get(cv2.CAP_PROP_FRAME_COUNT)
+    total_duration = frame_count / fps
+    cap.release()
+    silence = detect_silence(video_path)
+    print(f"  Silence candidates: {len(silence)}")
+    scene = detect_scene_changes(video_path)
+    print(f"  Scene change candidates: {len(scene)}")
+    transcript = detect_transcript_boundaries(video_path)
+    print(f"  Transcript boundary candidates: {len(transcript)}")
+    all_c = silence + scene + transcript
+    merged = merge_candidates(all_c, total_duration)
+    print(f"  Final merged candidates: {len(merged)}")
+    with open(output_path, "w") as f:
+        json.dump({"total_duration": total_duration, "candidates": merged}, f, indent=2)
+    print(f"  Saved to {output_path}")
+    return merged
+
+if __name__ == "__main__":
+    import sys
+    video_path = sys.argv[1] if len(sys.argv) > 1 else "test_video.mp4"
+    run(video_path)

component2_feature_extractor.py

@@ -0,0 +1,101 @@
+"""
+component2_feature_extractor.py — Updated with real YouTube Analytics support
+Simulated : python component2_feature_extractor.py
+Real data : python component2_feature_extractor.py --video-id YOUR_VIDEO_ID
+"""
+
+import json
+import sys
+import pandas as pd
+import numpy as np
+
+
+def simulate_retention_curve(total_duration, seed=42):
+    np.random.seed(seed)
+    t = np.linspace(0, total_duration, int(total_duration))
+    base = 100 * np.exp(-0.003 * t)
+    noise = np.random.normal(0, 2, len(t))
+    spikes = np.zeros(len(t))
+    for _ in range(5):
+        spike_t = np.random.randint(0, len(t))
+        spikes[max(0, spike_t-10):spike_t+10] += np.random.uniform(3, 8)
+    return pd.DataFrame({"second": t, "retention_pct": np.clip(base + noise + spikes, 0, 100)})
+
+
+def get_real_retention_curve(video_id):
+    try:
+        from youtube_analytics import get_retention_curve
+        df = get_retention_curve(video_id)
+        return df
+    except Exception as e:
+        print(f"[Component 2] Warning: {e}")
+        print("[Component 2] Falling back to simulated retention curve")
+        return None
+
+
+def get_retention_at(curve_df, t, window=10):
+    mask   = (curve_df["second"] >= t - window) & (curve_df["second"] <= t + window)
+    subset = curve_df[mask]
+    if subset.empty:
+        return 0.0, 0.0, 0.0
+    at_t_idx       = (subset["second"] - t).abs().idxmin()
+    retention_at_t = curve_df.loc[at_t_idx, "retention_pct"]
+    before         = curve_df[curve_df["second"] < t].tail(30)
+    after          = curve_df[curve_df["second"] > t].head(30)
+    further        = curve_df[curve_df["second"] > t + 30].head(30)
+    drop_rate      = (before["retention_pct"].mean() - after["retention_pct"].mean()) if len(before) and len(after) else 0
+    recovery       = after["retention_pct"].mean() - further["retention_pct"].mean() if len(after) and len(further) else 0
+    return round(float(retention_at_t), 3), round(float(drop_rate), 3), round(float(recovery), 3)
+
+
+def extract_features(candidates_path="candidates.json", video_id=None):
+    with open(candidates_path) as f:
+        data = json.load(f)
+
+    candidates     = data["candidates"]
+    total_duration = data["total_duration"]
+
+    if video_id:
+        print(f"[Component 2] Fetching REAL retention for video: {video_id}")
+        curve_df = get_real_retention_curve(video_id)
+        if curve_df is None:
+            curve_df = simulate_retention_curve(total_duration)
+    else:
+        print("[Component 2] Using SIMULATED retention curve")
+        curve_df = simulate_retention_curve(total_duration)
+
+    rows = []
+    for i, c in enumerate(candidates):
+        t = c["timestamp"]
+        ret_at_t, drop_rate, recovery = get_retention_at(curve_df, t)
+        time_since_last = t - candidates[i-1]["timestamp"] if i > 0 else t
+        rows.append({
+            "timestamp":                 t,
+            "type":                      c["type"],
+            "content_score":             c["score"],
+            "retention_at_t":            ret_at_t,
+            "retention_drop_rate":       drop_rate,
+            "retention_recovery":        recovery,
+            "relative_position":         round(t / total_duration, 4),
+            "time_since_last_candidate": round(time_since_last, 2),
+            "label":                     None
+        })
+
+    df = pd.DataFrame(rows)
+    df["label"] = (
+        (df["retention_at_t"] > df["retention_at_t"].median()) &
+        (df["retention_drop_rate"] < df["retention_drop_rate"].median())
+    ).astype(int)
+
+    df.to_csv("features.csv", index=False)
+    print("[Component 2] features.csv saved ✅")
+    print(df[["timestamp", "type", "retention_at_t", "retention_drop_rate", "label"]].to_string(index=False))
+    return df
+
+
+if __name__ == "__main__":
+    video_id = None
+    if "--video-id" in sys.argv:
+        idx      = sys.argv.index("--video-id")
+        video_id = sys.argv[idx + 1]
+    extract_features(video_id=video_id)

component3_ml_ranker.py

@@ -0,0 +1,150 @@
+"""
+Component 3: ML Ranking Engine
+- Loads features.csv from Component 2
+- Trains a LightGBM model to score each candidate timestamp
+- Outputs ranked_candidates.json with placement scores
+- Generates SHAP feature importance analysis
+"""
+
+import pandas as pd
+import numpy as np
+import lightgbm as lgb
+import shap
+import json
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+
+FEATURES = [
+    "content_score",
+    "retention_at_t",
+    "retention_drop_rate",
+    "retention_recovery",
+    "relative_position",
+    "time_since_last_candidate",
+]
+
+def load_features(path="features.csv"):
+    df = pd.read_csv(path)
+    print(f"[Component 3] Loaded {len(df)} candidates from {path}")
+    print(df[["timestamp", "type", "retention_at_t", "label"]].to_string(index=False))
+    return df
+
+def encode_type(df):
+    type_map = {"silence": 0, "scene_change": 1, "transcript_boundary": 2}
+    df = df.copy()
+    df["type_encoded"] = df["type"].map(type_map).fillna(0).astype(int)
+    return df
+
+def train_model(df):
+    df = encode_type(df)
+    feature_cols = FEATURES + ["type_encoded"]
+    X = df[feature_cols].fillna(0)
+    y = df["label"]
+
+    params = {
+        "objective": "binary",
+        "metric": "auc",
+        "learning_rate": 0.05,
+        "num_leaves": 15,
+        "min_child_samples": 1,
+        "n_estimators": 100,
+        "verbose": -1,
+        "random_state": 42,
+    }
+
+    n_positive = y.sum()
+    n_samples = len(y)
+
+    if n_samples >= 10 and n_positive >= 3:
+        from sklearn.model_selection import StratifiedKFold
+        from sklearn.metrics import roc_auc_score
+        skf = StratifiedKFold(n_splits=3, shuffle=True, random_state=42)
+        auc_scores = []
+        for fold, (train_idx, val_idx) in enumerate(skf.split(X, y)):
+            X_train, X_val = X.iloc[train_idx], X.iloc[val_idx]
+            y_train, y_val = y.iloc[train_idx], y.iloc[val_idx]
+            m = lgb.LGBMClassifier(**params)
+            m.fit(X_train, y_train, callbacks=[lgb.log_evaluation(period=-1)])
+            preds = m.predict_proba(X_val)[:, 1]
+            auc = roc_auc_score(y_val, preds)
+            auc_scores.append(auc)
+            print(f"  Fold {fold+1} AUC: {auc:.4f}")
+        print(f"  Mean CV AUC: {np.mean(auc_scores):.4f}")
+    else:
+        print(f"  [Note] Small dataset ({n_samples} samples, {n_positive} positive)")
+        print(f"  Skipping CV — training directly on all data")
+        print(f"  (CV requires 10+ samples with 3+ positive labels)")
+
+    final_model = lgb.LGBMClassifier(**params)
+    final_model.fit(X, y, callbacks=[lgb.log_evaluation(period=-1)])
+    print("  Final model trained ✅")
+    return final_model, feature_cols
+
+def score_candidates(df, model, feature_cols):
+    df = encode_type(df)
+    X = df[feature_cols].fillna(0)
+    df = df.copy()
+    df["placement_score"] = model.predict_proba(X)[:, 1]
+    df_sorted = df.sort_values("placement_score", ascending=False).reset_index(drop=True)
+    df_sorted["rank"] = df_sorted.index + 1
+    mins = (df_sorted["timestamp"] // 60).astype(int)
+    secs = (df_sorted["timestamp"] % 60).astype(int)
+    df_sorted["timestamp_formatted"] = mins.astype(str) + "m " + secs.astype(str) + "s"
+    return df_sorted
+
+def save_shap_plot(model, df, feature_cols, output_path="shap_importance.png"):
+    df = encode_type(df)
+    X = df[feature_cols].fillna(0)
+    explainer = shap.TreeExplainer(model)
+    shap_values = explainer.shap_values(X)
+    vals = shap_values[1] if isinstance(shap_values, list) else shap_values
+    mean_shap = np.abs(vals).mean(axis=0)
+    feat_imp = pd.Series(mean_shap, index=feature_cols).sort_values(ascending=True)
+    fig, ax = plt.subplots(figsize=(8, 5))
+    feat_imp.plot(kind="barh", ax=ax, color="#6C63FF")
+    ax.set_title("Feature Importance (SHAP)", fontsize=13, fontweight="bold")
+    ax.set_xlabel("Mean |SHAP value|")
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=150)
+    plt.close()
+    print(f"  SHAP plot saved → {output_path}")
+
+def save_results(df_ranked, output_path="ranked_candidates.json"):
+    results = []
+    for _, row in df_ranked.iterrows():
+        results.append({
+            "rank": int(row["rank"]),
+            "timestamp": float(row["timestamp"]),
+            "timestamp_formatted": row["timestamp_formatted"],
+            "type": row["type"],
+            "placement_score": round(float(row["placement_score"]), 4),
+            "retention_at_t": round(float(row["retention_at_t"]), 2),
+            "label": int(row["label"])
+        })
+    with open(output_path, "w") as f:
+        json.dump({"total_candidates": len(results), "ranked_placements": results}, f, indent=2)
+    print(f"  Results saved → {output_path}")
+
+def run(features_path="features.csv"):
+    print("=" * 55)
+    print("  COMPONENT 3: ML RANKING ENGINE")
+    print("=" * 55)
+    df = load_features(features_path)
+    print("\n[Training LightGBM Ranker...]")
+    model, feature_cols = train_model(df)
+    print("\n[Scoring All Candidates...]")
+    df_ranked = score_candidates(df, model, feature_cols)
+    print("\n[Ranked Placement Timestamps]")
+    print(df_ranked[["rank", "timestamp_formatted", "type",
+                      "placement_score", "retention_at_t", "label"]].to_string(index=False))
+    print("\n[Generating SHAP Feature Importance...]")
+    save_shap_plot(model, df, feature_cols)
+    save_results(df_ranked)
+    print("\n✅ Component 3 Complete!")
+    print("   → ranked_candidates.json")
+    print("   → shap_importance.png")
+    print("   Next: python component4_recommender.py")
+
+if __name__ == "__main__":
+    run()

component4_recommender.py

@@ -0,0 +1,131 @@
+"""
+Component 4: Smart Recommender
+- Loads ranked_candidates.json from Component 3
+- Applies business rules to filter and finalize ad placement timestamps
+- Outputs final_recommendations.json — the creator-ready result
+"""
+
+import json
+import os
+
+# ── Business Rule Config (tweak these per creator/video) ──
+CONFIG = {
+    "min_placement_score":    0.0,   # minimum ML score to consider
+    "min_gap_seconds":        120,   # minimum 3 min between placements
+    "skip_intro_pct":         0.20,  # skip first 20% of video
+    "skip_outro_pct":         0.10,  # skip last 10% of video
+    "max_placements":         3,     # max sponsored segments per video
+    "short_video_threshold":  480,   # videos <= 8 min → max 1 placement
+    "post_peak_bonus":        0.05,  # future: boost score if after sentiment peak
+}
+
+def load_ranked(path="ranked_candidates.json"):
+    with open(path) as f:
+        data = json.load(f)
+    placements = data["ranked_placements"]
+    # find total duration from highest timestamp as fallback
+    total_duration = max(p["timestamp"] for p in placements) / 0.80
+    print(f"[Component 4] Loaded {len(placements)} ranked candidates")
+    print(f"  Estimated video duration: {int(total_duration//60)}m {int(total_duration%60)}s")
+    return placements, total_duration
+
+def apply_rules(placements, total_duration, config=CONFIG):
+    print("\n[Applying Business Rules]")
+
+    # Rule 1: Score threshold
+    filtered = [p for p in placements if p["placement_score"] >= config["min_placement_score"]]
+    print(f"  Rule 1 — Score >= {config['min_placement_score']}: {len(filtered)} passed")
+
+    # Rule 2: Skip intro
+    intro_cut = total_duration * config["skip_intro_pct"]
+    filtered = [p for p in filtered if p["timestamp"] >= intro_cut]
+    print(f"  Rule 2 — Skip intro ({int(config['skip_intro_pct']*100)}%, < {int(intro_cut)}s removed): {len(filtered)} remain")
+
+    # Rule 3: Skip outro
+    outro_cut = total_duration * (1 - config["skip_outro_pct"])
+    filtered = [p for p in filtered if p["timestamp"] <= outro_cut]
+    print(f"  Rule 3 — Skip outro ({int(config['skip_outro_pct']*100)}%, > {int(outro_cut)}s removed): {len(filtered)} remain")
+
+    # Rule 4: Max placements for short videos
+    max_allow = 1 if total_duration <= config["short_video_threshold"] else config["max_placements"]
+    print(f"  Rule 4 — Max placements allowed: {max_allow}")
+
+    # Rule 5: Minimum gap enforcement (greedy selection by score)
+    selected = []
+    for p in sorted(filtered, key=lambda x: x["placement_score"], reverse=True):
+        if len(selected) >= max_allow:
+            break
+        too_close = any(abs(p["timestamp"] - s["timestamp"]) < config["min_gap_seconds"] for s in selected)
+        if not too_close:
+            selected.append(p)
+
+    print(f"  Rule 5 — Min gap {config['min_gap_seconds']}s enforced: {len(selected)} final placements")
+    return selected
+
+def format_output(selected, total_duration, config=CONFIG):
+    output = {
+        "video_duration_seconds": round(total_duration, 1),
+        "video_duration_formatted": f"{int(total_duration//60)}m {int(total_duration%60)}s",
+        "total_placements_recommended": len(selected),
+        "config_used": config,
+        "recommendations": []
+    }
+
+    for i, p in enumerate(sorted(selected, key=lambda x: x["timestamp"])):
+        output["recommendations"].append({
+            "placement_number": i + 1,
+            "timestamp_seconds": p["timestamp"],
+            "timestamp_formatted": p["timestamp_formatted"],
+            "type": p["type"],
+            "placement_score": p["placement_score"],
+            "retention_at_t": p["retention_at_t"],
+            "confidence": (
+                "HIGH"   if p["placement_score"] >= 0.75 else
+                "MEDIUM" if p["placement_score"] >= 0.50 else
+                "LOW"
+            ),
+            "creator_note": (
+                f"Place sponsored segment at {p['timestamp_formatted']} — "
+                f"natural {p['type'].replace('_', ' ')} detected, "
+                f"{p['retention_at_t']:.1f}% viewers still watching."
+            )
+        })
+    return output
+
+def print_summary(output):
+    print("\n" + "=" * 55)
+    print("  FINAL RECOMMENDATIONS FOR CREATOR")
+    print("=" * 55)
+    print(f"  Video Duration : {output['video_duration_formatted']}")
+    print(f"  Placements     : {output['total_placements_recommended']}")
+    print()
+    if not output["recommendations"]:
+        print("  ⚠️  No suitable placement found.")
+        print("  Suggestion: Lower min_placement_score in CONFIG")
+        print("              or collect more video data for better ML labels.")
+    else:
+        for r in output["recommendations"]:
+            print(f"  📍 Placement {r['placement_number']}")
+            print(f"     Timestamp  : {r['timestamp_formatted']}")
+            print(f"     Type       : {r['type']}")
+            print(f"     Score      : {r['placement_score']} ({r['confidence']})")
+            print(f"     Retention  : {r['retention_at_t']}% viewers watching")
+            print(f"     Note       : {r['creator_note']}")
+            print()
+
+def run(ranked_path="ranked_candidates.json", output_path="final_recommendations.json"):
+    print("=" * 55)
+    print("  COMPONENT 4: SMART RECOMMENDER")
+    print("=" * 55)
+    placements, total_duration = load_ranked(ranked_path)
+    selected = apply_rules(placements, total_duration)
+    output = format_output(selected, total_duration)
+    print_summary(output)
+    with open(output_path, "w") as f:
+        json.dump(output, f, indent=2)
+    print(f"✅ Component 4 Complete!")
+    print(f"   → {output_path}")
+    print(f"   Next: python dashboard.py  (Streamlit visualization)")
+
+if __name__ == "__main__":
+    run()

dashboard.py

@@ -0,0 +1,437 @@
+"""
+Dashboard — Creator-Friendly Ad Placement Recommender
+Full OAuth login + integrated pipeline (no subprocess)
+"""
+
+import streamlit as st
+import json
+import os
+import tempfile
+import pandas as pd
+import plotly.graph_objects as go
+
+# ── Page Config ──
+st.set_page_config(
+    page_title="Ad Placement Recommender",
+    page_icon="🎯",
+    layout="wide"
+)
+
+# ── Custom CSS ──
+st.markdown("""
+<style>
+    .main { background-color: #0e1117; }
+    .big-title { font-size:2.2rem; font-weight:800; color:#ffffff; }
+    .subtitle  { font-size:1rem; color:#aaaaaa; margin-bottom:2rem; }
+    .metric-box {
+        background:#1c1f26; border-radius:12px;
+        padding:1.2rem; text-align:center;
+    }
+    .metric-label { font-size:0.85rem; color:#888; margin-bottom:4px; }
+    .metric-value { font-size:2rem; font-weight:700; color:#ffffff; }
+    .placement-card {
+        background:#1a2a1a; border:1px solid #2a5a2a;
+        border-radius:12px; padding:1.4rem; margin-bottom:1rem;
+    }
+    .placement-card-warn {
+        background:#2a2a1a; border:1px solid #5a5a2a;
+        border-radius:12px; padding:1.4rem; margin-bottom:1rem;
+    }
+    .placement-card-bad {
+        background:#2a1a1a; border:1px solid #5a2a2a;
+        border-radius:12px; padding:1.4rem; margin-bottom:1rem;
+    }
+    .tip-box {
+        background:#111827; border-left:4px solid #3b82f6;
+        border-radius:8px; padding:1rem; margin-top:0.5rem;
+        font-size:0.9rem; color:#cbd5e1;
+    }
+    .section-header {
+        font-size:1.3rem; font-weight:700;
+        color:#ffffff; margin:2rem 0 1rem 0;
+    }
+    .badge-green  { background:#166534; color:#86efac; padding:3px 10px; border-radius:20px; font-size:0.8rem; }
+    .badge-yellow { background:#713f12; color:#fde68a; padding:3px 10px; border-radius:20px; font-size:0.8rem; }
+    .badge-red    { background:#7f1d1d; color:#fca5a5; padding:3px 10px; border-radius:20px; font-size:0.8rem; }
+    .stButton>button {
+        background:linear-gradient(135deg,#3b82f6,#8b5cf6);
+        color:white; border:none; border-radius:10px;
+        padding:0.7rem 2rem; font-size:1rem; font-weight:600;
+        width:100%; cursor:pointer;
+    }
+    .login-card {
+        background:#1c1f26; border-radius:16px;
+        padding:2.5rem; text-align:center; max-width:480px; margin:auto;
+    }
+</style>
+""", unsafe_allow_html=True)
+
+
+# ── Helpers ──
+
+def get_spot_quality(retention):
+    if retention >= 50:
+        return "🟢", "Great Spot",   "placement-card",      "badge-green"
+    elif retention >= 30:
+        return "🟡", "Decent Spot",  "placement-card-warn", "badge-yellow"
+    else:
+        return "🔴", "Weak Spot",    "placement-card-bad",  "badge-red"
+
+def get_type_label(t):
+    return {
+        "scene_change":        "🎬 Natural scene break",
+        "silence":             "🔇 Quiet moment",
+        "transcript_boundary": "🗣️ Topic change"
+    }.get(t, t)
+
+def get_type_tip(t):
+    return {
+        "scene_change":        "The video visually transitions here — viewers naturally expect a brief pause. Perfect for a sponsorship read.",
+        "silence":             "There's a quiet gap in audio here — inserting an ad won't feel jarring or cut off speech.",
+        "transcript_boundary": "The speaker shifts to a new topic — a natural mental break for the viewer."
+    }.get(t, "Natural break detected in the video.")
+
+def extract_video_id(url):
+    import re
+    for pattern in [r"youtu\.be/([^?&]+)", r"youtube\.com/watch\?v=([^&]+)"]:
+        m = re.search(pattern, url)
+        if m:
+            return m.group(1)
+    if re.match(r'^[A-Za-z0-9_-]{11}$', url.strip()):
+        return url.strip()
+    return None
+
+def load_json(path):
+    if not os.path.exists(path):
+        return None
+    with open(path) as f:
+        return json.load(f)
+
+
+# ══════════════════════════════════════════════
+#  HEADER
+# ══════════════════════════════════════════════
+st.markdown('<div class="big-title">🎯 Ad Placement Recommender</div>', unsafe_allow_html=True)
+st.markdown('<div class="subtitle">Find the perfect moments in your video to place ads — so viewers stay happy and you earn more.</div>', unsafe_allow_html=True)
+
+
+# ══════════════════════════════════════════════
+#  AUTH GATE
+# ══════════════════════════════════════════════
+from youtube_auth import get_credentials, show_login_button, logout
+
+creds = get_credentials()
+
+if creds is None:
+    st.markdown("---")
+    st.markdown("""
+    <div class="login-card">
+        <div style="font-size:3rem;">🔐</div>
+        <div style="font-size:1.3rem; font-weight:700; color:#fff; margin:1rem 0;">
+            Connect Your YouTube Account
+        </div>
+        <div style="color:#9ca3af; font-size:0.9rem; margin-bottom:1.5rem;">
+            We need read-only access to your YouTube Analytics<br>
+            to see where viewers drop off in your videos.<br><br>
+            <b style="color:#6ee7b7;">We never post, modify or delete anything.</b>
+        </div>
+    </div>
+    """, unsafe_allow_html=True)
+
+    auth_url = show_login_button()
+    col1, col2, col3 = st.columns([1, 2, 1])
+    with col2:
+        st.markdown(f"""
+        <a href="{auth_url}" target="_self" style="text-decoration:none;">
+            <div style="
+                background:linear-gradient(135deg,#ff0000,#cc0000);
+                color:white; border-radius:12px; padding:1rem 2rem;
+                font-size:1.1rem; font-weight:700; text-align:center;
+                margin-top:1.5rem; cursor:pointer;
+            ">
+                🎬 Login with YouTube
+            </div>
+        </a>
+        """, unsafe_allow_html=True)
+    st.stop()
+
+# ── Logged in — show logout in sidebar ──
+with st.sidebar:
+    st.markdown("### 👤 Account")
+    st.success("✅ YouTube Connected")
+    if st.button("🚪 Logout"):
+        logout()
+        st.rerun()
+    st.markdown("---")
+    st.markdown("### ℹ️ How It Works")
+    st.markdown("""
+    1. 🔗 Paste your YouTube video URL
+    2. 🎬 Upload the same video as `.mp4`
+    3. 🚀 Click Analyze
+    4. 📍 See exactly where to place ads
+    """)
+
+
+# ══════════════════════════════════════════════
+#  INPUT FORM
+# ══════════════════════════════════════════════
+st.markdown('<div class="section-header">📥 Analyze Your Video</div>', unsafe_allow_html=True)
+
+col1, col2 = st.columns([1, 1])
+with col1:
+    yt_input = st.text_input(
+        "🔗 YouTube Video URL",
+        placeholder="https://youtu.be/4Rq-LY16WxM",
+        help="Must be YOUR video — we need access to its analytics"
+    )
+with col2:
+    uploaded_file = st.file_uploader(
+        "🎬 Upload Your Video File (.mp4)",
+        type=["mp4"],
+        help="Upload the same video you posted on YouTube"
+    )
+
+analyze_btn = st.button("🚀 Analyze My Video & Find Best Ad Spots")
+
+if analyze_btn:
+    if not yt_input or not uploaded_file:
+        st.warning("⚠️ Please provide both your YouTube URL and upload your video file.")
+    else:
+        video_id = extract_video_id(yt_input)
+        if not video_id:
+            st.error("❌ Could not extract video ID. Please check your YouTube URL.")
+        else:
+            # Save uploaded video to temp file
+            os.makedirs("test_video", exist_ok=True)
+            save_path = os.path.join("test_video", uploaded_file.name)
+            with open(save_path, "wb") as f:
+                f.write(uploaded_file.getbuffer())
+
+            # Run pipeline with live progress
+            from pipeline import run_full_pipeline
+
+            progress_box = st.empty()
+            progress_bar = st.progress(0)
+            steps_done   = [0]
+
+            def on_progress(msg):
+                progress_box.info(msg)
+                steps_done[0] += 1
+                progress_bar.progress(min(steps_done[0] / 4, 1.0))
+
+            try:
+                with st.spinner("Analyzing your video... this takes 2–4 minutes ⏳"):
+                    run_full_pipeline(save_path, video_id, creds, progress_callback=on_progress)
+                progress_bar.progress(1.0)
+                progress_box.success("✅ Analysis complete!")
+                st.rerun()
+            except Exception as e:
+                st.error(f"❌ Pipeline error: {str(e)}")
+                st.info("💡 Make sure your video is public or unlisted and belongs to your connected YouTube channel.")
+
+st.markdown("---")
+
+
+# ══════════════════════════════════════════════
+#  LOAD RESULTS
+# ══════════════════════════════════════════════
+data       = load_json("final_recommendations.json")
+candidates = load_json("ranked_candidates.json")
+retention  = load_json("retention_curve.json")
+
+if not data:
+    st.info("👆 Enter your YouTube URL and upload your video above to get started.")
+    st.stop()
+
+recs         = data.get("recommendations", [])
+duration     = data.get("video_duration_formatted", "N/A")
+total_placed = data.get("total_placements_recommended", 0)
+cands_list   = candidates.get("ranked_placements", []) if candidates else []
+top_ret      = max((c["retention_at_t"] for c in cands_list), default=0)
+
+
+# ══════════════════════════════════════════════
+#  METRICS
+# ══════════════════════════════════════════════
+m1, m2, m3, m4 = st.columns(4)
+metrics = [
+    ("🎬 Video Duration",         duration,           "#ffffff"),
+    ("📍 Best Ad Spots Found",    total_placed,       "#22c55e" if total_placed > 0 else "#ef4444"),
+    ("🔬 Moments Analyzed",       len(cands_list),    "#ffffff"),
+    ("👀 Best Spot Retention",    f"{top_ret:.0f}%",  "#22c55e" if top_ret >= 50 else "#f59e0b"),
+]
+for col, (label, value, color) in zip([m1, m2, m3, m4], metrics):
+    with col:
+        st.markdown(f"""
+        <div class="metric-box">
+            <div class="metric-label">{label}</div>
+            <div class="metric-value" style="color:{color};">{value}</div>
+        </div>""", unsafe_allow_html=True)
+
+st.markdown("<br>", unsafe_allow_html=True)
+
+
+# ══════════════════════════════════════════════
+#  RETENTION CURVE
+# ══════════════════════════════════════════════
+st.markdown('<div class="section-header">📈 Your Viewer Retention Curve</div>', unsafe_allow_html=True)
+st.caption("This shows how many viewers are still watching at each moment. The markers show your recommended ad spots.")
+
+if retention:
+    times  = [p["time_seconds"]     for p in retention]
+    values = [p["retention_percent"] for p in retention]
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=times, y=values, mode="lines",
+        name="Viewer Retention",
+        line=dict(color="#6366f1", width=2),
+        fill="tozeroy", fillcolor="rgba(99,102,241,0.15)"
+    ))
+
+    colors = ["#22c55e", "#f59e0b", "#ef4444"]
+    for i, r in enumerate(recs):
+        color = colors[i % len(colors)]
+        fig.add_vline(
+            x=r["timestamp_seconds"], line_dash="dash",
+            line_color=color, line_width=2,
+            annotation_text=f"📍 Ad {r['placement_number']} ({r['timestamp_formatted']})",
+            annotation_font_color=color
+        )
+
+    fig.update_layout(
+        plot_bgcolor="#0e1117", paper_bgcolor="#0e1117",
+        font_color="white", height=380,
+        xaxis=dict(title="Time (seconds)", gridcolor="#1f2937"),
+        yaxis=dict(title="Viewers Still Watching (%)", gridcolor="#1f2937", range=[0, 105]),
+        margin=dict(l=20, r=20, t=30, b=40)
+    )
+    st.plotly_chart(fig, use_container_width=True)
+
+st.markdown("---")
+
+
+# ══════════════════════════════════════════════
+#  RECOMMENDATIONS
+# ══════════════════════════════════════════════
+st.markdown('<div class="section-header">🎯 Where to Place Your Ad</div>', unsafe_allow_html=True)
+
+if not recs:
+    st.markdown("""
+    <div style="background:#1c1f26;border-radius:12px;padding:1.5rem;text-align:center;">
+        <div style="font-size:2rem;">😕</div>
+        <div style="font-size:1.1rem;color:#f87171;font-weight:600;margin:0.5rem 0;">
+            No strong ad spots found for this video
+        </div>
+        <div style="color:#9ca3af;font-size:0.9rem;">
+            This usually means viewer retention dropped too quickly.<br>
+            Try a video where viewers watch past the halfway point.
+        </div>
+    </div>
+    """, unsafe_allow_html=True)
+else:
+    for r in recs:
+        emoji, quality, card_class, badge_class = get_spot_quality(r["retention_at_t"])
+        type_label = get_type_label(r["type"])
+        type_tip   = get_type_tip(r["type"])
+        ret        = r["retention_at_t"]
+        conf_color = "#22c55e" if r["confidence"] == "HIGH" else "#f59e0b" if r["confidence"] == "MEDIUM" else "#94a3b8"
+
+        st.markdown(f"""
+        <div class="{card_class}">
+            <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:0.8rem;">
+                <div style="font-size:1.2rem;font-weight:700;color:#ffffff;">
+                    📍 Ad Spot {r['placement_number']} &nbsp;—&nbsp; {r['timestamp_formatted']}
+                </div>
+                <span class="{badge_class}">{emoji} {quality}</span>
+            </div>
+            <div style="display:flex;gap:2rem;margin-bottom:0.8rem;flex-wrap:wrap;">
+                <div>
+                    <div style="color:#888;font-size:0.8rem;">VIEWERS WATCHING</div>
+                    <div style="font-size:1.5rem;font-weight:700;color:#ffffff;">{ret:.0f}%</div>
+                </div>
+                <div>
+                    <div style="color:#888;font-size:0.8rem;">BREAK TYPE</div>
+                    <div style="font-size:1rem;font-weight:600;color:#e2e8f0;">{type_label}</div>
+                </div>
+                <div>
+                    <div style="color:#888;font-size:0.8rem;">CONFIDENCE</div>
+                    <div style="font-size:1rem;font-weight:600;color:{conf_color};">{r['confidence']}</div>
+                </div>
+            </div>
+            <div class="tip-box">
+                💡 <b>Why this spot?</b> {type_tip}<br><br>
+                🎬 <b>What to do:</b> Place your sponsorship or enable mid-roll at <b>{r['timestamp_formatted']}</b>.
+                At this moment, <b>{ret:.0f}% of your audience</b> is still watching.
+            </div>
+        </div>
+        """, unsafe_allow_html=True)
+
+st.markdown("---")
+
+
+# ══════════════════════════════════════════════
+#  INSIGHTS FOR NEXT VIDEO
+# ══════════════════════════════════════════════
+st.markdown('<div class="section-header">📊 Insights for Your Next Video</div>', unsafe_allow_html=True)
+
+if cands_list:
+    df = pd.DataFrame(cands_list)
+    best_ret  = df["retention_at_t"].max()
+    worst_ret = df["retention_at_t"].min()
+    avg_ret   = df["retention_at_t"].mean()
+    drop_time = df.loc[df["retention_at_t"].idxmin(), "timestamp_formatted"]
+
+    i1, i2, i3 = st.columns(3)
+    for col, label, value, color, sub in [
+        (i1, "🏆 Peak Retention Spot",    f"{best_ret:.0f}%",  "#22c55e", "viewers at best moment"),
+        (i2, "📉 Biggest Drop-Off At",    drop_time,           "#ef4444", "most viewers left here"),
+        (i3, "📊 Avg Retention at Breaks", f"{avg_ret:.0f}%",  "#f59e0b", "across all detected moments"),
+    ]:
+        with col:
+            st.markdown(f"""
+            <div class="metric-box">
+                <div class="metric-label">{label}</div>
+                <div class="metric-value" style="color:{color};">{value}</div>
+                <div style="color:#888;font-size:0.8rem;">{sub}</div>
+            </div>""", unsafe_allow_html=True)
+
+    st.markdown("<br>", unsafe_allow_html=True)
+    st.markdown("#### 💡 What This Means for Your Next Video")
+
+    tips = []
+    if best_ret >= 60:
+        tips.append("✅ **Strong early retention** — your intro hooks viewers well. Keep doing what you did in the first 2 minutes.")
+    if worst_ret < 25:
+        tips.append(f"⚠️ **Viewers drop off near {drop_time}** — tighten that section or add a re-engagement hook (a question, teaser, or visual change).")
+    if avg_ret < 35:
+        tips.append("📉 **Overall retention is low** — try shorter videos or stronger pacing to keep viewers engaged longer.")
+    if avg_ret >= 50:
+        tips.append("🎉 **Great overall retention** — your audience is engaged. You can confidently place ads and expect good visibility.")
+    if total_placed == 0:
+        tips.append("🔴 **No strong ad spots this time** — aim to keep 40%+ viewers watching past the 2-minute mark.")
+
+    for tip in tips:
+        st.markdown(f"- {tip}")
+
+
+# ══════════════════════════════════════════════
+#  ADVANCED TABLE
+# ══════════════════════════════════════════════
+st.markdown("---")
+with st.expander("🔬 View All Analyzed Moments (Advanced)"):
+    if cands_list:
+        df_show = pd.DataFrame(cands_list)[["timestamp_formatted", "type", "retention_at_t", "placement_score"]]
+        df_show.columns = ["Timestamp", "Break Type", "Viewers Watching (%)", "ML Score"]
+        df_show["Break Type"]           = df_show["Break Type"].map(get_type_label)
+        df_show["Viewers Watching (%)"] = df_show["Viewers Watching (%)"].map(lambda x: f"{x:.1f}%")
+        df_show["ML Score"]             = df_show["ML Score"].map(lambda x: f"{x:.4f}")
+        st.dataframe(df_show, use_container_width=True, hide_index=True)
+
+
+# ── Footer ──
+st.markdown("<br>", unsafe_allow_html=True)
+st.markdown(
+    '<div style="text-align:center;color:#4b5563;font-size:0.8rem;">Ad Placement Recommender • Built for YouTube Creators</div>',
+    unsafe_allow_html=True
+)

pipeline.py

@@ -0,0 +1,308 @@
+"""
+pipeline.py — Runs full pipeline as functions (no subprocess needed on Render)
+"""
+
+import json
+import os
+import tempfile
+import numpy as np
+import pandas as pd
+
+
+# ── Component 1: Candidate Generator ──────────────────────────
+
+def run_component1(video_path):
+    """Extract scene changes, silences, transcript boundaries from video."""
+    import cv2
+    from pydub import AudioSegment
+    from pydub.silence import detect_silence
+
+    candidates = []
+    total_duration = 0
+
+    # Get video duration
+    cap = cv2.VideoCapture(video_path)
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    frame_count = cap.get(cv2.CAP_PROP_FRAME_COUNT)
+    total_duration = frame_count / fps if fps > 0 else 0
+
+    # Scene change detection
+    prev_frame = None
+    frame_idx  = 0
+    scene_threshold = 30.0
+
+    while True:
+        ret, frame = cap.read()
+        if not ret:
+            break
+        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+        if prev_frame is not None:
+            diff = cv2.absdiff(gray, prev_frame)
+            score = diff.mean()
+            if score > scene_threshold:
+                timestamp = frame_idx / fps
+                if timestamp > 30:  # skip first 30s
+                    candidates.append({
+                        "timestamp": round(timestamp, 2),
+                        "type":      "scene_change",
+                        "score":     round(float(score), 3)
+                    })
+        prev_frame = gray
+        frame_idx += 1
+    cap.release()
+
+    # Silence detection
+    try:
+        audio = AudioSegment.from_file(video_path)
+        silences = detect_silence(audio, min_silence_len=800, silence_thresh=-40)
+        for start_ms, end_ms in silences:
+            mid = (start_ms + end_ms) / 2 / 1000
+            if mid > 30 and mid < total_duration - 30:
+                candidates.append({
+                    "timestamp": round(mid, 2),
+                    "type":      "silence",
+                    "score":     0.6
+                })
+    except Exception as e:
+        print(f"[Component 1] Audio extraction warning: {e}")
+
+    # Deduplicate — remove candidates within 5s of each other
+    candidates = sorted(candidates, key=lambda x: x["timestamp"])
+    deduped = []
+    for c in candidates:
+        if not deduped or abs(c["timestamp"] - deduped[-1]["timestamp"]) > 5:
+            deduped.append(c)
+
+    data = {"candidates": deduped, "total_duration": round(total_duration, 2)}
+    with open("candidates.json", "w") as f:
+        json.dump(data, f, indent=2)
+
+    print(f"[Component 1] {len(deduped)} candidates found, duration: {total_duration:.1f}s")
+    return data
+
+
+# ── Component 2: Feature Extractor ────────────────────────────
+
+def run_component2(video_id, creds):
+    """Fetch retention data and extract features."""
+    from youtube_analytics import get_retention_curve
+
+    with open("candidates.json") as f:
+        data = json.load(f)
+
+    candidates     = data["candidates"]
+    total_duration = data["total_duration"]
+
+    curve_df = get_retention_curve(video_id, creds=creds)
+
+    rows = []
+    for i, c in enumerate(candidates):
+        t = c["timestamp"]
+
+        # Get retention at timestamp
+        mask   = (curve_df["second"] >= t - 10) & (curve_df["second"] <= t + 10)
+        subset = curve_df[mask]
+        if subset.empty:
+            ret_at_t, drop_rate, recovery = 0.0, 0.0, 0.0
+        else:
+            idx      = (subset["second"] - t).abs().idxmin()
+            ret_at_t = float(curve_df.loc[idx, "retention_pct"])
+            before   = curve_df[curve_df["second"] < t].tail(30)
+            after    = curve_df[curve_df["second"] > t].head(30)
+            further  = curve_df[curve_df["second"] > t + 30].head(30)
+            drop_rate = float(before["retention_pct"].mean() - after["retention_pct"].mean()) if len(before) and len(after) else 0
+            recovery  = float(after["retention_pct"].mean() - further["retention_pct"].mean()) if len(after) and len(further) else 0
+
+        time_since_last = t - candidates[i-1]["timestamp"] if i > 0 else t
+        rows.append({
+            "timestamp":                 round(t, 2),
+            "type":                      c["type"],
+            "content_score":             c["score"],
+            "retention_at_t":            round(ret_at_t, 3),
+            "retention_drop_rate":       round(drop_rate, 3),
+            "retention_recovery":        round(recovery, 3),
+            "relative_position":         round(t / total_duration, 4),
+            "time_since_last_candidate": round(time_since_last, 2),
+            "label":                     0
+        })
+
+    df = pd.DataFrame(rows)
+    if len(df) > 1:
+        df["label"] = (
+            (df["retention_at_t"] > df["retention_at_t"].median()) &
+            (df["retention_drop_rate"] < df["retention_drop_rate"].median())
+        ).astype(int)
+
+    df.to_csv("features.csv", index=False)
+    print(f"[Component 2] features.csv saved — {len(df)} candidates")
+    return df
+
+
+# ── Component 3: ML Ranker ─────────────────────────────────────
+
+def run_component3():
+    """Train LightGBM ranker and score all candidates."""
+    import lightgbm as lgb
+    from sklearn.preprocessing import LabelEncoder
+
+    df = pd.read_csv("features.csv")
+
+    feature_cols = [
+        "retention_at_t", "retention_drop_rate", "retention_recovery",
+        "relative_position", "time_since_last_candidate", "content_score"
+    ]
+
+    le = LabelEncoder()
+    df["type_enc"] = le.fit_transform(df["type"])
+    feature_cols.append("type_enc")
+
+    X = df[feature_cols].fillna(0)
+    y = df["label"].fillna(0).astype(int)
+
+    n_pos = y.sum()
+    print(f"[Component 3] Training LightGBM — {len(df)} samples, {n_pos} positive")
+
+    model = lgb.LGBMClassifier(
+        n_estimators=100,
+        learning_rate=0.05,
+        num_leaves=15,
+        random_state=42,
+        verbose=-1
+    )
+    model.fit(X, y)
+
+    scores = model.predict_proba(X)[:, 1]
+    df["placement_score"] = scores
+
+    def fmt(t):
+        return f"{int(t//60)}m {int(t%60):02d}s"
+
+    placements = []
+    for _, row in df.iterrows():
+        placements.append({
+            "timestamp":           row["timestamp"],
+            "timestamp_formatted": fmt(row["timestamp"]),
+            "type":                row["type"],
+            "placement_score":     float(row["placement_score"]),
+            "retention_at_t":      float(row["retention_at_t"]),
+            "label":               int(row["label"])
+        })
+
+    placements = sorted(placements, key=lambda x: x["placement_score"], reverse=True)
+    for i, p in enumerate(placements):
+        p["rank"] = i + 1
+
+    result = {"ranked_placements": placements}
+    with open("ranked_candidates.json", "w") as f:
+        json.dump(result, f, indent=2)
+
+    print(f"[Component 3] Ranked {len(placements)} candidates")
+    return placements
+
+
+# ── Component 4: Recommender ───────────────────────────────────
+
+def run_component4():
+    """Apply business rules and generate final recommendations."""
+
+    CONFIG = {
+        "min_placement_score":   0.0,
+        "min_gap_seconds":       120,
+        "skip_intro_pct":        0.20,
+        "skip_outro_pct":        0.10,
+        "max_placements":        3,
+        "short_video_threshold": 480,
+    }
+
+    with open("ranked_candidates.json") as f:
+        data = json.load(f)
+
+    placements     = data["ranked_placements"]
+    total_duration = max(p["timestamp"] for p in placements) / 0.80
+
+    # Rule 1: Score threshold
+    filtered = [p for p in placements if p["placement_score"] >= CONFIG["min_placement_score"]]
+
+    # Rule 2: Skip intro
+    intro_cut = total_duration * CONFIG["skip_intro_pct"]
+    filtered  = [p for p in filtered if p["timestamp"] >= intro_cut]
+
+    # Rule 3: Skip outro
+    outro_cut = total_duration * (1 - CONFIG["skip_outro_pct"])
+    filtered  = [p for p in filtered if p["timestamp"] <= outro_cut]
+
+    # Rule 4: Max placements
+    max_allow = 1 if total_duration <= CONFIG["short_video_threshold"] else CONFIG["max_placements"]
+
+    # Rule 5: Min gap (greedy)
+    selected = []
+    for p in sorted(filtered, key=lambda x: x["placement_score"], reverse=True):
+        if len(selected) >= max_allow:
+            break
+        too_close = any(abs(p["timestamp"] - s["timestamp"]) < CONFIG["min_gap_seconds"] for s in selected)
+        if not too_close:
+            selected.append(p)
+
+    def fmt(t):
+        return f"{int(t//60)}m {int(t%60):02d}s"
+
+    output = {
+        "video_duration_seconds":      round(total_duration, 1),
+        "video_duration_formatted":    fmt(total_duration),
+        "total_placements_recommended": len(selected),
+        "config_used":                 CONFIG,
+        "recommendations": []
+    }
+
+    for i, p in enumerate(sorted(selected, key=lambda x: x["timestamp"])):
+        ret = p["retention_at_t"]
+        output["recommendations"].append({
+            "placement_number":    i + 1,
+            "timestamp_seconds":   p["timestamp"],
+            "timestamp_formatted": p["timestamp_formatted"],
+            "type":                p["type"],
+            "placement_score":     p["placement_score"],
+            "retention_at_t":      ret,
+            "confidence": (
+                "HIGH"   if p["placement_score"] >= 0.75 else
+                "MEDIUM" if p["placement_score"] >= 0.50 else
+                "LOW"
+            ),
+            "creator_note": (
+                f"Place sponsored segment at {p['timestamp_formatted']} — "
+                f"natural {p['type'].replace('_', ' ')} detected, "
+                f"{ret:.1f}% viewers still watching."
+            )
+        })
+
+    with open("final_recommendations.json", "w") as f:
+        json.dump(output, f, indent=2)
+
+    print(f"[Component 4] {len(selected)} final placements recommended")
+    return output
+
+
+# ── Full Pipeline ──────────────────────────────────────────────
+
+def run_full_pipeline(video_path, video_id, creds, progress_callback=None):
+    """Run all 4 components in sequence. Returns final recommendations."""
+
+    def update(msg):
+        print(msg)
+        if progress_callback:
+            progress_callback(msg)
+
+    update("🔍 Step 1/4 — Detecting natural break points in your video...")
+    run_component1(video_path)
+
+    update("📊 Step 2/4 — Fetching viewer retention data from YouTube...")
+    run_component2(video_id, creds)
+
+    update("🤖 Step 3/4 — Running ML ranking engine...")
+    run_component3()
+
+    update("🎯 Step 4/4 — Generating final recommendations...")
+    result = run_component4()
+
+    update("✅ Analysis complete!")
+    return result

render.yaml

@@ -0,0 +1,9 @@
+services:
+  - type: web
+    name: ad-placement-recommender
+    runtime: python
+    buildCommand: pip install -r requirements.txt
+    startCommand: streamlit run dashboard.py --server.port $PORT --server.address 0.0.0.0
+    envVars:
+      - key: PYTHON_VERSION
+        value: 3.11.0

simulate_and_test.py

@@ -0,0 +1,24 @@
+"""
+Quick test: simulates candidates.json then runs Component 2
+No real video or API needed — run this first to verify the pipeline.
+"""
+import json, numpy as np
+
+total_duration = 600  # 10-minute video
+
+# Simulate Component 1 output
+np.random.seed(0)
+candidates = []
+for t in range(120, 540, 70):
+    t += np.random.randint(-10, 10)
+    candidates.append({
+        "timestamp": float(t),
+        "type": np.random.choice(["silence", "scene_change", "transcript_boundary"]),
+        "score": round(np.random.uniform(0.5, 5.0), 3)
+    })
+
+with open("candidates.json", "w") as f:
+    json.dump({"total_duration": total_duration, "candidates": candidates}, f, indent=2)
+
+print("candidates.json created with", len(candidates), "candidates")
+print("Now run: python component2_feature_extractor.py")

test_retention.py

@@ -0,0 +1,18 @@
+from youtube_analytics import get_retention_curve
+
+video_ids = [
+    "USVNGTw2pKM",  # Dijkstra is Dead
+    "okPBQ0Ekafw",
+    "FU78qBHeQf0",
+    "4Rq-LY16WxM",  # FlashGuard
+    "LpihkA9KWqo",
+]
+
+for vid in video_ids:
+    print(f"\nTrying: {vid}")
+    df = get_retention_curve(vid)
+    if df is not None:
+        print(f"  ✅ Has retention data! ({len(df)} points)")
+        print(df.head(5).to_string(index=False))
+    else:
+        print(f"  ⚠️  No data yet")

youtube_analytics.py

@@ -0,0 +1,113 @@
+"""
+youtube_analytics.py — Fetches real retention curve from YouTube Analytics API
+"""
+
+import pandas as pd
+import numpy as np
+from googleapiclient.discovery import build
+
+
+def get_video_duration(video_id, creds):
+    youtube = build("youtube", "v3", credentials=creds)
+    response = youtube.videos().list(
+        part="contentDetails,snippet",
+        id=video_id
+    ).execute()
+
+    if not response["items"]:
+        raise ValueError(f"Video {video_id} not found or is private.")
+
+    item = response["items"][0]
+    duration_iso = item["contentDetails"]["duration"]
+    title = item["snippet"]["title"]
+
+    # Parse ISO 8601 duration
+    import re
+    match = re.match(r'PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?', duration_iso)
+    hours   = int(match.group(1) or 0)
+    minutes = int(match.group(2) or 0)
+    seconds = int(match.group(3) or 0)
+    total_seconds = hours * 3600 + minutes * 60 + seconds
+
+    print(f"[Analytics] Video: {title}")
+    print(f"[Analytics] Duration: {hours}h {minutes}m {seconds}s ({total_seconds}s)")
+    return total_seconds, title
+
+
+def get_retention_curve(video_id, creds=None):
+    if creds is None:
+        from youtube_auth import get_credentials
+        creds = get_credentials()
+
+    try:
+        total_duration, title = get_video_duration(video_id, creds)
+    except Exception as e:
+        print(f"[Analytics] Could not get video duration: {e}")
+        total_duration = 600
+
+    try:
+        analytics = build("youtubeAnalytics", "v2", credentials=creds)
+        response = analytics.reports().query(
+            ids="channel==MINE",
+            startDate="2020-01-01",
+            endDate="2030-01-01",
+            metrics="audienceWatchRatio",
+            dimensions="elapsedVideoTimeRatio",
+            filters=f"video=={video_id}",
+            maxResults=100
+        ).execute()
+
+        rows = response.get("rows", [])
+        if not rows:
+            raise ValueError("No retention data returned from YouTube Analytics.")
+
+        print(f"[Analytics] Fetched {len(rows)} retention data points for {video_id}")
+
+        ratios     = [r[0] for r in rows]
+        watch_vals = [r[1] for r in rows]
+        max_watch  = max(watch_vals) if watch_vals else 1
+
+        df = pd.DataFrame({
+            "second":        [r * total_duration for r in ratios],
+            "retention_pct": [min((v / max_watch) * 100, 100) for v in watch_vals]
+        })
+
+        # Save for dashboard chart
+        curve_json = [
+            {"time_seconds": round(row["second"], 2), "retention_percent": round(row["retention_pct"], 2)}
+            for _, row in df.iterrows()
+        ]
+        import json
+        with open("retention_curve.json", "w") as f:
+            json.dump(curve_json, f)
+
+        return df
+
+    except Exception as e:
+        print(f"[Analytics] Error fetching retention: {e}")
+        print("[Analytics] Falling back to simulated curve")
+        return simulate_retention_curve(total_duration)
+
+
+def simulate_retention_curve(total_duration, seed=42):
+    np.random.seed(seed)
+    t    = np.linspace(0, total_duration, int(total_duration))
+    base = 100 * np.exp(-0.003 * t)
+    noise  = np.random.normal(0, 2, len(t))
+    spikes = np.zeros(len(t))
+    for _ in range(5):
+        spike_t = np.random.randint(0, len(t))
+        spikes[max(0, spike_t-10):spike_t+10] += np.random.uniform(3, 8)
+    df = pd.DataFrame({
+        "second":        t,
+        "retention_pct": np.clip(base + noise + spikes, 0, 100)
+    })
+    # Save for dashboard
+    curve_json = [
+        {"time_seconds": round(row["second"], 2), "retention_percent": round(row["retention_pct"], 2)}
+        for _, row in df.iterrows()
+    ]
+    import json
+    with open("retention_curve.json", "w") as f:
+        json.dump(curve_json, f)
+    return df

youtube_auth.py

@@ -0,0 +1,80 @@
+"""
+youtube_auth.py — Web-based OAuth2 for multi-user Streamlit on Render
+"""
+
+import os
+import json
+import streamlit as st
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import Flow
+from google.auth.transport.requests import Request
+
+SCOPES = [
+    "https://www.googleapis.com/auth/youtube.readonly",
+    "https://www.googleapis.com/auth/yt-analytics.readonly",
+]
+
+def get_client_config():
+    env_secret = os.getenv("GOOGLE_CLIENT_SECRETS")
+    if env_secret:
+        return json.loads(env_secret)
+    if os.path.exists("client_secret.json"):
+        with open("client_secret.json") as f:
+            return json.load(f)
+    raise FileNotFoundError("No Google credentials found. Set GOOGLE_CLIENT_SECRETS env variable.")
+
+def get_redirect_uri():
+    render_url = os.getenv("RENDER_EXTERNAL_URL")
+    if render_url:
+        return f"{render_url}/oauth2callback"
+    return "http://localhost:8501/oauth2callback"
+
+def build_flow():
+    config = get_client_config()
+    flow = Flow.from_client_config(
+        config,
+        scopes=SCOPES,
+        redirect_uri=get_redirect_uri()
+    )
+    return flow
+
+def get_credentials():
+    if "google_creds" in st.session_state:
+        creds = Credentials.from_authorized_user_info(
+            st.session_state["google_creds"], SCOPES
+        )
+        if creds.valid:
+            return creds
+        if creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+            st.session_state["google_creds"] = json.loads(creds.to_json())
+            return creds
+
+    params = st.query_params
+    if "code" in params:
+        try:
+            flow = build_flow()
+            flow.fetch_token(code=params["code"])
+            creds = flow.credentials
+            st.session_state["google_creds"] = json.loads(creds.to_json())
+            st.query_params.clear()
+            return creds
+        except Exception as e:
+            st.error(f"Login failed: {e}")
+            return None
+
+    return None
+
+def show_login_button():
+    flow = build_flow()
+    auth_url, _ = flow.authorization_url(
+        prompt="consent",
+        access_type="offline"
+    )
+    return auth_url
+
+def logout():
+    if "google_creds" in st.session_state:
+        del st.session_state["google_creds"]
+    if "user_info" in st.session_state:
+        del st.session_state["user_info"]