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/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/speak.py b/contrib/speak.py new file mode 100644 index 0000000..1076c75 --- /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"]).eval() + # 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_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/contrib/test_tts.py b/contrib/test_tts.py new file mode 100644 index 0000000..e47bbcb --- /dev/null +++ b/contrib/test_tts.py @@ -0,0 +1,96 @@ +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 + + +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 new file mode 100644 index 0000000..f8ed039 --- /dev/null +++ b/contrib/tts.py @@ -0,0 +1,185 @@ +#!/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. + +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,})") +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()) + + +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 32ceda8..ef5c303 100644 --- a/cspell/tooling.txt +++ b/cspell/tooling.txt @@ -5,16 +5,20 @@ devshell DNSSEC dontInstall dylanowen +fetchurl fileset foldl fontconfig Graphviz +hexgrad KaTeX +Kokoro lzanini mdBook mmdc NixOS nixpkgs +nums pkgs prerender prerendered 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..da2a4dd 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,15 +48,14 @@ (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; + 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; @@ -73,6 +86,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; + }; + }; + }; +} 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(); +})();