presenter-json 0.1.0__py3-none-any.whl

presenter_json/__init__.py

@@ -0,0 +1,111 @@
+"""presenter-json — Pydantic models and JSON helpers for the ProPresenter
+gold-copy presentation timing format.
+
+Typical use::
+
+    from presenter_json import load_presentation, cues, slide_texts
+
+    pres = load_presentation("sermon.json")
+    for cue in cues(pres):
+        print(cue.time, cue.text)
+"""
+
+from __future__ import annotations
+
+from .helpers import (
+    Cue,
+    add_group,
+    add_slide,
+    clear_timing,
+    cues,
+    detect_timing_key,
+    from_api_response,
+    get_start_times,
+    get_stop_times,
+    get_timing,
+    get_trigger_times,
+    group_name,
+    iter_groups,
+    iter_slides,
+    new_presentation,
+    set_metadata,
+    set_start_times,
+    set_stop_times,
+    set_timing,
+    set_trigger_times,
+    slide_field,
+    slide_text,
+    slide_texts,
+)
+from .io import (
+    dumps_presentation,
+    load_presentation,
+    load_raw,
+    loads_presentation,
+    save_presentation,
+)
+from .models import (
+    METHOD_CAPTIONS,
+    METHOD_MANUAL,
+    METHOD_MODEL,
+    METHODS,
+    START_TIME_KEY,
+    STOP_TIME_KEY,
+    TIMING_KEYS,
+    TRIGGER_TIME_KEY,
+    Group,
+    Presentation,
+    PresentationFile,
+    PresentationId,
+    Slide,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # models
+    "PresentationFile",
+    "Presentation",
+    "PresentationId",
+    "Group",
+    "Slide",
+    "METHOD_MANUAL",
+    "METHOD_CAPTIONS",
+    "METHOD_MODEL",
+    "METHODS",
+    "TRIGGER_TIME_KEY",
+    "START_TIME_KEY",
+    "STOP_TIME_KEY",
+    "TIMING_KEYS",
+    # io
+    "load_presentation",
+    "loads_presentation",
+    "save_presentation",
+    "dumps_presentation",
+    "load_raw",
+    # helpers
+    "Cue",
+    "iter_groups",
+    "iter_slides",
+    "group_name",
+    "slide_field",
+    "slide_text",
+    "slide_texts",
+    "get_timing",
+    "get_trigger_times",
+    "get_start_times",
+    "get_stop_times",
+    "detect_timing_key",
+    "cues",
+    "new_presentation",
+    "add_group",
+    "add_slide",
+    "set_timing",
+    "set_trigger_times",
+    "set_start_times",
+    "set_stop_times",
+    "clear_timing",
+    "set_metadata",
+    "from_api_response",
+]

presenter_json/helpers.py

