Docs

Using Speaking Glass

Install Speaking Glass, write a script, start a take and fix the common problems.

Install

Get the installer for your computer from the download section. Speaking Glass is free, and there is no account to create.

macOS

macOS 12 or later · Apple Silicon or Intel

Open the .dmg you downloaded.
Drag Speaking Glass onto the Applications folder.
Open Speaking Glass from Applications. It is signed and notarised, so it opens like any other app.

Once Speaking Glass is open, see First run.

Windows

Windows 11 · Intel or AMD 64‑bit (x86‑64) · Windows 10 should work, untested

Run the setup .exe you downloaded. It installs for your user account only.
When Windows shows Windows protected your PC, choose More info, then Run anyway.

Warning: Check where the installer came from

The installer isn’t code‑signed yet, so SmartScreen can’t tell who made it and stops it the first time. Choose Run anyway only for a file you downloaded from speakingglass.com or from Speaking Glass’s releases on GitHub.

Once Speaking Glass is open, see First run.

Linux

Ubuntu 22.04 or newer · Intel or AMD 64‑bit (x86‑64) · WebKitGTK 4.1

There are two downloads, and either one works. Their commands expect the file in your Downloads folder; if you saved it somewhere else, change ~/Downloads to that folder. If an older Speaking Glass download is there too, replace SpeakingGlass_*.AppImage or SpeakingGlass_*.deb with the new file’s full name.

AppImage

Runs without installing. In a terminal, make it executable, then run it:

Terminal

cd ~/Downloadschmod +x SpeakingGlass_*.AppImage./SpeakingGlass_*.AppImage

It updates itself: when Speaking Glass offers a new version, choose Install and Restart.

Debian package (.deb)

Installs with apt. In a terminal:

Terminal

cd ~/Downloadssudo apt install ./SpeakingGlass_*.deb

It can’t update itself, so when there is a new version Speaking Glass offers the download page instead. Install the new .deb the same way.

Once Speaking Glass is open, see First run.

First run

Open Speaking Glass. For your first take, use the sample script: it is short, and it tells you what to watch for as the text follows your voice.

Set up voice following first, from Before your first take on the right of the Welcome screen: download the speech model, then set up your microphone. Then choose Open the sample script. Opening a script leaves the Welcome screen; Help › Setup Assistant brings it back.

Microphone: Needed for voice following; Allow Speaking Glass to use it, choose it, and check that Speaking Glass hears you.
Teleprompter screen: Optional; Automatic opens takes on the display the Speaking Glass window is on. Choose display picks another, such as the screen under your prompter’s glass; see Set up a prompter.
Speech language: Needed for voice following; A one-time download of the speech model. Writing works without it.

Download the speech model

Start here, because the download runs while you set up the microphone. The English speech model is about 128 MB. It downloads only when you choose to install it, from the Welcome screen or Settings › Speech, and is checked against a SHA‑256 checksum built into the app.

In the Speech language row, choose Download.
Go on to set up your microphone while it downloads; you can keep writing, too. The row says Installed when the model is ready.

If the download stops, choose Try again to pick it up.

Set up your microphone

In the Microphone row, choose Set up microphone. Settings opens at Audio.
Choose Allow and choose microphone, and allow Speaking Glass if your system asks. macOS asks only once.
In Input device, choose the microphone you will speak into.
Say a few words. Input level should read Hearing you. If it reads Too quiet, move closer or turn the microphone up.
Once the speech model is installed, choose Test transcription.
Say “Speaking Glass is following my voice.” Your words appear as you speak, and the test reports Transcription is working with your microphone.
Close Settings to go back to the Welcome screen.

If a step doesn’t work, see Speaking Glass can’t use the microphone, or It isn’t following me if no words appear.

Read the sample script

On the Welcome screen, choose Open the sample script. It opens “Sample: read this aloud” in the editor.
Choose File › Practise, or press ⇧Shift⌘Command↩Return on macOS or Ctrl+Shift+Enter on Windows and Linux. It opens a rehearsal in a reading window.
Read it aloud at your own pace. The line you’re on stays near the middle, and the words ahead wait for you.

