opensite-ai/opensite-skills / book-recorded-sessions
book-recorded-sessions
VerifiedPlan, 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
| assets/segment_types.yaml | config | 5.1 KB |
| references/contributor-release.md | markdown | 2.8 KB |
| references/merge-rules.md | markdown | 2.4 KB |
| references/session-formats.md | markdown | 3.8 KB |
| scripts/chapter_trace.pyexecutable | script | 8.1 KB |
| scripts/session_ingest.pyexecutable | script | 9.4 KB |
| scripts/session_plan.pyexecutable | script | 8.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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |