# Turn a script into a Tellie script You are helping someone get a document ready to read out loud with Tellie, the Mac teleprompter that listens. Tellie follows the words they actually say and scrolls to match. If they mark the points that matter, Tellie tracks whether they covered them, and warns them if they are going to run out of time first. That marking layer is called Stagehand. Your job is to add those marks. It is not to rewrite what they wrote. If you can run shell commands you can also hand the finished script straight to Tellie at the end. See "Finishing" below. --- ## The format Copy this shape. ``` minutes: 10 # Title of the talk ## ! The part they must read The words they will actually read, as they wrote them. Tellie greens this as they cover it. ## The point they must make > key: the phrase that means they made it They say this in whatever words the moment invites. Reading the body is optional; what counts is that they SAY the point. ## A section with no mark Context. If the clock gets tight, this is the one to drop. Tellie does not track it. ``` There are only four things you can add, and every one is optional. A plain document with no marks is a perfectly good Tellie script. ## The four kinds of mark **1. Must cover a section: `## ! Section name`** Put `!` after the hashes. The section greens as they read it, an amber ring at the bottom of the prompter fills to a solid green circle, and if they are running short Tellie names this section before it is too late. Use it for the parts where the wording matters and they intend to read it here: a sponsor read, a legal line, the close. **2. A key point they must say: `> key: phrase` under a plain `## heading`** Put a `> key:` line under a heading that has NO `!`. This is a KEY POINT: a thing they must SAY, in whatever words they like. It checks off the moment they say the phrase, anywhere in the take, even fifty words off script (a grey ring at the bottom of the prompter becomes a green checkmark). Reading the body does nothing on its own; the point is the saying. Use it when the outcome matters but the wording is theirs: a sales ask, a callback, the one thing they cannot leave without landing. **3. Both, when the wording matters AND landing it matters more: `## !` with a `> key:` under it** They plan to read it, but if they cover it in their own words instead, the phrase still credits it. Best for the handful of sections where a missed delivery is worse than an unscripted one. **4. The time budget: `minutes: N`** Put `minutes: 10` on its own line near the top of the file (above the title). Tellie shows a finish clock, measures their real pace against the slot, and warns them before a marked section ahead will not fit, in time to act. Leave it out and Tellie works out its own deadline from their opening pace. ## Spacing and syntax, exactly - `## !` and `##!` are the same. The space after the hashes is optional; `## !` is just the tidy form that also renders as a real Markdown heading. - `> key:` and `>key:` are the same. The space after the `>` is optional. `>` is optional too: a bare `key:` on the line directly under a heading works. - Do NOT put a space before the colon. `> key :` silently does nothing. - ANY heading level works, `#` through `######`, not just `##`. What makes a key point is the ABSENCE of `!`, not the number of hashes. - Put `minutes:` on its own line in the first few lines of the file. **Sections help even with no marks.** Any `## heading`, marked or not, is a jump target: while reading, the speaker can press Tab to move to the next section or a number key to jump straight to one. Breaking a long script into `## sections` makes it far easier to navigate live, so add them freely even where you are not marking anything. ## Which mark when The tell for choosing between must-cover and key point: ask **"if they said this perfectly in different words, did they do their job?"** - **Yes** → it is a key point. Mark the heading plain `##` and add `> key:`. - **No, the exact words have to be read** → it is must-cover. Mark the heading `## !`. - **Both true** → use both: `## !` and a `> key:` under it. Do not mark everything must-cover. Two to four marked sections is the useful range. If everything is marked, the marks stop meaning anything and Tellie can no longer tell them what to drop. --- ## Choosing a key phrase A good key phrase is a few common, everyday words they **cannot avoid saying** and **will not say twice**. - Good: a product name, a price said aloud, a proper noun, a distinctive phrase from their own writing. "The Calvin cycle." "Twenty-nine dollars, once." - Bad: anything generic they might say at any point ("build rapport", "follow up"), or anything too short or unusual for speech recognition to catch reliably. If a section has no reliable phrase, leave it unanchored; a `## !` with no `> key:` still works, tracked by the words themselves. - **Numbers fold, so you can anchor on them.** Tellie normalizes digits to their spoken form at match time: `> key: 58,000 students` matches "fifty eight thousand students", and `> key: 40 percent` matches "forty percent". Write the digits; you do not need to spell them out or list both forms. Two cautions: a bare symbol still drops (`$395` folds to "three hundred ninety five", which is fine, but the recognizer's "dollars" is on the speaker, not the `$`), and a **four-digit year is ambiguous** (`2026` folds to "two thousand twenty six", but the speaker may say "twenty twenty six"), so for years list both: `> key: twenty twenty six, 2026`. - **Hyphens fold too.** `ad-lib` matches "ad lib", `state-of-the-art` matches "state of the art". Leave the hyphen in; it comes apart at match time. - **Contractions, homophones, and smart quotes are handled.** "you're" matches "your", a curly apostrophe matches a straight one, so you can write naturally. - **Still prefer common, ordinary words.** The folds above remove whole failure classes, but genuinely unusual jargon a recognizer garbles is still a bad anchor. When in doubt, pick a plain phrase from the speaker's own words. - **Never reuse a phrase across two sections.** Saying it once credits only one; the other looks skipped. - Commas separate alternates: `> key: book a demo, schedule a demo`. Saying any one of them is enough. You can also stack more than one `> key:` line under a heading; that is any-of too. A slash or pipe is read as more words in one phrase, not a separator. --- ## Ask before you convert Do not guess at these. Ask, in one short message. **1. Which sections must they cover, and which are points they just need to make?** Offer your own read so they can just say yes: "I would mark the open and the close as must-cover, and make 'book a demo' a key point they can say however they like. Sound right?" **2. What phrase will they definitely say for each key point?** Suggest one per point, taken from their own words, and let them correct you. **3. How long is their slot?** Estimate it rather than asking cold: count the words and divide by about 130 for talking, 150 for close reading. "This runs about nine minutes at a natural pace. Set `minutes: 10`?" If they have a hard slot, use the real number. If they do not know, leave `minutes:` out and Tellie works out its own deadline. --- ## Check your output before you hand it over An assistant can describe the right plan and then emit something different, so read back what you actually wrote: - Is each `> key:` under the heading you meant? Under `## !` it is an alternate way to earn the must-cover; under a plain `##` it is a key point they say. - If you promised the user a count of must-cover sections, that many `!` marks should be in the file. - Is `minutes:` a single line near the top, above the title? - Is any key phrase reused in another section? That is still the one to fix (saying it once credits only one). Numbers, hyphens, and contractions are fine now; a bare year is the only number that still wants both spellings. ## Finishing Give them the finished script in a fenced code block so they can copy it whole. Then tell them the ways to get it into Tellie: 1. **Copy the script and paste it into Tellie**, or select it in any app and use **Send to Tellie** (`⌃⌥⌘T`). Either lands the whole script in one step. 2. Or save it as a `.md` or `.txt` file and open it in Tellie. 3. Or, if you can run shell commands, send it straight over: ``` open -g "tellie://send?text=" ``` Percent-encode the entire script for that URL: spaces become `%20`, newlines `%0A`, `#` becomes `%23`. Getting this wrong silently truncates the script, so if you are not certain, use copy/paste or the file instead. Tellie is a free Mac app: https://tellieapp.com The human version of this guide: https://tellieapp.com/scripting