@@ -0,0 +1,257 @@
+"""JSON-centric helpers for reading and generating presenter JSON.
+
+Two groups of functions:
+
+* **Reading** — flatten a :class:`PresentationFile` into groups, slides, slide
+  text, timing lists, and sorted playback cues.
+* **Generating / mutating** — build a presentation from scratch, add groups and
+  slides, stamp metadata, and set or clear a slide's timing lists.
+
+Slide content (text, enabled, notes, …) and timing keys all live in a slide's
+``model_extra`` because :class:`~presenter_json.models.Slide` declares no fields.
+These helpers hide that detail behind named accessors.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Iterator, NamedTuple
+
+from .models import (
+    START_TIME_KEY,
+    STOP_TIME_KEY,
+    TIMING_KEYS,
+    TRIGGER_TIME_KEY,
+    Group,
+    Presentation,
+    PresentationFile,
+    PresentationId,
+    Slide,
+)
+
+__all__ = [
+    "Cue",
+    "iter_groups",
+    "iter_slides",
+    "group_name",
+    "slide_field",
+    "slide_text",
+    "slide_texts",
+    "get_timing",
+    "get_trigger_times",
+    "get_start_times",
+    "get_stop_times",
+    "detect_timing_key",
+    "cues",
+    "new_presentation",
+    "add_group",
+    "add_slide",
+    "set_timing",
+    "set_trigger_times",
+    "set_start_times",
+    "set_stop_times",
+    "clear_timing",
+    "set_metadata",
+    "from_api_response",
+]
+
+
+class Cue(NamedTuple):
+    """A single playback cue: fire ``slide`` at ``time`` seconds."""
+
+    time: float
+    slide_index: int          # 0-based index into the flattened slide list
+    group_index: int          # 0-based index of the containing group
+    group_name: str
+    text: str
+    slide: Slide
+
+
+# --------------------------------------------------------------------------- #
+# Reading
+# --------------------------------------------------------------------------- #
+
+def _extras(model: Any) -> dict[str, Any]:
+    """Return a model's mutable extras dict, tolerating ``None``."""
+    extra = getattr(model, "model_extra", None)
+    return extra if extra is not None else {}
+
+
+def iter_groups(model: PresentationFile) -> Iterator[Group]:
+    """Yield every :class:`Group` in the presentation, in order."""
+    yield from model.presentation.groups
+
+
+def iter_slides(model: PresentationFile) -> Iterator[Slide]:
+    """Yield every :class:`Slide`, flattened across all groups, in order."""
+    for group in model.presentation.groups:
+        yield from group.slides
+
+
+def group_name(group: Group) -> str:
+    """Return a group's ``name`` (empty string if unset)."""
+    return _extras(group).get("name", "") or ""
+
+
+def slide_field(slide: Slide, key: str, default: Any = None) -> Any:
+    """Return an arbitrary field from a slide's extras."""
+    return _extras(slide).get(key, default)
+
+
+def slide_text(slide: Slide) -> str:
+    """Return a slide's ``text`` (empty string if unset)."""
+    return _extras(slide).get("text", "") or ""
+
+
+def slide_texts(model: PresentationFile) -> list[str]:
+    """Return the ``text`` of every slide, flattened across groups."""
+    return [slide_text(s) for s in iter_slides(model)]
+
+
+def get_timing(slide: Slide, key: str) -> list[float]:
+    """Return the timing list stored under ``key`` (empty list if absent)."""
+    values = _extras(slide).get(key)
+    if not isinstance(values, list):
+        return []
+    return [float(t) for t in values if isinstance(t, (int, float))]
+
+
+def get_trigger_times(slide: Slide) -> list[float]:
+    return get_timing(slide, TRIGGER_TIME_KEY)
+
+
+def get_start_times(slide: Slide) -> list[float]:
+    return get_timing(slide, START_TIME_KEY)
+
+
+def get_stop_times(slide: Slide) -> list[float]:
+    return get_timing(slide, STOP_TIME_KEY)
+
+
+def detect_timing_key(model: PresentationFile) -> str | None:
+    """Return the timing key in use across the presentation, or ``None``.
+
+    Prefers ``trigger time``; falls back to ``start time`` then ``stop time``.
+    A key is "in use" if any slide carries a non-empty list for it.
+    """
+    slides = list(iter_slides(model))
+    for key in TIMING_KEYS:
+        if any(get_timing(s, key) for s in slides):
+            return key
+    return None
+
+
+def cues(model: PresentationFile, *, timing_key: str | None = None) -> list[Cue]:
+    """Return every timing cue, sorted by time.
+
+    ``timing_key`` defaults to :func:`detect_timing_key`. Returns an empty list
+    if the presentation carries no timing data.
+    """
+    if timing_key is None:
+        timing_key = detect_timing_key(model)
+    if timing_key is None:
+        return []
+
+    result: list[Cue] = []
+    slide_index = 0
+    for group_index, group in enumerate(iter_groups(model)):
+        gname = group_name(group)
+        for slide in group.slides:
+            for t in get_timing(slide, timing_key):
+                result.append(
+                    Cue(
+                        time=t,
+                        slide_index=slide_index,
+                        group_index=group_index,
+                        group_name=gname,
+                        text=slide_text(slide),
+                        slide=slide,
+                    )
+                )
+            slide_index += 1
+
+    result.sort(key=lambda c: c.time)
+    return result
+
+
+# --------------------------------------------------------------------------- #
+# Generating / mutating
+# --------------------------------------------------------------------------- #
+
+def new_presentation(
+    *,
+    name: str | None = None,
+    uuid: str | None = None,
+    index: int | None = None,
+    **id_fields: Any,
+) -> PresentationFile:
+    """Build an empty :class:`PresentationFile` with metadata on ``presentation.id``.
+
+    Extra keyword arguments (e.g. ``audio_path``, ``method``) are set on the
+    :class:`PresentationId`.
+    """
+    pid = PresentationId(name=name, uuid=uuid, index=index, **id_fields)
+    return PresentationFile(presentation=Presentation(id=pid))
+
+
+def add_group(model: PresentationFile, name: str = "", **fields: Any) -> Group:
+    """Append a new :class:`Group` to the presentation and return it."""
+    group = Group(**({"name": name, **fields} if name or fields else {}))
+    model.presentation.groups.append(group)
+    return group
+
+
+def add_slide(group: Group, text: str = "", **fields: Any) -> Slide:
+    """Append a new :class:`Slide` to ``group`` and return it.
+
+    ``text`` and any extra keyword fields are stored on the slide.
+    """
+    data: dict[str, Any] = {}
+    if text:
+        data["text"] = text
+    data.update(fields)
+    slide = Slide(**data)
+    group.slides.append(slide)
+    return slide
+
+
+def set_timing(slide: Slide, key: str, times: Iterable[float]) -> None:
+    """Set the timing list under ``key`` on ``slide``."""
+    setattr(slide, key, [float(t) for t in times])
+
+
+def set_trigger_times(slide: Slide, times: Iterable[float]) -> None:
+    set_timing(slide, TRIGGER_TIME_KEY, times)
+
+
+def set_start_times(slide: Slide, times: Iterable[float]) -> None:
+    set_timing(slide, START_TIME_KEY, times)
+
+
+def set_stop_times(slide: Slide, times: Iterable[float]) -> None:
+    set_timing(slide, STOP_TIME_KEY, times)
+
+
+def clear_timing(slide: Slide, keys: Iterable[str] = TIMING_KEYS) -> None:
+    """Remove timing keys from a slide so they are omitted from output."""
+    extra = _extras(slide)
+    for key in keys:
+        extra.pop(key, None)
+
+
+def set_metadata(model: PresentationFile, **fields: Any) -> PresentationId:
+    """Set fields on ``presentation.id`` (e.g. ``audio_path``, ``method``, ``version``)."""
+    pid = model.presentation.id
+    for key, value in fields.items():
+        setattr(pid, key, value)
+    return pid
+
+
+def from_api_response(data: dict) -> PresentationFile:
+    """Wrap a raw ProPresenter ``/v1/presentation/{uuid}`` payload.
+
+    Accepts either the full ``{"presentation": {...}}`` envelope or a bare
+    ``presentation`` object and returns a validated :class:`PresentationFile`.
+    """
+    if "presentation" in data:
+        return PresentationFile.model_validate(data)
+    return PresentationFile.model_validate({"presentation": data})

presenter_json/io.py

@@ -0,0 +1,63 @@
+"""Read and write presenter JSON files.
+
+These are thin, JSON-centric wrappers around the pydantic models in
+:mod:`presenter_json.models`. They accept ``str`` or :class:`os.PathLike`
+paths and always round-trip through :class:`~presenter_json.models.PresentationFile`
+so extra/pass-through fields are preserved.
+"""
+
+from __future__ import annotations
+
+import json
+from os import PathLike
+from pathlib import Path
+
+from .models import PresentationFile
+
+__all__ = [
+    "load_presentation",
+    "loads_presentation",
+    "save_presentation",
+    "dumps_presentation",
+    "load_raw",
+]
+
+StrPath = str | PathLike[str]
+
+
+def load_presentation(path: StrPath) -> PresentationFile:
+    """Load and validate a presenter JSON file into a :class:`PresentationFile`."""
+    text = Path(path).read_text(encoding="utf-8")
+    return loads_presentation(text)
+
+
+def loads_presentation(text: str) -> PresentationFile:
+    """Validate a JSON string into a :class:`PresentationFile`."""
+    return PresentationFile.model_validate_json(text)
+
+
+def dumps_presentation(model: PresentationFile, *, indent: int | None = 2) -> str:
+    """Serialize a :class:`PresentationFile` to a JSON string."""
+    return model.model_dump_json(indent=indent)
+
+
+def save_presentation(
+    model: PresentationFile, path: StrPath, *, indent: int | None = 2
+) -> Path:
+    """Write ``model`` to ``path`` as JSON and return the resolved path.
+
+    Parent directories are created if they do not exist.
+    """
+    out = Path(path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(dumps_presentation(model, indent=indent), encoding="utf-8")
+    return out
+
+
+def load_raw(path: StrPath) -> dict:
+    """Load a presenter JSON file as a plain ``dict`` without validation.
+
+    Useful when you need the untouched ProPresenter payload (e.g. to inspect
+    fields that are not modelled) rather than a :class:`PresentationFile`.
+    """
+    return json.loads(Path(path).read_text(encoding="utf-8"))

presenter_json/models.py

@@ -0,0 +1,87 @@
+"""
+Pydantic models for the ProPresenter gold-copy presentation JSON format.
+
+The top-level shape mirrors the ``/v1/presentation/{uuid}`` ProPresenter API
+response, with extra keys added to ``presentation.id`` describing the audio, the
+timing method, and file versioning.
+
+All ProPresenter API fields not explicitly modelled here pass through via
+``extra="allow"`` so the JSON faithfully reflects the original API response.
+Timing fields (trigger time, start time, stop time) are stored as extras on
+:class:`Slide` so they are omitted entirely from slides that were never
+triggered.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+METHOD_MANUAL = "manual"
+METHOD_CAPTIONS = "captions"
+METHOD_MODEL = "model"
+
+#: Valid values for :attr:`PresentationId.method`.
+METHODS = (METHOD_MANUAL, METHOD_CAPTIONS, METHOD_MODEL)
+
+#: Timing keys stored as extras on a :class:`Slide`. Each maps to a list of
+#: floats (seconds). ``trigger time`` is the primary cue list.
+TRIGGER_TIME_KEY = "trigger time"
+START_TIME_KEY = "start time"
+STOP_TIME_KEY = "stop time"
+TIMING_KEYS = (TRIGGER_TIME_KEY, START_TIME_KEY, STOP_TIME_KEY)
+
+
+class PresentationId(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    uuid: str | None = None
+    name: str | None = None
+    index: int | None = None
+
+    # Audio the timing is against.
+    audio_path: str = ""          # local path to the audio file
+    audio_description: str = ""   # freeform: where the audio came from
+    audio_url: str = ""           # optional: internet source URL for the audio
+
+    # How the trigger times were produced.
+    method: str = METHOD_MANUAL           # manual | captions | model
+    method_description: str = ""          # freeform: model name / "forced alignment" / ...
+    method_url: str = ""                  # URL of the software implementing the method
+    method_version: str = ""              # version of that software
+
+    # Versioning of THIS json file itself — bumped on micro edits (e.g. a human
+    # nudging one trigger time), independent of the generating software.
+    version: str = ""
+    comment: str = ""             # optional freeform note about a change/edit
+
+
+class Slide(BaseModel):
+    """A single ProPresenter slide.
+
+    All fields (enabled, notes, text, label, …) pass through as extras. Timing
+    keys are written directly into ``model_extra`` so they appear in the output
+    only for slides that were actually triggered.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+
+class Group(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    slides: list[Slide] = Field(default_factory=list)
+
+
+class Presentation(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    id: PresentationId = Field(default_factory=PresentationId)
+    groups: list[Group] = Field(default_factory=list)
+
+
+class PresentationFile(BaseModel):
+    """Root model — the object serialized to and from a ``*.json`` file."""
+
+    model_config = ConfigDict(extra="allow")
+
+    presentation: Presentation

presenter_json-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: presenter-json
+Version: 0.1.0
+Summary: Pydantic models and JSON helpers for presentation timing format, shared across projects
+License: MIT
+Keywords: propresenter,presentation,json,pydantic,timing
+Author: scaperoth
+Author-email: scaperoth@berkeley.edu
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Dist: pydantic (>=2.0,<3.0)
+Project-URL: Homepage, https://github.com/scaperothian/presenter-json
+Project-URL: Issues, https://github.com/scaperothian/presenter-json/issues
+Project-URL: Repository, https://github.com/scaperothian/presenter-json
+Description-Content-Type: text/markdown
+
+# presenter-json
+
+Pydantic models and JSON helpers for  **presentation
+timing format** — a shared library for the various projects that read and
+generate these JSON files (training data, playback, benchmarking, …).
+
+The JSON shape resembles the ProPresenter `/v1/presentation/{uuid}` API response,
+with extra metadata on `presentation.id` (audio source, timing method, file
+version) and per-slide timing lists (`trigger time`, `start time`, `stop time`).
+Any ProPresenter field not explicitly modelled passes through untouched.
+
+## Install
+
+```bash
+pip install presenter-json
+```
+
+Or with Poetry, as a path/develop dependency from a sibling project:
+
+```toml
+[tool.poetry.dependencies]
+presenter-json = { path = "../presenter-json", develop = true }
+```
+
+## Reading a file
+
+```python
+from presenter_json import load_presentation, cues, slide_texts
+
+pres = load_presentation("sermon.json")
+
+print(pres.presentation.id.name)
+print(slide_texts(pres))            # text of every slide, flattened
+
+for cue in cues(pres):              # sorted playback cues
+    print(f"{cue.time:7.3f}  [{cue.group_name}]  {cue.text}")
+```
+
+## Generating a file
+
+```python
+from presenter_json import (
+    new_presentation, add_group, add_slide,
+    set_trigger_times, set_metadata, save_presentation,
+)
+
+pres = new_presentation(name="My Song", audio_path="audio/my-song.wav")
+set_metadata(pres, method="model", method_description="forced alignment", version="1.0")
+
+verse = add_group(pres, "Verse 1")
+s1 = add_slide(verse, "First line of the verse")
+set_trigger_times(s1, [0.0])
+add_slide(verse, "Second line")          # untriggered — no timing written
+
+save_presentation(pres, "my-song.json")
+```
+
+## API overview
+
+**IO** (`presenter_json.io`)
+- `load_presentation(path)` / `loads_presentation(text)` → `PresentationFile`
+- `save_presentation(model, path)` / `dumps_presentation(model)`
+- `load_raw(path)` → unvalidated `dict`
+
+**Reading** (`presenter_json.helpers`)
+- `iter_groups`, `iter_slides`, `group_name`, `slide_text`, `slide_texts`, `slide_field`
+- `get_trigger_times` / `get_start_times` / `get_stop_times` / `get_timing`
+- `detect_timing_key`, `cues` (sorted `Cue` list)
+
+**Generating / mutating**
+- `new_presentation`, `add_group`, `add_slide`
+- `set_trigger_times` / `set_start_times` / `set_stop_times` / `set_timing`, `clear_timing`
+- `set_metadata`, `from_api_response`
+
+**Models** (`presenter_json.models`)
+- `PresentationFile`, `Presentation`, `PresentationId`, `Group`, `Slide`
+- Constants: `METHOD_MANUAL`, `METHOD_CAPTIONS`, `METHOD_MODEL`, `TRIGGER_TIME_KEY`, …
+
+## Development
+
+```bash
+poetry install
+poetry run pytest
+```
+
+Tests run in GitHub Actions across Python 3.11–3.13 (`.github/workflows/ci.yml`).
+Tagging a release (`vX.Y.Z`) publishes to PyPI via Trusted Publishing
+(`.github/workflows/publish.yml`).
+
+All changes go through a branch off `main` and land via pull request.
+

presenter_json-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+presenter_json/__init__.py,sha256=bmZRzZP3gsrtr1cZdZLdxc3E77Iq_9_f0rPBNKuXgG4,2093
+presenter_json/helpers.py,sha256=k1ibpJstkq0D2b6IbqRClwsQjP0nMV5ORm9dorNXHR8,8007
+presenter_json/io.py,sha256=7qFISEpJNJ5UYNCMvtuMUdI0l3Fh6EtSAAlnIm84D3I,1969
+presenter_json/models.py,sha256=t3Khw1kI6IaPLwwpuZ8E5_fIigROjeCiuuxG2Nr3t2Y,3039
+presenter_json/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+presenter_json-0.1.0.dist-info/METADATA,sha256=6F6vhgF6xOPZ-dBxKovjzz-8btdHE5M06k8_QQZMObs,3946
+presenter_json-0.1.0.dist-info/WHEEL,sha256=EGEvSphFYqXKs23-kQBeyNoJP1nrT8ZJKQoi5p5DYL8,88
+presenter_json-0.1.0.dist-info/RECORD,,

presenter_json-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.0
+Root-Is-Purelib: true
+Tag: py3-none-any