CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

jbaruch/speaker-toolkit

Twelve skills for conference speakers covering rhetoric analysis, talk authoring, deck building and export, CFP submissions, publishing, illustrations, shownotes, screencast production, and vertical shorts, informed by a 113-entry Presentation Patterns taxonomy (83 observable: 64 patterns + 19 antipatterns; 30 unobservable: 21 patterns + 9 antipatterns).

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Medium

Suggest reviewing before use

Overview
Quality
Evals
Security
Files

shorts_plan.pyskills/shorts-producer/scripts/

"""The shorts plan: one talk's clips, written by the agent, read by the scripts.

``plan.json`` lives in the talk's shorts output folder. Relative paths in it
resolve against the plan's own directory. Schema version 1:

    {
      "schema_version": 1,
      "talk": "<tracking-database filename>",
      "source": "<local recording, video+audio>",
      "deck_pdf": "<the deck as PDF>",
      "work_dir": "<local scratch folder for intermediates>",
      "out_dir": "<folder for the finished shorts>",
      "handle": "@speaker", "event": "EVENT NAME", "website": "example.com",
      "qr_url": "<shownotes link>" | null,
      "clips": [{
        "id": "01-slug", "title": "...", "hook": ["LINE ONE", "LINE TWO"],
        "start": 1038.94, "end": 1069.45, "rationale": "...",
        "speaker_region": [x, y, w, h],
        "slides": [[0, 14], [4.9, 15]],
        "captions": "the corrected caption text"
      }]
    }

``start``/``end`` are seconds in the source. ``speaker_region`` is the
normalized box the speaker stays inside, ``slides`` pairs a clip offset in
seconds with a deck page number, and ``captions`` is the corrected text. Those
three are needed to render, not to prepare.
"""

from __future__ import annotations

import json
from pathlib import Path
import re
from typing import Any

SCHEMA_VERSION = 1
CLIP_ID = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
PLAN_FIELDS = (
    "talk",
    "source",
    "deck_pdf",
    "work_dir",
    "out_dir",
    "handle",
    "event",
    "website",
)
RENDER_FIELDS = ("speaker_region", "slides", "captions", "title", "hook")
# Seconds of recording prepared on each side of a clip, so the agent can move a
# boundary to a sentence edge without preparing again.
CONTEXT_SECONDS = 8.0


class PlanError(ValueError):
    """The plan cannot drive this step; the message says what to fix."""


def _path(plan_dir: Path, value: object, field: str) -> Path:
    if not isinstance(value, str) or not value:
        raise PlanError(f"plan field {field!r} must be a path string")
    path = Path(value).expanduser()
    return path if path.is_absolute() else (plan_dir / path).resolve()


def load(plan_path: Path) -> dict[str, Any]:
    """Read and check the plan's top level; paths come back absolute."""
    try:
        plan = json.loads(plan_path.read_text(encoding="utf-8"))
    except OSError as exc:
        raise PlanError(f"cannot read the plan {plan_path}: {exc}") from exc
    except json.JSONDecodeError as exc:
        raise PlanError(f"the plan {plan_path} is not JSON: {exc}") from exc
    if not isinstance(plan, dict) or plan.get("schema_version") != SCHEMA_VERSION:
        raise PlanError(
            f"the plan must be an object with schema_version {SCHEMA_VERSION}"
        )
    missing = [field for field in PLAN_FIELDS if field not in plan]
    if missing:
        raise PlanError(f"the plan is missing {missing}")
    for field in ("source", "deck_pdf", "work_dir", "out_dir"):
        plan[field] = _path(plan_path.parent, plan[field], field)
    qr_url = plan.get("qr_url")
    if qr_url is not None and not (
        isinstance(qr_url, str) and qr_url.startswith("https://")
    ):
        raise PlanError("qr_url must be an https:// link or null")
    clips = plan.get("clips")
    if not isinstance(clips, list) or not clips:
        raise PlanError("the plan needs a non-empty clips list")
    seen: set[str] = set()
    for clip in clips:
        _check_clip(clip, seen)
    return plan


