Skip to content

opensite-ai/opensite-skills / book-recorded-sessions

book-recorded-sessions

Verified

Plan, record, and merge recorded sessions into book chapters: solo lessons, interviews with a proxy reader, multi-guest panels, or hybrid lesson-plus-conversation episodes that also serve video and short-form clips. Covers contract-driven run-of-show, contributor releases and employer clearance, per-speaker capture and transcripts, speaker-attributed atoms, merging many sessions into a traceable chapter, and clip hand-off flags. Use when chapters are built from spoken recordings or podcasts. Not for narrating the finished audiobook or editing clips.

FileKindSize
SKILL.mdskill md4.9 KB
assets/segment_types.yamlconfig5.1 KB
references/contributor-release.mdmarkdown2.8 KB
references/merge-rules.mdmarkdown2.4 KB
references/session-formats.mdmarkdown3.8 KB
scripts/chapter_trace.pyexecutablescript8.1 KB
scripts/session_ingest.pyexecutablescript9.4 KB
scripts/session_plan.pyexecutablescript8.1 KB

scripts/session_ingest.py

View on GitHub
#!/usr/bin/env python3
"""Ingest a recorded session's transcripts into one speaker-attributed timeline.

Input: a session folder (default 01-evidence/raw/sessions/<SESSION>) containing either one
transcript per microphone track named <speaker_label>.vtt|.srt (preferred: no diarization
errors) or one diarized file whose cues begin with "<v Label>" or "Label:". Labels map to
contributors through the speaker_labels column of 01-evidence/CONTRIBUTORS.csv.

Writes <folder>/timeline.csv (start, end, label, contributor_id, words, text) and, with
markers.csv (segment_id,start), <folder>/segments.csv: one row per segment with the lead
speaker and two flags for short-form clips: needs_claim_check (numbers, percentages, money)
and needs_clearance (terms from a confidentiality watchlist).

Fails when a label maps to no contributor, a guest has no rights_id (or, with
--require-cleared, no cleared RIGHTS_LEDGER row), the session is not in SESSIONS.csv, or no
transcript is found.

Usage:
  python scripts/session_ingest.py <project_root> --session S01 [--dir PATH]
         [--watchlist confidential_terms.txt] [--require-cleared] [--json report.json]
"""
import argparse
import csv
import json
import pathlib
import re
import sys

TIME = re.compile(r"(?:(\d+):)?(\d{1,2}):(\d{2})[.,](\d{1,3})")
CUE = re.compile(r"^\s*(\S+)\s*-->\s*(\S+)")
VOICE = re.compile(r"^<v(?:\.[^ >]*)?\s+([^>]+)>\s*(.*)$")
PREFIX = re.compile(r"^([A-Z][\w .'-]{0,40}):\s+(.*)$")
NUMBERS = re.compile(r"\d|\bpercent\b|%|\$")


def secs(stamp):
    m = TIME.search(stamp)
    if not m:
        raise ValueError(f"bad timestamp {stamp!r}")
    h, mi, s, ms = m.groups()
    return int(h or 0) * 3600 + int(mi) * 60 + int(s) + int(ms.ljust(3, "0")) / 1000


def hms(t):
    t = int(round(t))
    return f"{t // 3600:02d}:{t % 3600 // 60:02d}:{t % 60:02d}"


def parse(path, default_label=None):
    cues, cur = [], None
    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
        m = CUE.match(line)
        if m:
            cur = {"start": secs(m.group(1)), "end": secs(m.group(2)), "lines": []}
            cues.append(cur)
        elif cur is not None and line.strip() and not line.strip().isdigit():
            cur["lines"].append(line.strip())
        elif not line.strip():
            cur = None
    out = []
    for c in cues:
        text = " ".join(c["lines"])
        label = default_label
        if default_label is None:  # diarized file: the label is in the cue text
            for rx in (VOICE, PREFIX):
                m = rx.match(text)
                if m:
                    label, text = m.group(1).strip(), m.group(2).strip()
                    break
        text = re.sub(r"</?v[^>]*>|<[^>]+>", "", text).strip()
        if text:
            out.append({"start": c["start"], "end": c["end"], "label": label or "UNKNOWN", "text": text,
                        "words": len(re.findall(r"[\w'’-]+", text))})
    return out