If the text keeps up with you, voice following works, and you’re ready for a real take: see Presenting. To start from your own words instead, File › New Script opens a blank one and File › Import Markdown… brings in one you already have; see Writing a script.

Writing a script

A script is a Markdown file. Write it the way you’ll say it, divide it with headings, and add cues: notes to yourself in square brackets, shown on the glass and skipped as you read. Insert › Cue and Insert › Part Break add them for you.

Spring launch.md

Markdown

[Take: Opening]

# A calm start

[Cue: look at the lens] Hello, and welcome back. [Beat]

Today I'll show you how the API{say="A P I"} copes with a **slow** connection.

[Take: Demo]

Here is the simplest case. [Pause] Watch the top line.

![The settings screen](settings.png)

:::silent
Cut to the screen recording here.
:::

Plain words are what you say. Square brackets hold directions for you, like [Cue: …] and [Pause], and [Take: …] starts a new part. Markdown marks like ** and :::silent notes are skipped as you read, and so are headings, by default.

Syntax at a glance

Script syntax
Syntax	What it does
`# Heading`	Starts a section. By default it is a quiet label on the glass, skipped as you read.
`[Cue: look at the lens]`	A note to you, on the glass where you wrote it. Skipped as you read.
`[Pause][Beat][Breathe]`	Short markers on the glass, skipped as you read. Any capitalisation works.
`[Take: Opening]`	Starts a part, which the Present menu can start on its own. Without part breaks, the biggest headings divide the script.
`API{say="A P I"}`	The glass shows API, and following listens for “A P I”. It applies only to the word before the brace. Put the spoken form in double quotes.
`:::silent Cut to the demo. :::`	A note shown quietly on the glass, set apart from the script, and skipped as you read.
`:::stage ![Chart](chart.png) :::`	Like a silent block, but a table, image, code block or diagram inside it stays in full during a take.
`bolditalic- list> quote`	Read like any other text.
`code`	Shown as code, skipped as you read.
`<!-- comment -->`	A note in the source that appears nowhere.

On the glass

In a teleprompter take, an image, table, code block or diagram is swapped for a one-line cue, so the glass keeps to your words: Image on screen, Refer to table, Demo code or Diagram on screen. A reading window and the editor’s preview show them in full.

Demo

Here is the simplest case. Pause Watch the top line.

Image on screen

Cut to the screen recording here.

The Demo part in a teleprompter take: the image is a one-line cue, and the silent note stays quiet.

To keep one in full during a take as well, put it inside a :::stage block.

In the app, Help › Script Syntax Reference has every form with an example.

When your script is ready, see Presenting.

Presenting

To start a take, choose Present in the editor’s toolbar, or press ⌘Command↩Return on macOS or Ctrl+Enter on Windows and Linux. It starts at the beginning of the script, in whichever of two ways you last chose; the line beside the button names it, with the display it will use.

Teleprompter: Fills the prompter display, above everything else, for reading off glass at a distance.; Mirrored if your rig needs it · Set up once
Reading window: Stays a window you can size and move, beside your webcam or a call, with wider lines for reading at a desk.; Never mirrored · No setup

To use the other, choose it under Present as in the Present menu: that starts a take straight away, from the beginning, and makes it the default. Settings › Prompter display and rigs sets the default too. During a take, ⌃Control⌘CommandF on macOS or F11 on Windows and Linux switches between them for that take only.

Set up a prompter

Do this once for each prompter display, with the display connected, in Settings › Prompter display and rigs. A reading window needs no setup.

Choose the display behind the glass. Identify displays shows each display’s number on the screen itself, to match the tiles. Left on Automatic, a take fills whichever display the Speaking Glass window is on.
If your prompter has beam‑splitter glass, and its own software doesn’t already flip the picture as Elgato Camera Hub can, turn on Horizontal mirror. Mirror in one place only, or the two flips cancel out.
If the text on the glass is upside down, turn on Vertical mirror.
Under This rig, set Viewing distance to how far you stand from the glass. Speaking Glass sizes the text for that distance on an Elgato Prompter or Prompter XL, or on any display that reports its own size. Any other display, an iPad included, uses a fixed size until you calibrate it.