def _check_clip(clip: object, seen: set[str]) -> None:
    if not isinstance(clip, dict):
        raise PlanError("every clip must be an object")
    clip_id = clip.get("id")
    if not isinstance(clip_id, str) or not CLIP_ID.match(clip_id):
        raise PlanError(
            f"clip id {clip_id!r} must be lowercase letters, digits and dashes"
        )
    if clip_id in seen:
        raise PlanError(f"clip id {clip_id!r} appears twice")
    seen.add(clip_id)
    start, end = clip.get("start"), clip.get("end")
    if not (
        isinstance(start, (int, float))
        and isinstance(end, (int, float))
        and 0 <= start < end
    ):
        raise PlanError(
            f"clip {clip_id}: start and end must be seconds with start < end"
        )


def clip(plan: dict[str, Any], clip_id: str) -> dict[str, Any]:
    for candidate in plan["clips"]:
        if candidate["id"] == clip_id:
            return candidate
    raise PlanError(
        f"no clip {clip_id!r} in the plan; ids: {[c['id'] for c in plan['clips']]}"
    )


def require_render_fields(selected: dict[str, Any]) -> None:
    """A clip is renderable once the agent filled in what preparation showed."""
    clip_id = selected["id"]
    missing = [field for field in RENDER_FIELDS if field not in selected]
    if missing:
        raise PlanError(
            f"clip {clip_id} is missing {missing} — prepare it and fill them in"
        )
    region = selected["speaker_region"]
    if not (
        isinstance(region, list)
        and len(region) == 4
        and all(isinstance(v, (int, float)) for v in region)
        and 0 <= region[0] < 1
        and 0 <= region[1] < 1
        and 0 < region[2] <= 1 - region[0] + 1e-9
        and 0 < region[3] <= 1 - region[1] + 1e-9
    ):
        raise PlanError(
            f"clip {clip_id}: speaker_region must be [x, y, w, h] inside 0..1"
        )
    slides = selected["slides"]
    duration = selected["end"] - selected["start"]
    if not isinstance(slides, list) or not slides:
        raise PlanError(
            f"clip {clip_id}: slides needs at least one [offset, page] pair"
        )
    offsets = []
    for pair in slides:
        if not (
            isinstance(pair, list)
            and len(pair) == 2
            and isinstance(pair[0], (int, float))
            and isinstance(pair[1], int)
            and pair[1] >= 1
        ):
            raise PlanError(
                f"clip {clip_id}: slide entry {pair!r} must be [offset, page]"
            )
        offsets.append(pair[0])
    if offsets[0] != 0 or offsets != sorted(offsets) or offsets[-1] >= duration:
        raise PlanError(
            f"clip {clip_id}: slide offsets must start at 0, rise, and stay inside the clip"
        )
    hook = selected["hook"]
    if not (
        isinstance(hook, list)
        and 1 <= len(hook) <= 2
        and all(isinstance(h, str) and h for h in hook)
    ):
        raise PlanError(f"clip {clip_id}: hook must be one or two lines of text")
    if not isinstance(selected["captions"], str) or not selected["captions"].split():
        raise PlanError(f"clip {clip_id}: captions must be the corrected text")


def clip_dir(plan: dict[str, Any], clip_id: str) -> Path:
    return plan["work_dir"] / clip_id


def deck_dir(plan: dict[str, Any]) -> Path:
    return plan["work_dir"] / "deck"


def vision_script(plan: dict[str, Any]) -> Path:
    """The Apple Vision helper, copied to a runnable name in the work folder.

    An installed plugin has only the ``vision.swift.txt`` mirror, because
    ``tessl install`` drops ``.swift`` files, and ``swift`` runs only a
    ``.swift`` path. A clone has both; the real file wins.
    """
    target = plan["work_dir"] / "vision.swift"
    here = Path(__file__).resolve().parent
    source = here / "vision.swift"
    if not source.exists():
        source = here / "vision.swift.txt"
    text = source.read_text(encoding="utf-8")
    if not target.exists() or target.read_text(encoding="utf-8") != text:
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(text, encoding="utf-8")
    return target


def deck_page(plan: dict[str, Any], page: int) -> Path:
    """The rendered page, as ``prepare-clip.py`` names it."""
    return deck_dir(plan) / f"page-{page:03d}.png"

skills

README.md

tile.json