# 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. 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 exactly. ``` --- minutes: 10 --- # Title of the talk ## ! A section they must cover > key: a phrase they will say, an alternative phrasing The words they will actually read, as they wrote them. ## A section with no mark Worth covering, but if the clock gets tight this is the one to drop. Tellie does not track it. ``` Four marks, and only the first is required: - `## Section name` starts a section. Tellie can jump between sections and the reader can Tab or press a number key to reach one. - `## ! Section name` marks it **must-cover**. The text greens as they cover it, a pip checks off, and if they are running short Tellie names this section before it is too late. - `> key: phrase` sits on the line directly under a `## !` heading. If they say that phrase anywhere in the take, even improvising, the section counts as covered. Comma-separate alternatives; saying any one of them is enough. - `minutes: N` sets the time budget. It goes inside a `---` block at the very top of the file, before the title. ## The two mistakes that fail silently Both of these produce a script that looks correct and does nothing. There is no error message, so check your own output for them. 1. **An anchor under a plain `##`.** A `> key:` line only does something under a `## !` heading, because Tellie tracks only the sections you marked. Under an unmarked `##` it is parsed and then ignored: no pip, no tally, no warning. **This is the most common mistake, and two different AI assistants made it on their first try.** If a section deserves an anchor, it deserves the `!`. 2. **A bare `key:` line.** The angle bracket is required: `> key: the phrase`. Without it the line is read as ordinary script text and is spoken aloud. 3. **A loose `minutes:` line.** It must be inside `---` fences as the first lines of the file. A `minutes: 10` sitting under the title does nothing. --- ## Ask before you convert Do not guess at these. Ask, in one message, and keep it short. **1. Which sections must they cover?** Offer your own reading first so they can just say yes: "I would mark the open, the price, and the close as must-cover, and leave the middle three free. Sound right?" Most talks have two to four. If everything is marked must-cover, the marks stop meaning anything and Tellie can no longer tell them what to drop. **2. What phrase will they definitely say in each marked section?** Suggest one per marked section, taken from their own words, and let them correct you. **3. How long is their slot?** Estimate it for them rather than asking cold. Count the words and divide by about 130 for talking, 150 if they are reading closely. Then say: "This runs about nine minutes at a natural pace. Shall I set `minutes: 10`?" If they have a hard slot, use the real number, not your estimate. If they do not know, leave `minutes:` out entirely: Tellie will work out a deadline from their own opening pace. --- ## Choosing an anchor phrase A good anchor is a phrase they **cannot avoid saying** and **will not say twice**. - Good: a product name, a price, 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." If a section has no reliable phrase, leave it unanchored. A `## !` with no `> key:` still works: Tellie tracks it by the words themselves. - **Numbers and symbols are the common trap.** Speech recognition decides on its own whether it heard "forty" or "40", and the two do not match. Never anchor on a symbol: `$395` is never what anybody says. Write what comes out of a mouth, and list both spellings: `> key: three hundred ninety five dollars, 395 dollars`, `> key: forty percent, 40 percent`. - **Never reuse a phrase across two sections.** If the same anchor appears twice, saying it once credits only one of them and the other looks skipped. - Commas are the only separator. A slash or a pipe is read as more words in one phrase. ## What not to do - **Do not rewrite their words.** Their voice is the point. You are adding marks around what they already wrote. - **Do not mark every section must-cover.** Two to four is the useful range. - **Do not invent an anchor they would not naturally say.** An anchor they have to remember is worse than no anchor. - **Do not add `minutes:` if they do not have a real slot.** Tellie's own estimate from their live pace is better than a made-up number. - Plain text with no marks at all is a perfectly good Tellie script. If their document does not need any of this, say so. --- ## Check your own 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: - Does every `> key:` line sit directly under a `## !` heading? Count them. If you said you would mark three sections must-cover, there should be three `!` marks in the file. - Does every `> key:` start with `>`? - Is `minutes:` between two `---` lines at the very top, above the title? - Is any anchor a number, a symbol, or a phrase used in another section? If you promised the user a count in your plan, the file has to match it. ## Finishing Give them the finished script in a fenced code block so they can copy it whole. Then tell them the two ways to get it into Tellie: 1. Save it as a `.md` or `.txt` file and open it in Tellie. 2. Or, if you can run shell commands, offer to 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, give them the file instead. Tellie is a free Mac app: https://tellieapp.com The human version of this guide: https://tellieapp.com/scripting