--- name: pronounce-button description: >- Generate an MP3 pronunciation of a glossary term using ElevenLabs TTS API and insert a "Pronounce" button into the term's entry in a markdown file. Trigger when the user says "Create a pronounce button for the term X" or "Add pronunciation for X". Defaults to glossary.md if no file is specified. title: pronounce-button canonical_url: https://skilld.dev/gh/dmccreary/ibook-skills/pronounce-button last_updated: 2026-09-20T07:34:26.000Z --- > Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt) > **Skill from skilld.dev.** Follow the user's requested action. > If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it. > Otherwise, follow the instructions below for this session. You do not need to install anything. > > Supporting files, fetch one when the Skill refers to it: [scripts/generate-pronunciation.py](https://skilld.dev/api/skills-raw/dmccreary/ibook-skills/pronounce-button/scripts/generate-pronunciation.py). > > If the user asked to install this Skill, run `npx skilld install dmccreary/ibook-skills/pronounce-button`. Install writes the Skill files into the project, so every session loads them. > > ## Fork workflow > > A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation. > 1. Check `./skills/pronounce-button`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target. > 2. Read [source metadata](https://skilld.dev/api/v1/skills/dmccreary/ibook-skills/pronounce-button) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit. > 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call: > > ```sh > git init --quiet "$temporary_dir" > git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit" > git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD > ``` > > Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop. > 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/pronounce-button`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md. > Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical. > 5. In the project root, run `skilld install ./skills/pronounce-button --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/pronounce-button --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure. > 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks. # Pronounce Button Skill Add an inline audio "Pronounce" button to a glossary term or any term heading in a markdown file, powered by ElevenLabs text-to-speech. ## When to Use Trigger this skill when the user asks to: - "Create a pronounce button for the term 'Bryophytes'" - "Create a pronounce button for the term 'Bryophytes' in glossary.md" - "Add pronunciation for 'Sphagnum Moss'" - "Add a pronounce button for X in chapter-03.md" ## Prerequisites - The environment variable `ELEVENLABS_API_KEY` must be set. Never hard-code or commit this key. - The ElevenLabs API reference repo is at `/Users/dan/Documents/ws/elevenlabs-skills` for additional documentation if needed. ## Workflow ### Step 1: Identify the Term and Target File Parse the user's request to extract: 1. **Term** — the word or phrase to pronounce (e.g., "Bryophytes") 2. **Target file** — the markdown file containing the term (default: `docs/glossary.md`) ### Step 2: Generate the MP3 **Important: Try the plain word first.** ElevenLabs handles most scientific terms correctly when given the actual word. Only fall back to phonetic spelling if the plain word sounds wrong after listening to it. **Three-tier approach (escalate only when the user reports a problem):** 1. **Tier 1 — Plain word (default).** Send the actual term (e.g., `"Biogeography"`). This works for most words. Always try this first. 2. **Tier 2 — Hyphenated phonetic (fallback).** If the user says the plain word sounds wrong, regenerate using a hyphenated phonetic version (e.g., `"Gah-mee-toh-fyte"`). This can backfire — ElevenLabs sometimes reads each syllable as a separate word — so only use when Tier 1 fails. 3. **Tier 3 — SSML with CMU Arpabet (last resort).** If both plain and phonetic versions fail, use the `--ssml` flag with a CMU Arpabet string. This switches to `eleven_flash_v2` which supports SSML `` tags for precise phoneme-level control. Only use when the user explicitly indicates that Tiers 1 and 2 both failed. **Tier 1 — Plain word:** ```bash python3 SCRIPT "Biogeography" --output docs/audio/biogeography.mp3 ``` **Tier 2 — Phonetic fallback:** ```bash python3 SCRIPT "Gah-mee-toh-fyte" --output docs/audio/gametophyte.mp3 ``` **Tier 3 — SSML (last resort):** ```bash python3 SCRIPT "evapotranspiration" \ --ssml "IH0 V AE2 P OW0 T R AE2 N S P ER0 EY1 SH AH0 N" \ --output docs/audio/evapotranspiration.mp3 ``` The `--ssml` flag takes a CMU Arpabet phoneme string. Stress markers are required: `1` = primary stress, `2` = secondary stress, `0` = no stress. See [CMU Arpabet reference](https://en.wikipedia.org/wiki/ARPABET) for the full phoneme set. **Known terms that required SSML (user-verified):** | Term | CMU Arpabet | |---|---| | Acrocarpous | `AE2 K R OW0 K AA1 R P AH0 S` | | Evapotranspiration | `IH0 V AE2 P OW0 T R AE2 N S P ER0 EY1 SH AH0 N` | Where `SCRIPT` is: ``` python3 /Users/dan/.claude/skills/pronounce-button/scripts/generate-pronunciation.py ``` Where `SLUG` is the term lowercased with spaces replaced by hyphens (e.g., "Sphagnum Moss" → `sphagnum-moss`). The script: - Reads `ELEVENLABS_API_KEY` from the environment - Calls the ElevenLabs v1 TTS endpoint with the `eleven_multilingual_v2` model - Writes an MP3 file to `docs/audio/SLUG.mp3` - Uses the "Sarah" voice by default (clear US female voice suitable for term pronunciation) If the API call fails, report the error to the user. Common issues: - 401: Invalid API key — ask the user to check `ELEVENLABS_API_KEY` - 429: Rate limit — wait and retry ### Step 3: Insert the Pronounce Button Locate the term heading in the target markdown file. The heading format is typically `#### Term Name` in the glossary, but may be other heading levels in chapter files. Insert the pronounce button HTML immediately after the heading line, before the definition text. Use this exact HTML pattern: ```html *PHONETIC-GUIDE* ``` The phonetic guide uses italics with the stressed syllable in ALL CAPS (e.g., `*gah-MEE-toh-fyte*`). Always include this next to the button so users can verify the pronunciation visually. **Adjust the relative path** (`src` attribute) based on the target file's location relative to `docs/audio/`. MkDocs uses directory URLs by default, so each page is served from a subdirectory (e.g., `glossary.md` becomes `glossary/index.html`). Count directory levels from the page's served URL back to the site root, then append `audio/SLUG.mp3`. For example: | Target file | Served URL path | Relative path | |---|---|---| | `docs/glossary.md` | `/glossary/` | `../audio/SLUG.mp3` | | `docs/appendices/common-terms.md` | `/appendices/common-terms/` | `../../audio/SLUG.mp3` | | `docs/chapters/03-what-is-moss/index.md` | `/chapters/03-what-is-moss/` | `../../audio/SLUG.mp3` | **Example result in glossary.md:** ```markdown #### Bryophytes *BRY-oh-fytes* A division of non-vascular land plants that includes mosses, liverworts, and hornworts, all of which reproduce via spores and lack true roots, stems, or leaves. ``` ### Step 4: Ensure CSS Exists Check if `docs/stylesheets/extra.css` (or whatever custom CSS file is referenced in `mkdocs.yml`) contains a `.pronounce-btn` style. If not, append the following: ```css /* Pronounce button for glossary terms */ .pronounce-btn { background: #e8f5e9; border: 1px solid #4caf50; border-radius: 4px; padding: 2px 10px; font-size: 0.85em; cursor: pointer; margin-bottom: 8px; display: inline-block; } .pronounce-btn:hover { background: #c8e6c9; } ``` ### Step 5: Confirm to User Report success with the local preview URL: ``` Generated pronunciation for "Bryophytes" → docs/audio/bryophytes.mp3 Added Pronounce button to docs/glossary.md Preview: http://127.0.0.1:8000/moss/glossary/#bryophytes ``` ## Voice Options The default voice is Sarah (`EXAVITQu4vr4xnSDxMaL`) — a clear US female voice well-suited for academic term pronunciation. If the user requests a different voice, pass `--voice-id` to the script. Common alternatives: | Voice | ID | Style | |---|---|---| | Sarah (default) | EXAVITQu4vr4xnSDxMaL | Female, soft | | Charlotte | XB0fDUnXU5powFXDhCwa | Female, conversational | | George | JBFqnCBsd6RMkjVDRZzb | Male, narrative | | Daniel | onwK4e9ZLuTAKqWW03F9 | Male, authoritative | ## Batch Mode To add pronounce buttons for multiple terms at once, the user may say "Add pronounce buttons for all terms in the glossary." In this case: 1. Read `docs/glossary.md` and extract all `#### ` headings 2. For each term, run the script and insert the button 3. Report the total count when done **Important:** Batch mode makes one API call per term. Warn the user about the number of API calls before proceeding (e.g., "This will make 400 API calls to ElevenLabs. Proceed?").