Calibrate a rig

Optional, and the way to size text by distance on a display Speaking Glass can’t size by itself.

Choose Calibrate… under This rig. Its tests appear on the prompter, so answer from where you will stand.
Choose the preset closest to your rig, from the list below. It fills in the distance and mirroring, and every answer stays open to change.
Work through the rest in its three parts: identify the rig, fit the picture to the glass, then tune how the words read. Skip any step you don’t need.
Choose Apply this rig. It becomes the rig that display runs with, mirroring included.

Calibration presets
Preset	The arrangement
Reading at a desk Not mirrored	A window on your own screen, read directly, with no camera.
Desk and webcam Not mirrored	A monitor on your desk, with a separate webcam and no glass.
Elgato Prompter Mirrored	The 9-inch beam‑splitter unit, close to you.
Elgato Prompter XL Mirrored	The 15.6-inch beam‑splitter unit, usually further away.
Studio glass rig Mirrored	A larger monitor behind a beam‑splitter hood, further back than a desk unit.
iPad rig Not mirrored	An iPad as a second display over Sidecar, read directly rather than through glass.

Choose where to start

The arrow beside Present opens its menu. Under Start, each row says where it starts, in the script’s own words.

From beginning: The whole script, the same as Present.
From here: The sentence your cursor is in. Not offered while the cursor is in the first sentence.
From last ending: The sentence where your last take or practice of this script stopped. Not offered until there has been one.
Each part: By number and name, such as Part 2 · Demo, from its first words. Offered once the script has two parts, which come from part breaks or, without any, the biggest headings; see Writing a script. Up to twelve are listed: for a later part, click its first words and choose From here.

Teleprompter · Elgato Prompter Present

The Present menu over the example script, with the cursor in its Demo part and the last take stopped in its Opening.

Practise

A practice is a rehearsal. Choose Practise in the Present menu, or press ⇧Shift⌘Command↩Return on macOS or Ctrl+Shift+Enter on Windows and Linux.

It opens from the beginning, always in a reading window, and voice following runs just as it does in a take; tables, images and code stay in full. When you choose Finish practice, the editor comes back with nothing reported, where a take ends with its Take complete summary.

When the take opens

Start speaking. There is no countdown: a take listens from the moment it opens, and the script follows from your first words. If something isn’t ready, such as no speech model, a microphone Speaking Glass can’t use or a prompter display that isn’t connected, a Before this take sheet says so first, with Start anyway.

For what you see from there, and every key you can press, see During a take.

During a take

As you read, the script moves to keep your line between two markers in the margins. The text moves only when Speaking Glass is sure where you are. When it isn’t, it holds. For every key you can press, see Keyboard shortcuts.

Following. Your line sits between the markers. The words behind you dim; the words ahead stay bright.

Holding. The markers go hollow and the text stays put. After a few seconds the same mark appears in the corner.

It holds while you ad-lib, skip or stumble, and carries on once your words match the script again. Following can be wrong, so it is built to wait for you rather than guess ahead.

Finding your place again

Keep reading. It picks you up when your words match the script, and if you start a sentence over, it follows you back.
Move the script to your line. ↑Up arrowor↓Down arrow moves it a line and ⌥Option←Left arrowor⌥Option→Right arrow a sentence (Alt on Windows and Linux), or scroll. It follows on from the line between the markers.
Open the Take controls from the tab at the top right of the window. Set my place tells Speaking Glass you are somewhere on screen: it looks again at the lines in view and waits until it hears you. Previous sentence and Next sentence move it one sentence. The take’s keys wait while the panel is open, so press Esc to close it before you use them.
If it keeps losing you, press A for auto-scroll. The script rolls at a steady pace with voice following off, [Left bracketor]Right bracket set the pace, and A hands it back to your voice. To find out why, see It isn’t following me.

Take controls

1:24

Voice ready Mic live

Holding your place

