A bug report video developers can act on shows three things: where you started, the exact steps you took, and the moment it broke. Keep it under two minutes, make your clicks and keystrokes visible, and pair it with a short written report that lists your environment and what you expected to happen. Below is the workflow for recording a bug on a Mac, when a screenshot or GIF works better, how to attach the result to Jira, Linear or GitHub, and a template you can paste.
Before you hit record
A minute of setup saves a second take:
- Reproduce the bug once without recording. Write the steps down as you go. If you can't make it happen again, say so in the report; a video of the one time it did happen still helps.
- Start from a known state. Reload the page, open a fresh window or sign in again, so the video starts where the steps start.
- Use a test account and test data. Keep real customer names, emails and payment details out of it.
- Silence notifications. Turn on Do Not Disturb, so a private message doesn't pop up mid-recording.
- Pick the smallest area that shows the bug. One window, or just the region that matters, is easier to watch and leaks less.
What to show, and in which order
Developers watch a bug video looking for one thing: the gap between what you did and what should have happened. Make it easy to spot:
- The starting point. Hold for a second on the screen, page or window where the steps begin. If the account or role matters, show it.
- The steps, one at a time. Move at normal speed and pause briefly after each click, so the result is visible. Don't wave the pointer around while you think.
- The bug. Stay on it for two or three seconds. Point at it with the cursor, or say what's wrong.
- What you expected. Say it out loud or put it in the written report: "Saving should close the dialog. Instead, it spins forever."
- The evidence, if there is any. An error message, a console error or a failed request, shown at the end.
Keep it short
A short video is easier to watch to the end. A few rules:
- One bug per video. Two bugs in one video become one ticket that's hard to close.
- Aim for under two minutes. If the setup takes ten minutes, record only the last part and describe the setup in the written report.
- Trim dead time at the start and end. Keep anything that's part of the bug, though. If a slow load is the problem, leave the wait in.
- Narrate if you can. A short sentence per step ("now I'm clicking Export") is quicker to follow than text on screen.
In Smooth Recorder, a 3-second timer is one click, so the video doesn't open with you reaching for the menu. If you narrated, you can trim the video by deleting words from its transcript, and filler words go in one click.
Show clicks and keystrokes
Many bugs come down to input: a double-click, a shortcut, a key held down. Make it visible.
With the built-in recorder: press ⇧⌘5, click Options and choose Show Mouse Clicks. Apple's screen recording guide says this draws a black circle around the pointer when you click. For shortcuts, say the keys out loud or list them in the report.
With Smooth Recorder: press ⌥1, pick a window or an area, and press R. In Studio, every click gets a ripple, the cursor can be made bigger, and keystrokes can be shown on screen, so a ⌘Z that does nothing is visible in the video. It records your microphone and your Mac's own sound, which matters when the bug is a sound that plays twice or not at all. (For your options with the built-in tools, see how to screen record on Mac with audio.)
One note on automatic zooms: they're made for demos. In a bug report, the surrounding screen often matters, so remove any zoom that hides it. Every zoom can be edited or removed.
Include the environment details
The video shows what happened. The environment tells a developer where to look. Put these in the written report, not only on screen:
| Detail | Where to find it on a Mac |
|---|---|
| App version and build | The app's About window or Settings |
| macOS version | Apple menu > About This Mac |
| Browser and version | Chrome > About Google Chrome, Safari > About Safari, or Firefox > About Firefox |
| Account, role or plan | The account menu in the app |
| When it happened | Date, time and time zone, so it can be matched with server logs |
| Network | VPN, proxy or a slow connection, if any |
| Display | An external monitor or scaled resolution, for visual bugs |
Hide secrets before you share
Bug videos get pasted into trackers, chat threads and vendor tickets, so assume more people will see them than you expect.
- Crop before you record. Record one window or area instead of the whole screen, so your inbox, chat and password manager stay out of frame.
- Use test data. A test account with made-up names beats blurring things later.
- Close what you don't need. Extra browser tabs, bookmarks with client names and notification banners all leak.
- Redact screenshots. Smooth Recorder's screenshot editor has Smart Redact, which finds private details such as email addresses and phone numbers and covers them. Check the result, and blur or pixelate anything else by hand, such as an API key or a customer's name.
- Re-record rather than patch. If a password or token shows up in a video, it's quicker and safer to record again than to hunt down every frame.
Screenshot, GIF or video?
Not every bug report needs a screen recording. Pick the smallest format that shows the problem:
| Format | Best for | Watch out for |
|---|---|---|
| Screenshot | Static bugs: a broken layout, wrong text, an error message | Annotate it: an arrow or a numbered step saves a sentence |
| GIF | A few silent seconds: a hover state, a flicker, an animation glitch | No sound, and long GIFs get big fast |
| Video | Multi-step flows, timing problems, sound, narration | Keep it short, and export an MP4 |
Screenshots are the fastest to read. Smooth Recorder's editor has arrows, text, numbered steps and highlights, and a scrolling capture gets a whole long page into one image (see how to take a scrolling screenshot on Mac).
GIFs play inline, like an image, wherever the tracker shows images, so nobody has to press play. Press G in Smooth Recorder's capture overlay to record one directly, or see how to record a GIF on Mac.
Videos are for everything else. If the bug needs more than about ten seconds, or any sound, record a video.
Attach it to Jira, Linear or GitHub
All three let you drag a file into the description or a comment. The differences are in the limits:
- GitHub: drag the file into an issue or comment. GitHub takes MP4, MOV and WebM videos. As of September 2026, GitHub's docs list a 10 MB limit for images and GIFs, and for videos, 10 MB in repositories on free plans and 100 MB on paid plans.
- Jira Cloud: drag the file into the description or a comment. Atlassian's docs list a default of 1 GB per file, which admins can change, but Jira's Free plan has 2 GB of file storage in total, so long videos use it up quickly.
- Linear: drag a video into the issue description or a comment, and it plays right in the issue.
To make a video smaller, shorten it first, then lower the resolution and frame rate. Smooth Recorder exports MP4 or MOV from 480p up to the original size, at up to 60 fps, in H.264 or HEVC. For a bug report, 720p or 1080p at 30 fps is usually plenty, and H.264 plays in the most places.
Then write timestamps into the ticket, such as "0:12 click Save, 0:15 the spinner never stops," so nobody has to scrub. If your team would rather share links than files, see our Loom alternatives for Mac.
Browser bugs: capture console and network logs too
For a bug in a web app, the video shows the symptom, and the logs often show the cause. There are two ways to get them.
Jam. Jam is a Chrome extension built for bug reports. Along with a screenshot or a screen recording, it captures console logs, network requests and device details such as the browser, OS and viewport size, and packages it all into one link. Its Instant Replay can capture up to the last two minutes of activity, after the bug has already happened. You can send a report on to Jira, Linear or Slack. As of September 2026, Jam has a free plan, and its Team plan is $14 per creator a month, billed yearly.
Your browser's developer tools. In Chrome, open DevTools, right-click in the Console and choose Save as... to save the messages as a log file. In the Network panel, export a HAR file with the requests. Attach both to the ticket.
Which should you use? Jam is built for bugs inside a browser tab. For a native Mac app, a problem that crosses several apps, or anything outside the browser, record the screen and attach the app's own logs or crash report. On a Mac, the Console app (in Applications > Utilities) lists crash reports.
A bug report template to paste with your video
Copy this into the ticket, fill it in and attach the video:
Title: [Area] What breaks, and when
(e.g. "Invoices: Save spins forever after editing a line item")
Summary
One or two sentences on what goes wrong.
Steps to reproduce
1. Sign in as ... (role, plan, test account)
2. Go to ...
3. Click ...
4. See the problem
Expected result
What should happen.
Actual result
What happens instead, with the exact error text.
Video
bug-save-spinner.mp4 (0:45)
0:05 open the invoice
0:12 click Save
0:15 the spinner never stops
Environment
- App version and build:
- macOS version:
- Browser and version:
- Account, role or plan:
- Date, time and time zone:
- Network (VPN, proxy):
Frequency
Every time / sometimes (how often?) / once
Logs
Console log, HAR file or crash report, if you have them.
Impact and workaround
Who is blocked, and is there a way around it?
A short video, clear steps and a written-down environment add up to a report a developer can start on right away, without a round of follow-up questions.