# VoiceScroll > VoiceScroll is a teleprompter app that listens as you read aloud and scrolls the script to the words you say. It waits when you pause. This file tells an AI assistant how to write a script for VoiceScroll and how to make a link that opens the script in the app. VoiceScroll runs on iPhone, iPad, and Android. It also runs on Macs with Apple silicon (M1 or later) and macOS 26 or later; the Mac app is the same App Store app as the iPhone and iPad app. - [App Store (iPhone, iPad, Mac)](https://apps.apple.com/app/voicescroll/id6760583162) - [Google Play (Android)](https://play.google.com/store/apps/details?id=com.voicescroll.android) - [Website](https://www.voice-scroll.com) ## Writing a script for VoiceScroll - Write plain text, the way the reader will say it. Leave out headings, bullet points, bold text, and emoji. They are not words the reader says. - Put text the reader does not say in square brackets, each short and on one line: stage directions such as [pause] or [smile], and section names such as [Intro]. VoiceScroll does not wait for text in square brackets. It takes it out of the line and shows it on its own when the reader reaches it. - Everything outside square brackets is read aloud, and the app waits for it. Don't leave a title, a word count, or a note such as "Script:" as plain text. - Don't use square brackets for anything else, such as citation numbers. - Square brackets are the default. A reader can change the marks to parentheses or braces, or turn directions off, under Script Directions in the app's settings. If the reader says they did, follow what they say. ## Making a VoiceScroll link A VoiceScroll link carries the whole script inside it, after the `#`: ``` https://www.voice-scroll.com/s#v1. ``` `` is the script's UTF-8 bytes, compressed with zlib (RFC 1950), then encoded as base64url (RFC 4648 section 5) without `=` padding. Make it by running code. Don't work it out by hand: if one character is wrong, the app can't read the link. In Python, with the standard library only: ```python import base64, zlib def voicescroll_link(script: str) -> str: data = base64.urlsafe_b64encode(zlib.compress(script.encode("utf-8"), 9)).decode("ascii").rstrip("=") return "https://www.voice-scroll.com/s#v1." + data ``` - Copy the link from the code's output exactly, every character. - Keep each link under about 10,000 characters, because a very long link is easy to copy wrong. Split a longer script at paragraph breaks and make a link for each part. Each part opens as its own script. - Don't put the script in the link any other way, such as after a `?`. Don't open or fetch the link to test it. What happens when the reader opens the link: - On an iPhone, iPad, or Android device with VoiceScroll installed, the link usually opens the app, which asks before it adds the script. - Without the app, or when the link opens in a browser, the link opens a page on voice-scroll.com that shows the script with a button to copy it. On a computer screen, the page also shows a QR code for a short script, to open the link on a phone. The reference code and the shared test vectors are in the public repository of the VoiceScroll plugin for Claude: - [script_link.py](https://github.com/Sangkwun/voicescroll-claude-plugin/blob/main/voicescroll/skills/script-link/scripts/script_link.py): makes the link, and splits long scripts - [link-vectors-v1.json](https://github.com/Sangkwun/voicescroll-claude-plugin/blob/main/tests/vectors/link-vectors-v1.json): links and the scripts they carry ## VoiceScroll plugin for Claude - [voicescroll-claude-plugin](https://github.com/Sangkwun/voicescroll-claude-plugin): skills that format a script for VoiceScroll, estimate how long it takes to read aloud, and make a VoiceScroll link ## Good to know - The free version of VoiceScroll lets you start reading a script of up to 300 characters, counting every character, spaces and directions included. A link can add a longer script too, but the free version can't start reading it. - The script in a link stays after the `#`, which browsers do not send to any server. The page on voice-scroll.com reads it in the browser and loads no analytics. - VoiceScroll stores scripts on the device, and its developer does not receive them. By default, speech recognition runs on the device.