How to Record a Bug Report Video on Mac

To record a bug report video on a Mac, start from a known state, record only the window or area where the bug happens, and say what you expected and what actually happened as you go. Export a short MP4 and attach it to the ticket next to written repro steps. The built-in Screenshot toolbar (⇧⌘5, Command-Shift-5) is enough for many bugs. Screen Bolt adds single-window recording, an export that skips the editor, and on-device blurring of emails, phone numbers and your own keywords when customer data is on screen.

What a useful bug report video shows

A developer watching your video wants to reproduce the bug on their own machine. Everything in the recording should serve that goal:

• The starting state. Which page or screen you begin on, which account type you're logged in with, and what data is already there.
• Every step at normal speed. No jumping ahead, no unexplained clicks. If a step uses a keyboard shortcut, say it out loud. Viewers can't see which keys you pressed.
• The failure, held on screen. When the bug appears, stop moving the mouse for a couple of seconds so the error message, glitch or wrong value is readable.
• Expected vs actual, spoken. "I expected the draft to save. Instead I get this error." One sentence each.
• The environment. App version, macOS version, and browser if it's a web app. You can show the app's About window at the start, but writing it in the ticket is faster to read.

Keep the video as short as the repro allows. If reaching the bug takes a long setup, write those setup steps in the ticket and start the recording from a state the ticket describes.

The video doesn't replace the written report. Text can be searched and skimmed; a video can't. A template you can paste:

**Summary:** <one line: what breaks, where>

**Environment:** <app + version>, <browser + version if web>, macOS <version>, <account type / test account>

**Steps to reproduce:**
1. <starting page or state>
2. <action>
3. <action>

**Expected:** <what should happen>
**Actual:** <what happens instead, exact error text>

**Video:** <file name> (bug appears at <m:ss>)
**Happens every time?** <yes / sometimes / once>

Before you record

A few minutes of setup avoids a re-record:

• Use a test account and test data. This is the safest way to keep customer information out of the video in the first place.
• Turn on a Focus mode (Control Center ▸ Focus) so notifications don't pop up mid-recording.
• Close unrelated tabs and windows, especially anything showing chat, email or credentials.
• Reproduce the bug once without recording so you know the exact path.

There's a longer checklist in how to prepare your Mac for a clean screen recording.

Recording the repro steps

With the built-in Screenshot toolbar

1. Press ⇧⌘5.
2. Click Record Selected Portion and drag the frame over the app, or click Record Entire Screen.
3. Open Options and pick your microphone if you want to narrate.
4. In Options, turn on Show Mouse Clicks so viewers can see where you click.
5. Click Record.
6. Reproduce the bug, then click the stop button in the menu bar or press ⌃⌘Esc (Control-Command-Escape).

The recording is saved as a .mov file, on the Desktop unless you changed the location in Options. To cut dead time at the start or end, open it in QuickTime Player and choose Edit ▸ Trim (⌘T).

The built-in toolbar can't record a single window on its own, can't capture your Mac's system audio (a problem for audio bugs; see how to record internal audio on Mac), and can't blur anything. If none of those matter for this bug, it's all you need.

With Screen Bolt

Screen Bolt's Window mode records one window by itself, even if another window covers it, so the video stays on the app with the bug. More detail is in how to record a single window on Mac.

1. In the recording bar, click Window.
2. In Select Window to Record, click the window with the bug and confirm with Record Window (or press Return).
3. Click Mic and choose your microphone if you want to narrate. For an audio bug, click Audio and choose Record system audio from all apps.
4. Click the red record button.
5. Reproduce the bug. Use Pause if you need to look something up; the pause gap is removed from the recording.
6. Click Stop.

If you fumble a step, click Discard and restart in the recording bar. It deletes the take and returns you to setup without creating a project.

The first time you record, macOS asks for Screen Recording permission. On macOS 14 you have to quit and reopen Screen Bolt after granting it before recording works. The troubleshooting page covers other permission problems. Pick Area or Display instead of Window when:

• The bug involves a menu, popover or system dialog that may open as a separate window and so may not appear in a single-window recording.
• The flow moves between two apps, for example a sign-in that opens a browser.

There are menu shortcuts too. ⌥⌘3 (Option-Command-3) records the first display right away; ⌥⌘4 and ⌥⌘5 open the window picker or area selection and start recording once you confirm. They only work while Screen Bolt is the active app, not as global hotkeys.

Quick export: skip the editor

For most bug reports you don't need to edit anything. Screen Bolt can render the file as soon as you stop recording.

1. In the Record menu, choose Export to file (skip editor). (The same setting is in Settings ▸ Recording ▸ After recording ▸ Export to file.)
2. Open Settings ▸ Quick export and set Format, Frame rate, Resolution and Compression once. See the table in "Keeping bug videos small" below.
3. Record as usual. When you stop, Screen Bolt renders the video, reveals the file in Finder and returns to the recording bar.

The file is saved inside the project package (Screen Bolt <date> at <time>.screenbolt) in your projects folder, ~/Screen Bolt Projects by default. Finder shows the package as a single file. Drag the exported video from the Finder window that opens, or later right-click the project and choose Show Package Contents to get at it.

Things to know about quick export:

• Auto zoom is applied. By default, Screen Bolt turns your mouse clicks into zooms. That helps viewers follow small controls, but it can crop out a toast or error that appears elsewhere on screen. If the whole window needs to stay visible, turn off Automatically create zooms in the Record menu before you record.
• Editor blurs aren't added. Auto-Detect Sensitive Text and blur regions are editor tools, so a quick export shows whatever was on screen (apart from any live blur zones you drew before recording, described below).
• No background or padding is added. For a bug report that's what you want.
• Only the first camera is included, if you recorded one.
• Editor exports change these settings. Every export from the editor saves its format and quality as the new Quick export defaults, so check Settings ▸ Quick export if your bug videos suddenly come out in a different format or size.
• Free-version limits apply, and a blocked export fails without a message. The free version exports up to 3 minutes at 720p with a "Made with Screen Bolt" watermark in the bottom-right corner. If a free recording runs past 3 minutes, no file appears. Keep repro takes short.

If you realize after a quick export that the video needs blurring, press ⌥⌘Z (File ▸ Open last project) or double-click the .screenbolt project to open it in the editor.

Blurring customer data

Sometimes a bug only happens with a real customer's data. In that case, don't use quick export. Open the recording in the editor and blur before you export.

1. Set After recording back to Open editor before you record (or open an existing project with ⌥⌘Z).
2. Trim and cut first. Blur regions found by the scan don't shift when you later cut, reorder clips or change speed, so make those edits before scanning.
3. Open the Effects panel and go to Blur / Privacy ▸ Auto-Detect Sensitive Text.
4. Turn on Also detect phone numbers if needed. In Custom keywords (comma separated), add the customer's name, company domain, account ID or anything else specific to them. Matching ignores upper and lower case.
5. Start the scan. It runs on your Mac with Apple's Vision text recognition; nothing is uploaded. Email addresses are always included.
6. When it reports how many regions were added, play through the video and review every blur on the Blur track. Detected blurs follow the text through zooms and scrolling, and each has a Padding slider if the edges of the text show.
7. For anything the scan doesn't look for (street addresses, avatars, card details, tokens that aren't in your keywords), press B to add a blur region at the playhead. Choose a Style (Gaussian, Pixelate or Solid Color), then adjust Blur Intensity, Region and Duration.
8. Click Export in the toolbar. Mistakes that leak data even after blurring:

• The toolbar's Share button sends the raw recording, the unedited recording.mov without your blurs. Share the exported file instead.
• Don't send the .screenbolt project. It contains the unblurred recording, and project.json stores the matched text as each auto-blur's label. Once the ticket is filed, you can remove the project with the toolbar's Delete Recording button, which moves it to the Trash. Empty the Trash to delete it for good.
• Your keywords are saved in Screen Bolt's preferences between launches. Clear the field when you're done if the names themselves are sensitive.

You can also draw blur zones before recording with the Blur button in the recording bar. These are frosted windows on your screen, so they're useful for hiding a fixed sidebar or notification area. They aren't secure redaction, and they have limits: they stay at fixed screen positions (they don't follow scrolling or a moving window), they only appear on the main display, they don't blur a Window-mode recording, and you can't click through them. If the bug requires clicking in that area, use editor blurs instead. More approaches are in our post on hiding sensitive information in screen recordings.

Attaching to Jira, Linear or GitHub

Jira, Linear and GitHub all let you drag a video file into an issue or comment.

• Use MP4. The export sheet describes MP4 (H.264) as "Plays everywhere", which matters when teammates open the ticket in different browsers and operating systems. Screen Bolt's MOV export uses HEVC, which gives smaller files, but some browsers and players may not play it inline. MP4 vs MOV explains the difference.
• Rename the file to match the ticket, for example BUG-1234-save-draft.mp4. Exports are named Screen Bolt <date> at <time>, which is hard to find later.
• Write the timestamp where the bug appears in the ticket text, so nobody has to scrub through the setup.
• Check the size limit. Each tracker caps attachment size, and the cap can depend on your plan. If an upload is rejected, re-export smaller (next section) rather than splitting the repro.
• GIF for very short repros. A GIF plays inline anywhere images do, which is handy in GitHub comments. In Screen Bolt, GIF export is Pro only, silent and about 10 frames per second. Clips over 15 seconds ask for confirmation and clips over 60 seconds are refused, measured against the full recording rather than the trimmed result. At 10 frames per second a glitch that lasts a single frame can disappear, so use MP4 for rendering and animation bugs.

Screen Bolt makes a local file only. It has no share links or cloud upload, so the tracker's own attachment is where the video lives.

Keeping bug videos small

Smaller files upload faster and fit tracker limits. These settings matter most:

The Export sheet shows an estimated size before you export ("estimate ±30%"), so you can check it against the tracker's limit first. For a rough figure before recording, use the video file size calculator. Full export options are on the export help page.

Trimming dead time helps more than any setting. One catch in the free version: the export sheet checks the 3-minute cap against the full recording, not the trimmed result, so a 4-minute take trimmed to 1 minute is still refused. Stop recording soon after the bug appears.

With the built-in tools, open the .mov in QuickTime Player and choose File ▸ Export As ▸ 720p or 480p to shrink it.

Common mistakes

• Starting mid-flow. Without the starting state, the developer can't reproduce the bug. Begin from a page anyone on the team can reach, or describe the starting state in the ticket.
• Moving on too fast. The error appears for half a second and the video ends. Hold still on the failure.
• Relying on the video alone. Write the steps too, so the ticket makes sense without pressing play.
• Recording real customer data when test data would do. Blurring is a fallback, not the plan.
• Quitting Screen Bolt while recording. Quitting during an active recording doesn't finalize the file. Click Stop first.
• Pressing shortcuts silently. There's no on-screen key display, so say the shortcut, or add a text overlay in the editor with the T key.

If you also record code walkthroughs for pull requests, see how to record a code review video. For videos that explain fixed behavior to customers, see how-to videos for your help center. Screen Bolt's free version is on the download page, and the free and Pro limits are in the pricing table.