def rows(path):
    if not path.exists():
        return []
    with open(path, newline="", encoding="utf-8") as fh:
        return list(csv.DictReader(fh))


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("root")
    ap.add_argument("--session", required=True)
    ap.add_argument("--dir")
    ap.add_argument("--watchlist", help="file of confidential terms (client names, internal codenames), one per line")
    ap.add_argument("--require-cleared", action="store_true", help="guests' RIGHTS_LEDGER rows must be status cleared")
    ap.add_argument("--json")
    args = ap.parse_args()
    root = pathlib.Path(args.root).resolve()
    d = pathlib.Path(args.dir) if args.dir else root / "01-evidence" / "raw" / "sessions" / args.session
    problems, warnings = [], []

    people = [r for r in rows(root / "01-evidence" / "CONTRIBUTORS.csv") if (r.get("contributor_id") or "").strip()]
    label_map = {}
    for r in people:
        for lab in re.split(r"[;,]", r.get("speaker_labels") or ""):
            if lab.strip():
                label_map[lab.strip().lower()] = r
    rights = {r.get("item_id", "").strip(): r for r in rows(root / "04-rights" / "RIGHTS_LEDGER.csv")}
    if not any(r.get("session_id", "").strip() == args.session for r in rows(root / "01-evidence" / "SESSIONS.csv")):
        problems.append(f"{args.session} is not registered in 01-evidence/SESSIONS.csv")

    files = sorted(p for p in d.glob("*") if p.suffix.lower() in (".vtt", ".srt"))
    cues = []
    for f in files:
        per_track = f.stem.lower() in label_map
        cues += parse(f, default_label=f.stem if per_track else None)
    if not cues:
        problems.append(f"no transcript cues found in {d}")

    stats = {}
    for c in cues:
        r = label_map.get(c["label"].lower())
        c["contributor_id"] = r["contributor_id"] if r else ""
        if not r:
            continue
        s = stats.setdefault(r["contributor_id"], {"name": r.get("name", ""), "role": r.get("role", ""), "seconds": 0.0, "words": 0})
        s["seconds"] += c["end"] - c["start"]
        s["words"] += c["words"]
    for lab in sorted({c["label"] for c in cues if not c["contributor_id"]}):
        problems.append(f"speaker label {lab!r} maps to no contributor (add it to speaker_labels in CONTRIBUTORS.csv)")
    for cid, s in stats.items():
        r = next(p for p in people if p["contributor_id"] == cid)
        if s["role"] in ("author", "producer"):
            continue
        rid = (r.get("rights_id") or "").strip()
        if not rid or rid not in rights:
            problems.append(f"{cid}: no RIGHTS_LEDGER row for the contributor release (rights_id {rid or 'empty'})")
        elif rights[rid].get("status", "").strip() != "cleared":
            msg = f"{cid}: contributor release {rid} status is {rights[rid].get('status') or 'empty'}, not cleared"
            (problems if args.require_cleared else warnings).append(msg)
    total_s = sum(s["seconds"] for s in stats.values()) or 1.0
    total_w = sum(s["words"] for s in stats.values()) or 1
    for s in stats.values():
        s["talk_share"] = round(s["seconds"] / total_s, 3)
        s["word_share"] = round(s["words"] / total_w, 3)
        s["seconds"] = round(s["seconds"], 1)

    cues.sort(key=lambda c: c["start"])
    overlap = 0.0
    for i, a in enumerate(cues):
        for b in cues[i + 1:]:
            if b["start"] >= a["end"]:
                break
            if b["contributor_id"] != a["contributor_id"]:
                overlap += min(a["end"], b["end"]) - b["start"]
    if d.exists():
        with open(d / "timeline.csv", "w", newline="", encoding="utf-8") as fh:
            wr = csv.writer(fh, lineterminator="\n")
            wr.writerow(["start", "end", "label", "contributor_id", "words", "text"])
            for c in cues:
                wr.writerow([hms(c["start"]), hms(c["end"]), c["label"], c["contributor_id"], c["words"], c["text"]])

    watch = []
    if args.watchlist:
        watch = [w.strip() for w in pathlib.Path(args.watchlist).read_text(encoding="utf-8").splitlines()
                 if w.strip() and not w.startswith("#")]
    segments = []
    mpath = d / "markers.csv"
    if mpath.exists():
        marks = sorted(((r["segment_id"].strip(), secs(r["start"] + (".000" if "." not in r["start"] else "")))
                        for r in rows(mpath) if r.get("segment_id")), key=lambda x: x[1])
        end_all = max((c["end"] for c in cues), default=0)
        for i, (sid, st) in enumerate(marks):
            en = marks[i + 1][1] if i + 1 < len(marks) else end_all
            inside = [c for c in cues if c["start"] >= st and c["start"] < en]
            talk = {}
            for c in inside:
                talk[c["contributor_id"] or c["label"]] = talk.get(c["contributor_id"] or c["label"], 0) + c["end"] - c["start"]
            text = " ".join(c["text"] for c in inside)
            hits = sorted({w for w in watch if re.search(rf"\b{re.escape(w)}\b", text, re.I)})
            segments.append({"segment_id": sid, "start": hms(st), "end": hms(en), "seconds": round(en - st, 1),
                             "lead": max(talk, key=talk.get) if talk else "", "words": sum(c["words"] for c in inside),
                             "needs_claim_check": bool(NUMBERS.search(text)), "needs_clearance": bool(hits),
                             "watchlist_hits": "; ".join(hits)})
        with open(d / "segments.csv", "w", newline="", encoding="utf-8") as fh:
            wr = csv.DictWriter(fh, fieldnames=list(segments[0].keys()) if segments else ["segment_id"], lineterminator="\n")
            wr.writeheader()
            wr.writerows(segments)
    else:
        warnings.append("no markers.csv; segment map and clip flags not produced")

    report = {"pass": not problems, "session": args.session, "files": [f.name for f in files], "cues": len(cues),
              "contributors": stats, "crosstalk_seconds": round(overlap, 1), "segments": segments,
              "problems": problems, "warnings": warnings}
    print(f"{'PASS' if report['pass'] else 'FAIL'} {args.session}: {len(cues)} cues from {len(files)} file(s)")
    for cid, s in stats.items():
        print(f"  {cid:<14} {s['role']:<13} talk {s['talk_share']:.0%}  words {s['words']}")
    for p in problems:
        print(f"  - {p}")
    for w_ in warnings:
        print(f"  ~ {w_}")
    if args.json:
        pathlib.Path(args.json).write_text(json.dumps(report, indent=2), encoding="utf-8")
    return 0 if report["pass"] else 1


if __name__ == "__main__":
    sys.exit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall