Treat audio like a page

When I read along while something is read to me, I want to move through the voice the way my eyes move through a page: skim what I know, slow down for the hard part, go back and hear it again. Here's how the read-along keys in Voice Pipes let me do that.

Give me a page and I never read it straight through at one speed. My eyes skim the paragraph I already know, slow down on the sentence that carries the idea, jump back two lines when something didn’t land, and glance ahead to see where it’s going. Nobody taught me that. It’s just what reading is.

Listening has always felt different to me. A voice reads at its pace, in its order, from the first word to the last. If a sentence slipped past, getting it back meant scrubbing a timeline and hoping. So I kept having to choose: read it myself, or sit back and let it wash over me.

What I actually want is both at once, with the voice as easy to steer as my eyes.

Two senses, one pace

I like reading and listening at the same time. With the words in front of me and a voice in my ear, I drift less, and more of it stays with me. That’s my experience, not a law of learning; plenty of people prefer one or the other, and that’s fine.

But the moment I do both, the voice’s pace becomes the problem. Text isn’t evenly dense. The setup paragraph of an idea I’ve met a dozen times goes by too slowly; the one sentence that does the real work goes by too fast. How quickly I can take something in depends on what it says and on what I already know, and both change from sentence to sentence.

A page lets me match my pace to the text at every moment, and going back costs nothing. That’s what I wanted from audio: not one speed for the whole thing, but steering as cheap as moving my eyes. Fast where it’s familiar, slow where it’s dense, and a replay that takes one key, not a hunt.

The page, in the HUD

In Read it to me I wrote about the read-along card: while anything is read aloud, the HUD at the bottom of the screen can open a card above it with the whole text, one sentence per line. That’s the page. The sentence being read has a lavender bar, the ones already read are dimmed, and a thin underline runs under the word being spoken (exact with the macOS voices, closely estimated with the others).

What’s new since then is that my hands can steer it without reaching for the mouse. When the HUD has the keyboard, it says so: KEYS ON at the foot of the card, with the keys, and a small KEYS mark on the tag.

The keys

The defaults are Vim’s, because that’s where my fingers already rest, with the arrows and minus and equals for everyone else:

A few things worth knowing, because they’re how it actually behaves:

• The step is a sentence. I think of text in blocks, but the app thinks in sentences: j and k move exactly one, the same lines the card shows. A paragraph shows up as a gap in the card, but there’s no paragraph jump. To skip a paragraph, press j a few times, or click the sentence you want.
• k goes to the start of the sentence before the one being read. So when the voice has just moved on and the last sentence didn’t land, one k brings it back. To hear the sentence you’re in from its start, press k then j.
• A jump always carries on reading, even from a pause. At the ends, j on the last sentence starts it again, and so does k on the first.
• Speed runs from 0.6× to 2×, in tenths, and only for this reading; the track keeps its own speed for next time.
• Space pauses and resumes from the same spot. While the voice is still loading, before the first sound, there’s nothing to pause yet.
• Esc stops the reading and the HUD fades away. If the card was open, it opens again with the next reading.

The keys move the voice, not a selection. Nothing in the card gets selected or copied, and the app you started the reading from never sees these keys.

One read, scene by scene

Here’s how it feels on something I half know. I select a short explainer of Bloom filters in my browser, press ⌥R (the Read aloud track’s default hotkey), and read along with the card open.

That’s the whole idea: a handful of keys, and the voice keeps the pace I’d keep with my eyes.

Who has the keyboard

A HUD that takes your keys is only welcome if it gives them back, so this part had to be precise. Voice Pipes never comes to the front. The HUD is a small panel that can take the keyboard without making Voice Pipes the active app: the app you’re in stays in front, and when the HUD lets go, your typing goes straight back to it.

When it takes the keys is up to you, in Setup → Reading → Keyboard while reading:

• Always (the default since 1.8.1): the moment something starts being read. Great when an agent reads to you and your hands are already on the keyboard.
• Point or click: when you move the pointer onto the HUD, or click it. Move away and the keys are yours again (unless you clicked it; then click elsewhere). The HUD appearing under a resting pointer doesn’t count.
• Click: only when you click the HUD. Nothing is taken until you ask; click anywhere else to give them back.
• Never: no keys at all. The HUD’s buttons still work with the mouse, and so do any shortcuts you’ve set to work anywhere (more on those below).

The fine print, in plain words:

• While the HUD has the keyboard, it really has it. Keys that aren’t one of its own are held back rather than typed into your app (and it doesn’t beep at you). That’s the trade with Always: to type, click your app, and the keys go straight back.
• Any ⌘ shortcut hands the keyboard back. The HUD lets go instead of acting on it, so a ⌘ press never reaches Voice Pipes’ own menu (⌘Q included). That press is spent on letting go; press it again for your app.
• The mouse is never taken. Only while something is being read does the HUD’s own patch at the bottom of the screen answer clicks (its buttons and the sentences in the card). Everywhere else, and the rest of the time, clicks go where they always do.
• Clicking away keeps reading by default. Set When I click away to Stop and clicking elsewhere ends the reading too.
• No extra permission. The HUD sees keys only while it is the window they go to. The anywhere shortcuts are ordinary system hotkeys, switched on only while something is being read.
• When the HUD has the keys, the tag shows KEYS and the card’s foot KEYS ON. No mark, no keys taken.

Make the keys yours

Vim keys suit me; they don’t have to suit you. Every action’s keys are in the same place, under Keys while the HUD has the keyboard: each key is a chip with its ×, + key adds another, and Reset to defaults brings back Esc, Space, j/k, h/l and g/G. An action can have several keys, or none. Plain letters are fine here, because they only work while the HUD has the keyboard.

Two keys behave differently. Plain Esc can’t be recorded with + key, because Esc cancels recording; it comes back with Reset to defaults or in the config file. And anything with ⌘ always hands the keyboard back rather than doing an action, so leave ⌘ out of these.

Below that, Anywhere while reading is for shortcuts that work in any app, without the HUD having the keyboard, but only while something is being read. None are set until you add one with + Add shortcut, and each needs ⌃, ⌥ or ⌘, so it never takes a key from your typing. ⌃⌥→ for faster, say, works even in Never mode.

It’s all in config.toml too, under [settings.reading], and the app picks up a saved change within a second:

[settings.reading]
take_keys = "click"           # always | hover (point or click) | click | never
click_away = "keep-reading"   # keep-reading | stop
faster = ["l", "equal", "period"]

[settings.reading.global]     # work in any app, only while something is read
faster = "control+option+right"
slower = "control+option+left"

Or from a terminal (vp reading key replaces that action’s keys):

vp reading keys click
vp reading key faster l period
vp reading shortcut faster control+option+right

And if you’d rather not touch either, tell your agent “don’t take my keys”, and its skill changes the setting for you. The config guide covers the file, and the CLI reference the other reading commands, like vp speed from another shell.

Try it

Steering from the keyboard arrived in 1.7.3, and 1.8.1 made Always the default. If you already have Voice Pipes, update from the menu bar panel. If you don’t, one line installs it:

curl -fsSL https://github.com/brancusi/voice-tools-releases/releases/latest/download/install.sh | bash

Then select something you half know, press ⌥R, open the card from the tag, and read along. Skim with l, slow down with h, and when a sentence slips by, k. A page never asked me to read at its speed. Now the voice doesn’t either.