Recording a coding tutorial on a Mac, end to end

Almost every unwatchable programming screencast fails in one of four specific ways, and none of them is about the presenter's knowledge. The code is too small to read on the device the viewer is holding. The screen changes and nobody knows which key caused it. The project does not build at the start of the video because the presenter's machine had state nobody else has. Or a notification slides in from the corner with somebody's real name attached.

All four are fixed before recording, not during and not in the edit. That is the useful way to think about a coding tutorial: it is a preparation task with a recording step at the end, not a recording task. What follows is that preparation, in the order it has to happen.

It assumes you are recording an editor and a terminal — the two windows that make programming content different from every other kind of screencast, because both are dense text and both are driven by keys nobody can see.

The single most common re-record is caused by state. Your machine has the dependency directory that installed six months ago, the database with the seed data you added by hand, the feature branch you forgot you were on, and the environment file you have never once had to think about. None of that exists for the viewer, and half of it will surface as a broken command three minutes into the take.

Fix it by making the starting point reproducible before you own the microphone.

You read code on a large display at arm's length, with a font size chosen for a working day. Your viewer reads it in a player window on a laptop, or full screen on a phone held closer than any monitor. The gap between those two is the difference between a tutorial people finish and one they close.

The correction is unsubtle. Raise the editor font until it feels absurd on your own screen, then record thirty seconds and watch it at the size the video will actually be delivered at. Judging this in the editor rather than in a test export is the mistake almost everyone makes once.

A notification in a tutorial is not just an interruption — it is often a person's name, a client's name, or a subject line you do not want on the internet. macOS has a switch for this: turning on the Do Not Disturb Focus from Control Center silences notifications, and Focus settings let you build a recording-specific Focus if you want finer control over what is allowed through.

Focus does not cover everything, though, and the rest is manual. Chat apps with unread badges in the Dock, a browser signed into your own account with your avatar in the corner, a bookmarks bar that lists your employer's internal tools, a calendar with the next meeting's title in the menu bar. Every one of those has ended up in somebody's published video.

The recorder is the least interesting decision here. Shift-Command-5 brings up the built-in macOS capture controls with Record Entire Screen, and QuickTime Player's New Screen Recording hands you the same controls. Either is enough for a tutorial; neither needs configuring beyond choosing the whole screen rather than a selected portion.

The part that does need a decision is the keyboard. A programming tutorial is mostly keyboard — jump to definition, run the last test, multi-cursor, the command palette, the shell. Every one of those is invisible in a recording, which leaves you narrating key names out loud and falling out of sync with your own hands.

A keystroke overlay removes that job. Show KeyPress draws each press as a keycap in an always-on-top window on your screen, so any recorder capturing the display captures the keycaps too. It records nothing itself, has no plugin for any recorder, and needs no configuration on the recorder's side — the only requirement is that you capture the display rather than a single application window, because the overlay is a separate window drawn above your editor rather than part of it.

A forty-minute single take means every mistake in minute thirty-eight costs you the whole thing, which is why single takes get worse as they go on — you start protecting the take instead of teaching. Recording in segments that map to your checkpoint commits inverts that. A fluffed segment costs three minutes.

It also lets you change the overlay's configuration between segments to suit what the segment is. ⌃⌥M switches between All Keys and Shortcuts Only from anywhere, and ⌃⌥= and ⌃⌥- step through the three size presets, so you are not opening a settings window mid-session and putting it in shot.

One practical detail: your own start and stop keystrokes end up in the recording, keycaps and all. Press ⌘⇧K to turn the visualization off just before you reach for the stop control, or leave a couple of seconds of silence at each end and trim them.

macOS handles the worst case for you. While Secure Input is active — a password field, an unlock dialog, a terminal with Secure Keyboard Entry — applications stop receiving key events at all. Show KeyPress clears the keyboard visualization for that whole period, so no keycap is drawn and nothing reaches the recording. What appears instead is a short banner reading Keyboard hidden — Secure Input, which reads as a deliberate pause rather than a glitch. If you would rather the take showed nothing at all there, turn off Show Status HUD in Settings under General before you record.

What macOS does not cover is anything it has no reason to treat as secret. An API key pasted into a plain text field, a token typed into a config file, an internal hostname — all of that is ordinary text as far as the system is concerned. ⌘⇧K is the master switch for those moments; it takes the cursor halo and the pet down with the keycaps, and a short status banner confirms the new state.

None of this is stored anywhere. Key events are processed on device, keystrokes and typed fragments are never persisted, and the app ships with no network entitlement at all — there is no log of a recording session to leak afterwards.