The text stays put until the words match the script again.

Hold text Set my place Previous sentence Next sentence

Why did it move?

End take ⌘.

Open the Take controls from the tab at the top right of the window to set your place or move a sentence at a time.

To keep the text still while you ad-lib, choose Hold text. It becomes Follow voice; choose that to carry on.

In a reading window, if your words match a part of the script that is off screen, Speaking Glass doesn’t jump there. A Possible match card offers Read from there or Ignore.

Keyboard shortcuts

Keyboard shortcuts during a take
Action	macOS	Windows and Linux
Moving through the script
Move the script one line	`↑Up arrow`or`↓Down arrow`	`↑Up arrow`or`↓Down arrow`
Move the script about a screen	`Page Up`or`Page Down`	`Page Up`or`Page Down`
Previous / next sentence	`⌥Option←Left arrow`or`⌥Option→Right arrow`	`Alt+←Left arrow`or`Alt+→Right arrow`
Previous / next section	`⌥Option↑Up arrow`or`⌥Option↓Down arrow`	`Alt+↑Up arrow`or`Alt+↓Down arrow`
Go to the start or end of the script	`Home`or`End`	`Home`or`End`
Pausing and pace
Start / Pause / Resume	`Space`	`Space`
Hard pause Turns the microphone off	`⇧Shift⌘CommandSpace`	`Ctrl+Shift+Space`
Auto-scroll on / off	`A`	`A`
Auto-scroll slower / faster	`[Left bracket`or`]Right bracket`	`[Left bracket`or`]Right bracket`
Blank stage	`B`	`B`
The stage
Larger / smaller stage text Unless the display sizes its own text	`⌘Command+Plus`or`⌘Command−Minus`	`Ctrl++Plus`or`Ctrl+−Minus`
Mirror stage	`⇧Shift⌘CommandM`	`Ctrl+Shift+M`
Switch between reading window and teleprompter	`⌃Control⌘CommandF`	`F11`
Ending the take
End take	`⌘Command.Full stop`	`Ctrl+.Full stop`
End the take and close the stage	`Esc`then`Esc`	`Esc`then`Esc`

Your files and updates

Every script is a Markdown file on your own disk, in Speaking Glass’s data folder. There is no account and no copy on a server, so backing up is up to you. To find the folder, see Where your data lives.

Restore an earlier version

Speaking Glass saves a revision of a script every few minutes while you write, before each take, and when the file changes outside Speaking Glass.

In the editor, choose Revision History… from the Script actions menu (⋯).
Choose a revision to read it, then Restore this version.

Your current text is saved as a revision first, so you can undo a restore the same way.

Back up and restore

Settings › Data, privacy & updates has both.

Back up everything

Choose Export all data and pick a folder. The export holds every script with its revisions and images, your settings and calibrated rigs, and your take history, with a checksum for each file. It leaves out the speech model, which you can download again in Speaking Glass.

If the export folder’s name ends in INCOMPLETE, it didn’t finish. Don’t use it as a backup.

Restore a backup

Restoring replaces your current scripts, settings and take history with the export’s. To keep what you have now, export it first.

Choose Restore from export… and pick the export folder. Speaking Glass checks every file against its checksum and changes nothing yet.
Quit and reopen Speaking Glass. The export is restored as it opens.

To move to a new computer, copy the export folder to it, install Speaking Glass and restore the export there.

Where your data lives

Your scripts with their revisions and images, your settings and the speech model are all in one folder:

macOS: ~/Library/Application Support/com.candidcue.app; In Finder, press ⇧Shift⌘CommandG, paste the path and press Return.
Windows: %APPDATA%\com.candidcue.app; In File Explorer, press Ctrl+L, paste the path and press Enter.
Linux: ~/.local/share/com.candidcue.app; In your file manager, press Ctrl+L, paste the path and press Enter.

Updates

Speaking Glass checks updates.speakingglass.com for a newer version shortly after it opens and every six hours, unless you turn that off, and installs one only when you choose to, never during a take.

When there is one, a notice in the corner of the window offers Install and Restart or Later. Installing restarts Speaking Glass; your scripts, settings and speech model stay as they are, and every update is signed and verified before it installs. Later puts the notice away until you next open Speaking Glass.

A Linux .deb can’t replace itself, so there the notice offers Download instead. Install the new .deb the same way as the first; see Debian package (.deb).

To stop the automatic check, turn off Check for updates automatically in Settings › Data, privacy & updates. Help › Check for Updates… checks whenever you ask, whatever that switch says. How updates work.

Note: Your voice stays here

Speech recognition and following run on your computer. Speaking Glass does not upload your microphone audio or your scripts. The network inventory lists every network path in the app.

Troubleshooting

Speaking Glass can’t use the microphone
The speech model is damaged or didn’t download
Takes open on the wrong display
It isn’t following me
Getting help

Speaking Glass can’t use the microphone

Settings › Audio says Microphone access is off, or a take says Microphone not allowed. The buttons below sit beside that message, and in the Take controls during a take.

macOS

Choose Open System Settings.
In Privacy & Security › Microphone, turn on Speaking Glass.
Back in Speaking Glass, choose Try again.

If Speaking Glass was already on, quit Speaking Glass and open it again.

Windows

Choose Open Windows Settings.
In Privacy & security › Microphone, turn on Let apps access your microphone and Let desktop apps access your microphone.
Back in Speaking Glass, choose Try again.

If both were already on, the microphone may be unplugged or in use by another app. Check it in Windows Settings › System › Sound.

Linux

Allow Speaking Glass to use the microphone in your system settings.
Back in Speaking Glass, choose Try again.

If it was already allowed, the microphone may be unplugged or in use by another app.

If it still doesn’t work, see Getting help.

The speech model is damaged or didn’t download

If Settings › Speech says Damaged, choose Download again there. If it says The download did not finish, check your connection and choose Try again; it picks up where it stopped.

You can keep writing in the meantime. Only voice following needs the model.

If it still doesn’t work, see Getting help.

Takes open on the wrong display

When the display you chose for the prompter isn’t connected, new takes open on the display the Speaking Glass window is on. Settings › Prompter display and rigs says Your chosen display is not connected.

Connect the display and turn it on.
Choose Check again beside that message.

Or choose another display in the same place. Identify displays puts a number on each screen.

If it still doesn’t work, see Getting help.

It isn’t following me

Voice following works in English only. If you’re speaking English, check these in order:

If the Take controls show Follow voice, choose it. The text was on hold.
In Settings › Speech, make sure the speech model is installed. If it’s damaged or didn’t download, see The speech model is damaged or didn’t download.
In Settings › Audio, speak and watch Input level. If it doesn’t move, choose another input there, or see Speaking Glass can’t use the microphone.
Choose Test transcription there and say a sentence. Your words should appear as text.

Meanwhile, you can move the script yourself: ↑Up arrowor↓Down arrow moves it a line, and A rolls it at a steady pace with voice following off, until you press A again. In the Take controls, Set my place tells Speaking Glass you are somewhere on screen: it looks again at the lines in view and waits until it hears you. The take’s keys wait while the panel is open, so press Esc to close it before you use them.

Getting help

Report a problem on GitHub. Say what happened, what you expected and what you tried, with your Speaking Glass version and system. Settings › Data, privacy & updates lists both under Diagnostics. Outside a take, Help › Report a Problem in Speaking Glass opens the same form.

If you’re asked for a support bundle, export one. Support bundles are created only when you ask for one, and go only where you send them.

Choose Help › Export Support Bundle… in Speaking Glass, or Export support bundle under Diagnostics, and pick where to save it. Speaking Glass saves a folder of diagnostic state, versions, timings, recovery reports and logs.
Open the folder and read what’s in it.

Warning: Anything you attach to an issue is public

A bundle is designed to leave out your scripts, transcripts and microphone audio, and its logs have home folders and web addresses removed. Speaking Glass can’t recognise prose, though, so a log line could still hold something you wrote.
Compress the folder into a .zip file and drag it into the issue.