puntorigen/avatar-skills / broll-finder
broll-finder
VerifiedFind real public YouTube footage about a topic or person (e.g. Anthony Bourdain) and turn the relevant moments into clean 9:16, silent B-roll clips for an avatar reel. The found-footage counterpart of broll-generator — instead of synthesizing B-roll with AI, it searches YouTube, fetches timecoded transcripts so the agent can pick the relevant windows WITHOUT downloading whole videos, downloads only those segments, and normalizes them into a broll/-compatible manifest (with source + license metadata) that avatar-reel-composer can drop in via a broll scene. Use when the user wants real/archival B-roll, complementary footage about a subject or person, "find clips of X on YouTube to use in the reel", or footage inserts to lay under an avatar voice-over.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.0 KB |
| examples.md | markdown | 3.3 KB |
| scripts/_common.py | script | 23.6 KB |
| scripts/cut_segment.py | script | 7.8 KB |
| scripts/find_broll.py | script | 10.4 KB |
| scripts/requirements.txt | manifest | 345 B |
| scripts/search.py | script | 3.7 KB |
| scripts/transcripts.py | script | 6.1 KB |
scripts/cut_segment.py
View on GitHub#!/usr/bin/env python3
"""Turn ONE [start,end] window of a real video into a clean B-roll clip.
This is the found-footage workhorse — the counterpart of broll-generator's
generate_broll.py. Given a YouTube URL (downloads ONLY that window) or a local
file (cuts it directly), it produces a 9:16, audio-stripped clip normalized to
the reel format, and appends a provenance + license entry to a broll-compatible
manifest.json.
Output: <out-dir>/<NNN>_<slug>.mp4 + a manifest.json entry. A JSON summary is
printed to stdout for an orchestrating skill.
Examples:
# From YouTube (downloads only 02:12-02:18), saved into an avatar's broll/found/:
python3 cut_segment.py --url "https://youtu.be/VIDEOID" --start 132 --end 138 \
--description "Bourdain comiendo pho en un puesto callejero de Hanoi" \
--avatar-dir /path/to/lolo
# From an already-downloaded local file:
python3 cut_segment.py --input clip.mp4 --start 5 --end 11 \
--description "olas rompiendo al atardecer" --fit blur --out-dir ./broll
"""
from __future__ import annotations
import argparse
import datetime as _dt
import json
import sys
import tempfile
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
import _common as C # noqa: E402
# Reel format defaults (match avatar-reel-composer's reel preset).
DEFAULT_W, DEFAULT_H, DEFAULT_FPS = 1080, 1920, 30
def resolve_out_dir(args) -> tuple[Path, Path]:
"""Found clips live under <avatar>/broll/found/ with their own manifest,
kept separate from generated broll so indices never collide."""
if args.avatar_dir:
avatar_dir = Path(args.avatar_dir).expanduser().resolve()
if avatar_dir.is_dir():
out_dir = avatar_dir / "broll" / "found"
out_dir.mkdir(parents=True, exist_ok=True)
return out_dir, out_dir / "manifest.json"
out_dir = Path(args.out_dir or (Path.cwd() / "broll-found")).expanduser().resolve()
out_dir.mkdir(parents=True, exist_ok=True)
return out_dir, out_dir / "manifest.json"
def main() -> int:
ap = argparse.ArgumentParser(
description="Cut one [start,end] window of a real video into a clean 9:16 B-roll clip.",
formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__)
src = ap.add_mutually_exclusive_group(required=True)
src.add_argument("--url", help="YouTube URL/ID — only the window is downloaded.")
src.add_argument("--input", help="Local video file to cut.")
ap.add_argument("--start", type=float, required=True, help="Window start (seconds).")
ap.add_argument("--end", type=float, required=True, help="Window end (seconds).")
ap.add_argument("--description", required=True, help="What the clip shows (for the manifest/storyboard).")
ap.add_argument("--fit", default="crop", choices=["crop", "pad", "blur"],
help="16:9->9:16 strategy. DEFAULT 'crop' = center crop-to-fill that covers the "
"WHOLE 9:16 frame (never letterbox/pad a downscaled copy). 'pad' (black bars) "
"and 'blur' (blurred backfill) are opt-in only when cropping would cut out "
"essential content.")
ap.add_argument("--width", type=int, default=DEFAULT_W)
ap.add_argument("--height", type=int, default=DEFAULT_H)
ap.add_argument("--fps", type=int, default=DEFAULT_FPS)
ap.add_argument("--max-height", type=int, default=720, help="Max source height to download (default 720).")
ap.add_argument("--keep-audio", action="store_true", help="Keep audio (off by default for clean B-roll).")
ap.add_argument("--cookies-from-browser", help="Browser for cookies on bot-gated videos.")
ap.add_argument("--frame", action="store_true", help="Also save a midpoint frame jpg for visual review.")
ap.add_argument("--avatar-dir", help="Avatar folder; saves to <avatar>/broll/found/.")
ap.add_argument("--out-dir", help="Explicit output folder (default ./broll-found).")
ap.add_argument("--out-name", help="Override the output filename stem (without extension).")
args = ap.parse_args()
if args.end <= args.start:
print("Error: --end must be greater than --start.", file=sys.stderr)
return 1
seg_dur = round(args.end - args.start, 3)
out_dir, manifest_path = resolve_out_dir(args)
manifest = C.load_manifest(manifest_path)
idx = C.next_index(manifest["items"], out_dir)
stem = args.out_name or f"{idx:03d}_{C.slugify(args.description)}"
final_path = out_dir / f"{stem}.mp4"
# 1) get a local source covering the window
info: dict = {}
cleanup_tmp: Path | None = None
if args.url:
info = C.ytdlp_info(args.url, args.cookies_from_browser)
tmpdir = Path(tempfile.mkdtemp(prefix="bf_dl_"))
cleanup_tmp = tmpdir
section = C.download_section(
args.url, args.start, args.end, tmpdir / "section",
max_height=args.max_height, cookies_browser=args.cookies_from_browser)
if not section or not section.exists():
print("Error: section download failed.", file=sys.stderr)
return 2
# The downloaded file IS the window, so cut from 0.
local_src, lstart, lend = section, 0.0, seg_dur
else:
local_src = Path(args.input).expanduser().resolve()
if not local_src.exists():
print(f"Error: input not found: {local_src}", file=sys.stderr)
return 2
lstart, lend = args.start, args.end
# 2) cut + normalize to 9:16
ok = C.cut_and_normalize(
local_src, final_path, start=lstart, end=lend,
W=args.width, H=args.height, fps=args.fps, fit=args.fit,
strip_audio=not args.keep_audio)
if not ok or not final_path.exists():
print("Error: ffmpeg normalization failed.", file=sys.stderr)
return 3
frame_path = None
if args.frame:
frame_path = C.extract_frame(final_path, seg_dur / 2.0,
out_dir / f"{stem}.jpg")
if cleanup_tmp:
import shutil
shutil.rmtree(cleanup_tmp, ignore_errors=True)
probe = C.probe_video(final_path)
lic = C.license_summary(info.get("license"))
vid = info.get("video_id") or (C.extract_video_id(args.url) if args.url else None)
entry = {
"index": idx,
"file": final_path.name,
"path": str(final_path),
"description": args.description,
"source": "youtube" if args.url else "local",
"source_url": (args.url if args.url and args.url.startswith("http")
else (f"https://www.youtube.com/watch?v={vid}" if vid else None)),
"source_video_id": vid,
"source_title": info.get("title"),
"channel": info.get("channel"),
"channel_url": info.get("channel_url"),
"license": lic["license"],
"reusable": lic["reusable"],
"rights_note": lic["note"],
"segment": {"start": args.start, "end": args.end},
"fit": args.fit,
"aspect_ratio": "9:16",
"audio": bool(args.keep_audio),
"duration_sec": probe.get("duration", seg_dur),
"width": probe.get("width"),
"height": probe.get("height"),
"fps_actual": probe.get("fps"),
"frame": str(frame_path) if frame_path else None,
"created": _dt.datetime.now(_dt.timezone.utc).isoformat(),
}
manifest["items"].append(entry)
C.write_manifest(manifest_path, manifest)
print(f"Done: {final_path}", file=sys.stderr)
if not lic["reusable"]:
print(f" RIGHTS: {lic['note']}", file=sys.stderr)
print(json.dumps({
"video": str(final_path), "manifest": str(manifest_path),
**{k: entry[k] for k in ("description", "duration_sec", "width", "height",
"license", "reusable", "source_url", "segment")},
}, ensure_ascii=False))
return 0
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |