From 57f0660d67a796ab5348a4794191c074815f7c53 Mon Sep 17 00:00:00 2001 From: bc1cindy Date: Sat, 14 Nov 2026 21:42:28 -0300 Subject: [PATCH 1/3] Extract each chapter's readable text Narration reads a chapter's text aloud. Extract it without frontmatter, code, diagrams, tables, markup or math, one heading, list item or paragraph per line, and name its audio by the hash of the text, so audio rendered from other text never stands in for it. --- contrib/test_tts.py | 68 +++++++++++++++++++++++++++++ contrib/tts.py | 102 ++++++++++++++++++++++++++++++++++++++++++++ cspell/tooling.txt | 1 + 3 files changed, 171 insertions(+) create mode 100644 contrib/test_tts.py create mode 100644 contrib/tts.py diff --git a/contrib/test_tts.py b/contrib/test_tts.py new file mode 100644 index 0000000..a1e7cbd --- /dev/null +++ b/contrib/test_tts.py @@ -0,0 +1,68 @@ +import tts + + +def test_drops_frontmatter(): + assert tts.text("---\ntitle: Scrubber\nstatus: draft\n---\n\nBody text.\n") == "Body text." + + +def test_drops_fenced_blocks_of_any_kind(): + markdown = ( + "Before.\n\n" + "```mermaid\nsequenceDiagram\n A->>B: hi\n```\n\n" + "````rust\nfn main() {}\n````\n\n" + "~~~\nplain\n~~~\n\n" + "After.\n") + assert tts.text(markdown) == "Before.\nAfter." + + +def test_drops_html_and_math(): + markdown = ( + "
\n

Hidden

\n
\n\n" + "A fee of $f$ per input.\n\n" + "$$\nx = y\n$$\n\n" + "Text with
a tag.\n") + assert tts.text(markdown) == "A fee of per input.\nText with a tag." + + +def test_keeps_link_and_inline_code_text(): + markdown = "See [BIP 370](https://example.com/370) and the `PSBT_IN_SIGHASH` field.\n" + assert tts.text(markdown) == "See BIP 370 and the PSBT_IN_SIGHASH field." + + +def test_drops_images_tables_and_footnote_definitions(): + markdown = ( + "Intro.[^1]\n\n" + "![diagram](d.svg)\n\n" + "| Field | Kept |\n|---|---|\n| a | b |\n\n" + "[^1]: A note.\n") + assert tts.text(markdown) == "Intro." + + +def test_drops_tables_without_outer_pipes(): + markdown = ( + "Fields:\n\n" + "`` | PSBT version | BIP |\n" + "--- | --- | --- |\n" + "`PSBT_GLOBAL_XPUB = 0x01` | 0, 2 | [174](https://example.com) |\n\n" + "After.\n") + assert tts.text(markdown) == "Fields:\nAfter." + + +def test_headings_and_list_items_are_units(): + markdown = "## Trust scope\n\n- Creator\n- Signer\n\n1. First\n2. Second\n" + assert tts.text(markdown) == "Trust scope.\nCreator.\nSigner.\nFirst.\nSecond." + + +def test_wrapped_paragraph_lines_join(): + assert tts.text("One sentence\nwrapped over\nthree lines.\n") == ( + "One sentence wrapped over three lines.") + + +def test_no_text(): + assert tts.text("---\ntitle: Stub\n---\n\n```mermaid\nA\n```\n") == "" + + +def test_name_depends_only_on_text(): + assert tts.name("Hello.") == tts.name("Hello.") + assert tts.name("Hello.") != tts.name("Hello!") + assert len(tts.name("Hello.")) == 16 diff --git a/contrib/tts.py b/contrib/tts.py new file mode 100644 index 0000000..a9f4d23 --- /dev/null +++ b/contrib/tts.py @@ -0,0 +1,102 @@ +#!/usr/bin/env python3 +"""Narration of the book's chapters. + +A chapter's readable text is read aloud as one audio file named by the hash +of that text, so audio rendered from other text is never mistaken for it. +""" +import hashlib +import re + +FRONTMATTER = re.compile(r"\A---\n.*?\n---[ \t]*(?:\n|\Z)", re.S) +FENCE = re.compile(r"^(`{3,}|~{3,})") +MATH_BLOCK = re.compile(r"\$\$") +BLANK = re.compile("") +# A header row, a delimiter row, then rows up to a blank line. Outer pipes +# are optional in markdown tables. +TABLE = re.compile( + r"^[^\n]*\|[^\n]*\n" + r"[ \t]*\|?[ \t]*:?-{3,}:?[ \t]*(?:\|[ \t]*:?-{3,}:?[ \t]*)*\|?[ \t]*\n" + r"(?:[^\n]*\|[^\n]*(?:\n|\Z))*", + re.M, +) +LIST_ITEM = re.compile(r"^(?:[-*+]|\d+[.)])\s+") +HEADING = re.compile(r"^#{1,6}\s+") +IMAGE = re.compile(r"!\[[^\]]*\]\([^)]*\)") +LINK = re.compile(r"\[([^\]]+)\]\([^)]*\)") +REFERENCE_LINK = re.compile(r"\[([^\]]+)\]\[[^\]]*\]") +FOOTNOTE_MARKER = re.compile(r"\[\^[^\]]+\]") +INLINE_CODE = re.compile(r"`+([^`]+)`+") +INLINE_MATH = re.compile(r"\$[^$\n]+\$") +TAG = re.compile(r"<[^>]+>") +EMPHASIS = re.compile(r"(? ")) + yield from flush() + + +def is_footnote_definition(line): + return line.startswith("[^") and "]:" in line + + +def clean(text): + text = IMAGE.sub("", text) + text = LINK.sub(r"\1", text) + text = REFERENCE_LINK.sub(r"\1", text) + text = FOOTNOTE_MARKER.sub("", text) + text = INLINE_MATH.sub("", text) + text = INLINE_CODE.sub(r"\1", text) + text = TAG.sub("", text) + text = EMPHASIS.sub(r"\1", text).replace("*", "") + return " ".join(text.split()) diff --git a/cspell/tooling.txt b/cspell/tooling.txt index 32ceda8..96d9520 100644 --- a/cspell/tooling.txt +++ b/cspell/tooling.txt @@ -10,6 +10,7 @@ foldl fontconfig Graphviz KaTeX +Kokoro lzanini mdBook mmdc From f84d21c7ce19690b8f0cb2d409572b3a09d99d0b Mon Sep 17 00:00:00 2001 From: bc1cindy Date: Sat, 14 Nov 2026 21:46:11 -0300 Subject: [PATCH 2/3] Render narration with Kokoro Render each chapter to one MP3 per voice inside the build, with the Kokoro from nixpkgs and its weights and voices fetched by hash. Each section, cut before each of the chapter's headings, is read by its own derivation per voice, so an edit re-renders only its section, and the start of each section is kept beside the MP3. Speaking lives in contrib/speak.py, apart from tts.py, so that a change to tts.py re-renders only the sections whose text it changes. The book is read in af_heart, am_echo, bf_emma and bf_isabella; the list is in nix/tts.nix. With an empty cache the Pages build narrates the whole book, at about 10 minutes per voice on a 4 core runner, which outlasts the 30 minute timeout. --- .github/workflows/pages.yml | 5 +- contrib/speak.py | 36 ++++++++++++ contrib/test_tts.py | 28 +++++++++ contrib/tts.py | 95 ++++++++++++++++++++++++++++-- cspell/tooling.txt | 2 + flake.nix | 1 + nix/site.nix | 20 +++++-- nix/tts.nix | 114 ++++++++++++++++++++++++++++++++++++ 8 files changed, 290 insertions(+), 11 deletions(-) create mode 100644 contrib/speak.py create mode 100644 nix/tts.nix diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index b0a258e..5b4c4eb 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -8,7 +8,10 @@ permissions: jobs: build: runs-on: ubuntu-latest - timeout-minutes: 30 + # With an empty cache, as after a week without builds, the build compiles + # wandb, which cache.nixos.org does not serve with its tests off, and + # narrates every chapter, at about 10 minutes per voice. + timeout-minutes: 90 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - uses: DeterminateSystems/nix-installer-action@3138316df39ed29be04236d7ffc686fa525866aa # v23 diff --git a/contrib/speak.py b/contrib/speak.py new file mode 100644 index 0000000..3558201 --- /dev/null +++ b/contrib/speak.py @@ -0,0 +1,36 @@ +#!/usr/bin/env python3 +"""Read a text aloud with Kokoro. + + python3 speak.py TEXT VOICE OUT + +reads the text file TEXT to the FLAC file OUT, taking the model from +KOKORO_CONFIG, KOKORO_MODEL and KOKORO_VOICES (a directory of .pt +files). It lives apart from tts.py so that changes there leave the rendered +sections cached. +""" +import os +import sys +from pathlib import Path + +import numpy +import soundfile +import torch +from kokoro import KModel, KPipeline + + +def main(): + if len(sys.argv) != 4: + sys.exit(__doc__) + text, voice, out = Path(sys.argv[1]).read_text(), sys.argv[2], sys.argv[3] + model = KModel(repo_id="hexgrad/Kokoro-82M", + config=os.environ["KOKORO_CONFIG"], model=os.environ["KOKORO_MODEL"]) + # The voice's first letter is its language: a for American, b for British + # English. + pipeline = KPipeline(lang_code=voice[0], repo_id="hexgrad/Kokoro-82M", model=model) + pack = torch.load(Path(os.environ["KOKORO_VOICES"]) / (voice + ".pt"), weights_only=True) + audio = [a for _, _, a in pipeline(text, voice=pack, speed=1) if a is not None] + soundfile.write(out, numpy.concatenate(audio), 24000, format="FLAC") + + +if __name__ == "__main__": + main() diff --git a/contrib/test_tts.py b/contrib/test_tts.py index a1e7cbd..e47bbcb 100644 --- a/contrib/test_tts.py +++ b/contrib/test_tts.py @@ -66,3 +66,31 @@ def test_name_depends_only_on_text(): assert tts.name("Hello.") == tts.name("Hello.") assert tts.name("Hello.") != tts.name("Hello!") assert len(tts.name("Hello.")) == 16 + + +def test_sections_cut_before_headings(): + markdown = "Lead.\n\n## Trust scope\n\nFirst.\n\n- Item\n\n### Roles\n\nSecond.\n" + assert tts.sections(markdown) == [ + {"title": "", "level": 0, "text": "Lead."}, + {"title": "Trust scope", "level": 2, "text": "Trust scope.\nFirst.\nItem."}, + {"title": "Roles", "level": 3, "text": "Roles.\nSecond."}, + ] + + +def test_sections_join_to_the_text(): + markdown = "# Title\n\nOne.\n\n```\n# not a heading\n```\n\n## Next\n\nTwo.\n" + assert "\n".join(s["text"] for s in tts.sections(markdown)) == tts.text(markdown) + assert [s["title"] for s in tts.sections(markdown)] == ["Title", "Next"] + + +def test_no_sections_without_text(): + assert tts.sections("```mermaid\nA\n```\n") == [] + + +def test_starts_add_up_durations(): + cut = [{"title": t, "level": 2, "text": ""} for t in "ABC"] + assert tts.starts(cut, [1.5, 2.25, 3]) == [ + {"title": "A", "level": 2, "start": 0.0}, + {"title": "B", "level": 2, "start": 1.5}, + {"title": "C", "level": 2, "start": 3.75}, + ] diff --git a/contrib/tts.py b/contrib/tts.py index a9f4d23..f8ed039 100644 --- a/contrib/tts.py +++ b/contrib/tts.py @@ -3,9 +3,27 @@ A chapter's readable text is read aloud as one audio file named by the hash of that text, so audio rendered from other text is never mistaken for it. + +Each section, cut before each of the chapter's headings, is read on its +own, so an edit re-reads only its section. nix/tts.nix runs + + python3 tts.py sections MARKDOWN + +to print the sections as JSON, reads each section to a FLAC file with +contrib/speak.py, then runs + + python3 tts.py join MARKDOWN OUT FLAC... + +to join them into OUT/.mp3, with the start of each section in +OUT/.json. """ import hashlib +import json import re +import subprocess +import sys +import tempfile +from pathlib import Path FRONTMATTER = re.compile(r"\A---\n.*?\n---[ \t]*(?:\n|\Z)", re.S) FENCE = re.compile(r"^(`{3,}|~{3,})") @@ -20,7 +38,7 @@ re.M, ) LIST_ITEM = re.compile(r"^(?:[-*+]|\d+[.)])\s+") -HEADING = re.compile(r"^#{1,6}\s+") +HEADING = re.compile(r"^(#{1,6})\s+") IMAGE = re.compile(r"!\[[^\]]*\]\([^)]*\)") LINK = re.compile(r"\[([^\]]+)\]\([^)]*\)") REFERENCE_LINK = re.compile(r"\[([^\]]+)\]\[[^\]]*\]") @@ -30,6 +48,9 @@ TAG = re.compile(r"<[^>]+>") EMPHASIS = re.compile(r"(? ")) yield from flush() @@ -100,3 +138,48 @@ def clean(text): text = TAG.sub("", text) text = EMPHASIS.sub(r"\1", text).replace("*", "") return " ".join(text.split()) + + +def starts(sections, durations): + """Return each section's title, level and start in seconds.""" + marks, at = [], 0.0 + for section, duration in zip(sections, durations): + marks.append({"title": section["title"], "level": section["level"], "start": round(at, 2)}) + at += duration + return marks + + +def join(markdown_path, out_dir, parts): + """Join the sections' FLAC files into OUT_DIR/.mp3 and .json.""" + import numpy + import soundfile + + markdown = Path(markdown_path).read_text() + cut = sections(markdown) + assert len(cut) == len(parts), "one FLAC file per section" + out_dir = Path(out_dir) + out_dir.mkdir(parents=True, exist_ok=True) + if not parts: + return + audio = [soundfile.read(p)[0] for p in parts] + stem = out_dir / name(text(markdown)) + stem.with_suffix(".json").write_text( + json.dumps(starts(cut, [len(a) / SAMPLE_RATE for a in audio]))) + with tempfile.NamedTemporaryFile(suffix=".wav") as wav: + soundfile.write(wav.name, numpy.concatenate(audio), SAMPLE_RATE) + subprocess.run(["ffmpeg", "-loglevel", "error", "-i", wav.name, + "-ac", "1", "-b:a", "64k", str(stem.with_suffix(".mp3"))], check=True) + + +def main(): + command, args = sys.argv[1] if len(sys.argv) > 1 else None, sys.argv[2:] + if command == "sections" and len(args) == 1: + json.dump(sections(Path(args[0]).read_text()), sys.stdout) + elif command == "join" and len(args) >= 2: + join(args[0], args[1], args[2:]) + else: + sys.exit(__doc__) + + +if __name__ == "__main__": + main() diff --git a/cspell/tooling.txt b/cspell/tooling.txt index 96d9520..74252cd 100644 --- a/cspell/tooling.txt +++ b/cspell/tooling.txt @@ -5,10 +5,12 @@ devshell DNSSEC dontInstall dylanowen +fetchurl fileset foldl fontconfig Graphviz +hexgrad KaTeX Kokoro lzanini diff --git a/flake.nix b/flake.nix index c0e75f6..bbc82ef 100644 --- a/flake.nix +++ b/flake.nix @@ -19,6 +19,7 @@ ./nix/site.nix ./nix/devshell.nix ./nix/spellcheck.nix + ./nix/tts.nix ./nix/apps/validate-commits ]; }; diff --git a/nix/site.nix b/nix/site.nix index a8d0f35..3197cc0 100644 --- a/nix/site.nix +++ b/nix/site.nix @@ -6,9 +6,23 @@ lib, fontconfig, mermaidSvgs, + narration, ... }: let + # The markdown the book's chapters come from. + markdown = [ + ../README.md + ] + ++ lib.filter (f: lib.hasSuffix ".md" (toString f)) (lib.filesystem.listFilesRecursive ../docs); + + # The markdown read aloud: contrib/book.py leaves these out of the chapters. + chapters = lib.subtractLists [ + ../docs/index.md + ../docs/log.md + ../docs/README.md + ] markdown; + # Only what the book is built from, so that changes to the nix files, # the tests or the spelling dictionaries do not rebuild it. src = lib.fileset.toSource { @@ -34,10 +48,7 @@ (python3.withPackages (ps: [ ps.pyyaml ])) ]; - MERMAID_SVG_DIR = mermaidSvgs ( - [ ../README.md ] - ++ lib.filter (f: lib.hasSuffix ".md" (toString f)) (lib.filesystem.listFilesRecursive ../docs) - ); + MERMAID_SVG_DIR = mermaidSvgs markdown; buildPhase = '' export FONTCONFIG_FILE=${fontconfig} @@ -73,6 +84,7 @@ packages = { inherit site; + narration = narration chapters; default = site; }; }; diff --git a/nix/tts.nix b/nix/tts.nix new file mode 100644 index 0000000..0c4b783 --- /dev/null +++ b/nix/tts.nix @@ -0,0 +1,114 @@ +{ ... }: +{ + perSystem = + { pkgs, lib, ... }: + let + # Kokoro's weights, config and voice packs, pinned to one revision of + # the model repository. + revision = "f3ff3571791e39611d31c381e3a41a3af07b4987"; + fetchModelFile = + path: hash: + pkgs.fetchurl { + url = "https://huggingface.co/hexgrad/Kokoro-82M/resolve/${revision}/${path}"; + inherit hash; + }; + config = fetchModelFile "config.json" "sha256-WrsB4kA7ByvwPQT94WBEPiCdeg2tSaQjvhUZa5tDwX8="; + model = fetchModelFile "kokoro-v1_0.pth" "sha256-SW26EY0aWPXz2y78iNvcIW4Eg/yJ/m5H7h8sU/GK0eQ="; + + # The voices the book is read in. The first, by name, is the default. + voiceHashes = { + af_heart = "sha256-CrVwm4/6sZv9hJzRHZj3W2CvdzMlOtDWexI4KhAstP8="; + am_echo = "sha256-i8/chSvJhftFw5bFYeVx/7kYOTAHH5YvG1DfXJexYeg="; + bf_emma = "sha256-0KQj3qv0pStPSTGMUXQsVOIbuJu76aEhQed1jdtdpwE="; + bf_isabella = "sha256-zdTDcAOAUQTR0I+x4FhVyPssaN4kym5x8mSjCqpZ7v0="; + }; + voices = builtins.attrNames voiceHashes; + # A directory with one voice's pack, so adding a voice leaves the others + # cached. + voicePack = + voice: + pkgs.linkFarm "kokoro-voice-${voice}" [ + { + name = "${voice}.pt"; + path = fetchModelFile "voices/${voice}.pt" voiceHashes.${voice}; + } + ]; + + python = + (pkgs.python3.override { + packageOverrides = final: prev: { + # Its tests fail on darwin against pillow 13. Kokoro only reaches + # it through wandb, and never calls it. + imageio = prev.imageio.overridePythonAttrs { doCheck = false; }; + # Its hypothesis tests miss their deadlines on a busy builder. + wandb = prev.wandb.overridePythonAttrs { doCheck = false; }; + }; + }).withPackages + (ps: [ + ps.kokoro + ps.soundfile + ps.spacy-models.en_core_web_sm + ]); + + tts = ../contrib/tts.py; + + # The chapter's sections, read at evaluation time from a derivation + # that needs only the standard library. + sections = + file: + lib.importJSON ( + pkgs.runCommand "sections.json" { nativeBuildInputs = [ pkgs.python3 ]; } '' + python ${tts} sections ${file} > $out + '' + ); + + # One derivation per section and voice, whose inputs are the section's + # text, the voice and the speaking script, so edits elsewhere in the book, + # or in the chapter, leave it cached. + speak = + voice: text: + pkgs.runCommand "narration-${voice}-${builtins.substring 0 12 (builtins.hashString "sha256" text)}.flac" + { + nativeBuildInputs = [ python ]; + KOKORO_CONFIG = config; + KOKORO_MODEL = model; + KOKORO_VOICES = voicePack voice; + HF_HUB_OFFLINE = "1"; + passAsFile = [ "text" ]; + inherit text; + } + '' + export HOME=$(mktemp -d) + python ${../contrib/speak.py} $textPath ${voice} $out + ''; + + # The chapter's sections joined into one file per voice. + render = + file: voice: + pkgs.runCommand "narration-${voice}-${builtins.substring 0 12 (builtins.hashFile "sha256" file)}" + { + nativeBuildInputs = [ + (pkgs.python3.withPackages (ps: [ + ps.numpy + ps.soundfile + ])) + pkgs.ffmpeg + ]; + } + '' + python ${tts} join ${file} $out/${voice} ${toString (map (s: speak voice s.text) (sections file))} + ''; + in + { + _module.args = { + # The narration of these markdown files, as /.mp3, with + # the start of each section in /.json. + narration = + files: + pkgs.symlinkJoin { + name = "narration"; + paths = lib.concatMap (file: map (render file) voices) files; + }; + }; + }; +} From b6dda281e9be672be2cf7e38ee653a1960074d63 Mon Sep 17 00:00:00 2001 From: bc1cindy Date: Sat, 14 Nov 2026 21:53:12 -0300 Subject: [PATCH 3/3] Add an audio player to each page Put the browser's audio player, one per rendered voice, at the top of each chapter, so that narration works without JavaScript. theme/narration.js replaces them with one player floating at the bottom of the page, opened from the menu bar: play, a timeline marked at the chapter's main sections, speed, voice, and the position where the reader stopped. The audio is linked from the site URL, since the print page holds every chapter at the root. The preprocessor lives apart from the renderer, so that changing it does not re-render the book. --- book.toml | 9 +- contrib/narration.py | 77 ++++++++++++++ contrib/test_narration.py | 81 ++++++++++++++ cspell/tooling.txt | 1 + nix/site.nix | 2 + theme/narration.css | 197 ++++++++++++++++++++++++++++++++++ theme/narration.js | 216 ++++++++++++++++++++++++++++++++++++++ 7 files changed, 582 insertions(+), 1 deletion(-) create mode 100644 contrib/narration.py create mode 100644 contrib/test_narration.py create mode 100644 theme/narration.css create mode 100644 theme/narration.js diff --git a/book.toml b/book.toml index 0b88649..da8ec12 100644 --- a/book.toml +++ b/book.toml @@ -18,7 +18,14 @@ after = ["links", "graphviz"] command = "mdbook-katex" after = ["links"] +# Reads the chapters' source, before the other preprocessors render it. +[preprocessor.narration] +command = "python3 contrib/narration.py" +after = ["links"] +before = ["graphviz", "mermaid", "katex"] + [output.html] -additional-css = ["theme/diagrams.css"] +additional-css = ["theme/diagrams.css", "theme/narration.css"] +additional-js = ["theme/narration.js"] git-repository-url = "https://github.com/fungi-protocol/docs" site-url = "/docs/" diff --git a/contrib/narration.py b/contrib/narration.py new file mode 100644 index 0000000..af2cf16 --- /dev/null +++ b/contrib/narration.py @@ -0,0 +1,77 @@ +#!/usr/bin/env python3 +"""An mdbook preprocessor that puts the narration's audio players in the book. + +If TTS_AUDIO_DIR is set, it puts a block of audio elements at the top of +every chapter, one for each voice whose TTS_AUDIO_DIR//.mp3 +exists, as nix/tts.nix renders them, with the start of each section from +TTS_AUDIO_DIR//.json. A chapter whose text was not rendered, +like the generated contents page, gets none. Otherwise it changes nothing. +theme/narration.js turns the block into a floating player. + +It lives apart from tts.py, which renders the audio, so that changing the +player does not re-render the book. +""" +import html +import json +import os +import sys +from pathlib import Path + +import tts + + +def narrate(chapter, audio_dir, site_url): + """Put an audio player per rendered voice at the top of the chapter. + + The player links its audio from SITE_URL, as the print page holds every + chapter at the root whatever the depth of its source. + """ + spoken = tts.text(chapter["content"]) + if not spoken: + return + mp3 = tts.name(spoken) + ".mp3" + players = [ + player(voice, mp3, site_url) + for voice in sorted(Path(audio_dir).iterdir()) + if (voice / mp3).exists() + ] + if players: + chapter["content"] = ( + '
\n' + "\n".join(players) + "\n
\n\n" + chapter["content"]) + + +def player(voice, mp3, site_url): + starts = (voice / mp3).with_suffix(".json") + sections = ( + f' data-sections="{html.escape(starts.read_text())}"' if starts.exists() else "") + return (f'') + + +def walk_book(context, book): + audio_dir = os.environ.get("TTS_AUDIO_DIR") + if not audio_dir: + return + site_url = context["config"].get("output", {}).get("html", {}).get("site-url", "/") + + def walk(items): + for item in items: + chapter = item.get("Chapter") if isinstance(item, dict) else None + if chapter: + narrate(chapter, audio_dir, site_url) + walk(chapter["sub_items"]) + + # mdbook 0.5 renamed the top level key from `sections` to `items`. + walk(book.get("items", book.get("sections"))) + + +def main(): + if len(sys.argv) > 1 and sys.argv[1] == "supports": + sys.exit(0) + context, book = json.load(sys.stdin) + walk_book(context, book) + json.dump(book, sys.stdout) + + +if __name__ == "__main__": + main() diff --git a/contrib/test_narration.py b/contrib/test_narration.py new file mode 100644 index 0000000..89c020c --- /dev/null +++ b/contrib/test_narration.py @@ -0,0 +1,81 @@ +import narration +import tts + + +CHAPTER = "## Trust scope\n\nEvery PSBT role inside it may observe the full PSBT.\n" + + +def render(audio_dir, voice, content): + mp3 = tts.name(tts.text(content)) + ".mp3" + (audio_dir / voice).mkdir(parents=True, exist_ok=True) + (audio_dir / voice / mp3).write_bytes(b"mp3") + return mp3 + + +def chapter(content): + return {"name": "Scrubber", "content": content, "sub_items": []} + + +CONTEXT = {"config": {"output": {"html": {"site-url": "/docs/"}}}} + + +def test_one_player_per_rendered_voice(tmp_path): + mp3 = render(tmp_path, "af_heart", CHAPTER) + render(tmp_path, "bf_emma", CHAPTER) + item = chapter(CHAPTER) + narration.narrate(item, tmp_path, "/docs/") + assert item["content"] == ( + '
\n' + f'\n' + f'\n' + '
\n\n' + + CHAPTER) + + +def test_player_carries_the_section_starts(tmp_path): + mp3 = render(tmp_path, "af_heart", CHAPTER) + (tmp_path / "af_heart" / mp3).with_suffix(".json").write_text( + '[{"title": "Trust scope", "start": 0.0}]') + item = chapter(CHAPTER) + narration.narrate(item, tmp_path, "/docs/") + assert ('') in item["content"] + + +def test_text_not_rendered_gets_no_player(tmp_path): + render(tmp_path, "af_heart", "Other text.") + item = chapter(CHAPTER) + narration.narrate(item, tmp_path, "/docs/") + assert item["content"] == CHAPTER + + +def test_no_player_for_a_chapter_without_text(tmp_path): + (tmp_path / "af_heart").mkdir() + item = chapter("```mermaid\nA\n```\n") + narration.narrate(item, tmp_path, "/docs/") + assert item["content"] == "```mermaid\nA\n```\n" + + +def test_walk_defaults_to_the_root_without_site_url(tmp_path, monkeypatch): + mp3 = render(tmp_path, "af_heart", CHAPTER) + monkeypatch.setenv("TTS_AUDIO_DIR", str(tmp_path)) + book = {"items": [{"Chapter": chapter(CHAPTER)}]} + narration.walk_book({"config": {}}, book) + assert f'src="/tts/af_heart/{mp3}"' in book["items"][0]["Chapter"]["content"] + + +def test_walk_without_audio_dir_changes_nothing(monkeypatch): + monkeypatch.setenv("TTS_AUDIO_DIR", "") + book = {"items": [{"Chapter": chapter(CHAPTER)}, "Separator"]} + narration.walk_book(CONTEXT, book) + assert book["items"][0]["Chapter"]["content"] == CHAPTER + + +def test_walk_reaches_sub_chapters(tmp_path, monkeypatch): + render(tmp_path, "af_heart", CHAPTER) + monkeypatch.setenv("TTS_AUDIO_DIR", str(tmp_path)) + child = chapter(CHAPTER) + book = {"items": [{"Chapter": dict(chapter("Short."), sub_items=[{"Chapter": child}])}]} + narration.walk_book(CONTEXT, book) + assert child["content"].startswith('
') diff --git a/cspell/tooling.txt b/cspell/tooling.txt index 74252cd..ef5c303 100644 --- a/cspell/tooling.txt +++ b/cspell/tooling.txt @@ -18,6 +18,7 @@ mdBook mmdc NixOS nixpkgs +nums pkgs prerender prerendered diff --git a/nix/site.nix b/nix/site.nix index 3197cc0..da2a4dd 100644 --- a/nix/site.nix +++ b/nix/site.nix @@ -49,11 +49,13 @@ ]; MERMAID_SVG_DIR = mermaidSvgs markdown; + TTS_AUDIO_DIR = narration chapters; buildPhase = '' export FONTCONFIG_FILE=${fontconfig} python3 contrib/book.py . mdbook build -d $out + cp -rL $TTS_AUDIO_DIR $out/tts ''; dontInstall = true; diff --git a/theme/narration.css b/theme/narration.css new file mode 100644 index 0000000..fb885fb --- /dev/null +++ b/theme/narration.css @@ -0,0 +1,197 @@ +/* The player theme/narration.js builds, floating at the bottom of the page. */ +:root { + --narration-moss: #556b2f; +} +:is(.coal, .navy, .ayu) { + --narration-moss: #8f9f62; +} + +.narration-capsule { + position: fixed; + inset-inline: 0; + bottom: max(16px, env(safe-area-inset-bottom)); + margin-inline: auto; + width: min(560px, calc(100vw - 32px)); + box-sizing: border-box; + z-index: 100; + display: flex; + align-items: center; + gap: 10px; + padding: 8px 10px 8px 8px; + color: var(--fg); + background: var(--theme-popup-bg); + border: 1px solid var(--theme-popup-border); + border-radius: 999px; + box-shadow: 0 6px 24px rgb(0 0 0 / 0.25); + font-size: 1.4rem; +} + +.narration-capsule[hidden] { + display: none; +} + +.narration-capsule button, +.narration-capsule select { + font: inherit; + color: inherit; + background: none; + border: 0; + cursor: pointer; +} + +.narration-play { + flex: none; + display: grid; + place-items: center; + width: 40px; + height: 40px; + border-radius: 50%; + background: var(--narration-moss) !important; + color: var(--bg) !important; +} + +.narration-play svg, +.narration-toggle svg { + width: 22px; + height: 22px; + fill: currentColor; +} + +.narration-track { + position: relative; + flex: 1; + min-width: 0; +} + +/* Drawn by hand, since browsers differ in how far accent-color reaches a + range input. --progress, set by narration.js, fills the part played. */ +.narration-timeline { + display: block; + width: 100%; + height: 20px; + margin: 0; + background: none; + appearance: none; + -webkit-appearance: none; + cursor: pointer; +} + +.narration-timeline::-webkit-slider-runnable-track { + height: 4px; + border-radius: 2px; + background: linear-gradient(to right, var(--narration-moss) var(--progress, 0%), var(--theme-popup-border) 0); +} + +.narration-timeline::-moz-range-track { + height: 4px; + border-radius: 2px; + background: linear-gradient(to right, var(--narration-moss) var(--progress, 0%), var(--theme-popup-border) 0); +} + +.narration-timeline::-webkit-slider-thumb { + -webkit-appearance: none; + width: 14px; + height: 14px; + margin-top: -5px; + border: none; + border-radius: 50%; + background: var(--narration-moss); +} + +.narration-timeline::-moz-range-thumb { + width: 14px; + height: 14px; + border: none; + border-radius: 50%; + background: var(--narration-moss); +} + +/* The section marks sit on the timeline; only the marks take clicks. */ +.narration-marks { + position: absolute; + inset: 0; + pointer-events: none; +} + +.narration-mark { + position: absolute; + top: 50%; + width: 12px; + height: 20px; + padding: 0 !important; + transform: translate(-50%, -50%); + pointer-events: auto; +} + +.narration-mark::before { + content: ""; + display: block; + width: 1px; + height: 8px; + margin: auto; + background: var(--icons); + opacity: 0.35; +} + +.narration-mark:hover::before, +.narration-mark:focus-visible::before { + width: 2px; + height: 12px; + background: var(--narration-moss); + opacity: 1; +} + +.narration-time { + flex: none; + color: var(--icons); + font-variant-numeric: tabular-nums; +} + +.narration-rate { + flex: none; + min-width: 3.2em; + padding: 4px 6px; + border-radius: 6px; + font-variant-numeric: tabular-nums; +} + +.narration-voice { + flex: none; + max-width: 7em; +} + +.narration-close { + flex: none; + font-size: 1.3em !important; + line-height: 1; + padding: 0 4px; + color: var(--icons) !important; +} + +.narration-capsule :is(button, select, input):focus-visible { + outline: 2px solid var(--narration-moss); + outline-offset: 2px; +} + +.narration-capsule :is(.narration-rate, .narration-close, .narration-voice):hover { + color: var(--icons-hover) !important; + background: var(--theme-hover); +} + +.narration-toggle.narration-active { + color: var(--narration-moss); +} + +@media (max-width: 480px) { + .narration-time { + display: none; + } +} + +@media print { + .narration-capsule, + .narration-toggle, + .narration { + display: none !important; + } +} diff --git a/theme/narration.js b/theme/narration.js new file mode 100644 index 0000000..3de251b --- /dev/null +++ b/theme/narration.js @@ -0,0 +1,216 @@ +// Replaces the audio elements contrib/narration.py puts at the top of a +// chapter with a player that floats at the bottom of the page, opened from +// the menu bar. Without JavaScript the plain audio elements stay. +(function () { + "use strict"; + + const players = document.querySelectorAll(".narration"); + // The print page holds every chapter, each with its own audio, and keeps + // the plain elements. + if (players.length !== 1) return; + + const SPEEDS = [1, 1.25, 1.5, 2]; + const PLAY = "M8 5v14l11-7z"; + const PAUSE = "M6 5h4v14H6zM14 5h4v14h-4z"; + const SPEAKER = + "M3 9v6h4l5 5V4L7 9H3zm13.5 3A4.5 4.5 0 0 0 14 8v8a4.5 4.5 0 0 0 2.5-4zM14 3.2v2.1a7 7 0 0 1 0 13.4v2.1a9 9 0 0 0 0-17.6z"; + + // Storage may be refused, in a private window for example; the player + // then forgets its settings with the page. + function load(key) { + try { + return localStorage.getItem("narration-" + key); + } catch (e) { + return null; + } + } + function save(key, value) { + try { + localStorage.setItem("narration-" + key, value); + } catch (e) {} + } + + function icon(path) { + const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg"); + svg.setAttribute("viewBox", "0 0 24 24"); + svg.setAttribute("aria-hidden", "true"); + const shape = document.createElementNS("http://www.w3.org/2000/svg", "path"); + shape.setAttribute("d", path); + svg.append(shape); + return svg; + } + + function element(tag, className, label) { + const node = document.createElement(tag); + node.className = className; + if (tag === "button") node.type = "button"; + if (label) { + node.title = label; + node.setAttribute("aria-label", label); + } + return node; + } + + function clock(seconds) { + if (!isFinite(seconds)) return "--:--"; + const s = Math.floor(seconds); + return Math.floor(s / 60) + ":" + String(s % 60).padStart(2, "0"); + } + + const audios = Array.from(players[0].querySelectorAll("audio")); + const sources = new Map(audios.map((a) => [a.title, a.getAttribute("src")])); + // Each voice's sections, as title and start in seconds. + const sections = new Map(audios.map((a) => [a.title, JSON.parse(a.dataset.sections || "[]")])); + const voices = Array.from(sources.keys()); + const savedVoice = load("voice"); + const savedSpeed = Number(load("speed")); + let voice = voices.includes(savedVoice) ? savedVoice : voices[0]; + let speed = SPEEDS.includes(savedSpeed) ? savedSpeed : 1; + players[0].hidden = true; + + const audio = new Audio(); + audio.preload = "metadata"; + // The position is kept per audio file, so it resets when the text changes. + const positionKey = () => "position-" + sources.get(voice); + + const capsule = element("div", "narration-capsule"); + capsule.setAttribute("role", "region"); + capsule.setAttribute("aria-label", "Narration"); + capsule.hidden = true; + + const play = element("button", "narration-play", "Play narration"); + const playIcon = icon(PLAY); + play.append(playIcon); + + const timeline = element("input", "narration-timeline", "Position"); + timeline.type = "range"; + timeline.min = 0; + timeline.max = 0; + timeline.step = "any"; + timeline.value = 0; + const track = element("div", "narration-track"); + const marks = element("div", "narration-marks"); + track.append(timeline, marks); + + const time = element("span", "narration-time"); + const rate = element("button", "narration-rate", "Playback speed"); + const close = element("button", "narration-close", "Close narration"); + close.textContent = "×"; + + capsule.append(play, track, time, rate); + if (voices.length > 1) { + const select = element("select", "narration-voice", "Voice"); + for (const v of voices) select.append(new Option(v, v, false, v === voice)); + select.addEventListener("change", () => { + const at = audio.currentTime; + const resume = !audio.paused; + voice = select.value; + save("voice", voice); + setSource(at); + if (resume) audio.play(); + }); + capsule.append(select); + } + capsule.append(close); + document.body.append(capsule); + + const toggle = element("button", "icon-button narration-toggle", "Listen to this page"); + toggle.setAttribute("aria-expanded", "false"); + toggle.append(icon(SPEAKER)); + document.querySelector("#mdbook-menu-bar .left-buttons")?.append(toggle); + + function setSource(at) { + audio.src = sources.get(voice); + audio.defaultPlaybackRate = audio.playbackRate = speed; + audio.addEventListener("loadedmetadata", () => (audio.currentTime = at), { once: true }); + } + + // A mark on the timeline at the start of each of the chapter's main + // sections, those under its two shallowest heading levels, that jumps to + // it. A mark closer than 2% to the one before replaces it, so marks never + // cover each other and a heading right below the title keeps its mark. + function mark() { + marks.replaceChildren(); + const headed = sections.get(voice).filter((s) => s.level); + const deepest = Math.min(...headed.map((s) => s.level)) + 1; + let last = -Infinity; + for (const { title, level, start } of sections.get(voice)) { + const at = (100 * start) / audio.duration; + if (level > deepest) continue; + if (at - last < 2) marks.lastChild?.remove(); + last = at; + const button = element("button", "narration-mark", title || document.title); + button.style.left = at + "%"; + button.addEventListener("click", () => (audio.currentTime = start)); + marks.append(button); + } + } + + function show() { + const playing = !audio.paused; + playIcon.firstChild.setAttribute("d", playing ? PAUSE : PLAY); + play.setAttribute("aria-label", playing ? "Pause narration" : "Play narration"); + play.title = play.getAttribute("aria-label"); + time.textContent = clock(audio.currentTime) + " / " + clock(audio.duration); + rate.textContent = speed + "×"; + toggle.classList.toggle("narration-active", playing); + } + + function open(visible) { + // The audio loads when the player first opens, so a reader who never + // opens it downloads none of it. + if (visible && !audio.src) setSource(Number(load(positionKey())) || 0); + capsule.hidden = !visible; + toggle.setAttribute("aria-expanded", String(visible)); + if (!visible) audio.pause(); + } + + toggle.addEventListener("click", () => { + open(capsule.hidden); + if (!capsule.hidden) play.focus(); + }); + close.addEventListener("click", () => { + open(false); + toggle.focus(); + }); + // Only while focus is in the player, so Escape still closes mdbook's search. + capsule.addEventListener("keydown", (event) => { + if (event.key !== "Escape") return; + open(false); + toggle.focus(); + }); + play.addEventListener("click", () => (audio.paused ? audio.play() : audio.pause())); + rate.addEventListener("click", () => { + speed = SPEEDS[(SPEEDS.indexOf(speed) + 1) % SPEEDS.length]; + audio.defaultPlaybackRate = audio.playbackRate = speed; + save("speed", speed); + show(); + }); + timeline.addEventListener("input", () => (audio.currentTime = Number(timeline.value))); + + audio.addEventListener("loadedmetadata", () => { + timeline.max = audio.duration; + mark(); + show(); + }); + audio.addEventListener("timeupdate", () => { + timeline.value = audio.currentTime; + timeline.style.setProperty("--progress", (100 * audio.currentTime) / audio.duration + "%"); + save(positionKey(), audio.currentTime); + show(); + }); + audio.addEventListener("play", show); + audio.addEventListener("pause", show); + audio.addEventListener("ended", () => save(positionKey(), 0)); + + if ("mediaSession" in navigator) { + navigator.mediaSession.metadata = new MediaMetadata({ title: document.title }); + const skip = (by) => () => (audio.currentTime = Math.max(0, audio.currentTime + by)); + navigator.mediaSession.setActionHandler("play", () => audio.play()); + navigator.mediaSession.setActionHandler("pause", () => audio.pause()); + navigator.mediaSession.setActionHandler("seekbackward", skip(-10)); + navigator.mediaSession.setActionHandler("seekforward", skip(10)); + } + + show(); +})();