Skip to content

UserGuide.md

Latest commit

 

History

History
407 lines (285 loc) · 21.1 KB

UserGuide.md

File metadata and controls

407 lines (285 loc) · 21.1 KB
Raw

BugNarrator User Guide

Structured counterpart: docs/user/user-manual.md

BugNarrator is a macOS menu bar app for narrated software testing sessions. It helps developers, testers, and product owners talk through a workflow, capture evidence, and turn that session into a transcript plus draft issues they can review or export.

BugNarrator intentionally runs as a single-instance app. If you open it again while it is already running, the existing instance should come forward and the second copy should exit. This avoids duplicate menu bar items and protects local session integrity.

Getting Help

What BugNarrator Is

BugNarrator is built for software walkthroughs and testing passes where you want to keep reviewing the target app instead of stopping to type notes.

It helps you:

  • record narrated testing sessions
  • create a transcript after the session ends
  • attach screenshots to the review session and turn them into timeline markers automatically
  • generate a review summary
  • extract draft bugs, UX issues, enhancements, and follow-up questions
  • export selected issues to GitHub Issues or Jira Cloud with experimental integrations
  • browse and clean up old sessions from a session library

Download And Installation

Install From The DMG

  1. Download the latest macOS release from GitHub Releases.
  2. Open the downloaded DMG.
  3. Drag BugNarrator.app into Applications.
  4. Launch BugNarrator from Applications.

BugNarrator releases are signed with a Developer ID Application certificate (Team ID 2R4WAH4R53), notarized by Apple, and stapled, so macOS will not show the "unidentified developer" warning. A first launch of any downloaded app still shows the standard one-time "downloaded from the Internet" confirmation. If macOS reports an unidentified developer, do not bypass it — verify the DMG against the published .sha256 checksum and report it.

macOS Requirements

  • macOS 14 or later
  • microphone permission for recording
  • Screen Recording permission if you want screenshot capture
  • your own AI provider configuration for transcription and issue extraction

First Run

  1. Launch BugNarrator and confirm the menu bar icon appears.
  2. Open Settings.
  3. Choose an AI provider.
  4. Enter the required API key or base URL for that provider, or leave the key blank for Local (Parakeet).
  5. Optionally click Validate Key or Validate Connection.
  6. Optionally assign global hotkeys for Start Recording, Stop Recording, and Capture Screenshot. They begin as Not Set until you choose them.
  7. Click Show Recording Controls.
  8. Start a session with Start Recording.

BugNarrator does not ship with built-in AI access or credits. OpenAI is the hosted default provider and requires your own API key. You can also select OpenAI-Compatible for an enterprise gateway or hosted compatible provider, Local-Compatible for local or self-hosted OpenAI-compatible endpoints, or Local (Parakeet) for transcription on this Mac through http://localhost:8422.

Local (Parakeet) does not use an API key and does not upload audio, but the local server must be installed and running before transcription. Install it by downloading bugnarrator-transcription-macos-arm64.dmg from the latest release, verifying the published checksum, opening the disk image, copying bugnarrator-transcription to a local folder, and running ./bugnarrator-transcription --preload in Terminal — it is signed and notarized, and needs no Python or source checkout. Settings > AI Engines has a direct download link. Leave that Terminal process running while you use Parakeet. Long recordings are processed in bounded local chunks and can take several minutes; BugNarrator waits for the active local inference instead of starting duplicate retries. It is transcription-only; review summary and issue extraction still require an OpenAI-compatible chat provider. Hosted provider usage may incur charges on that provider account.

Core Workflow

Start A Narrated Testing Session

Open the recording controls window from the menu bar, or use your configured start hotkey if you assigned one. Global hotkeys are optional and start as Not Set, while the recording controls window remains the main control surface. BugNarrator records in the background while you keep working in other apps.

The recording controls window includes:

  • Start Recording
  • Stop Recording
  • Capture Screenshot

You can keep using global hotkeys if you assign them in Settings, but the recording controls window is still the main control surface during a live review.

Stop A Session

When you finish, stop the session from the control window or a stop hotkey you explicitly assigned. BugNarrator then preserves the finished audio inside the session artifacts and, when your AI provider configuration is available, uploads the recorded audio to the configured provider and waits for the transcript result.

If the provider configuration is missing, invalid, or revoked at stop time, the session still stays in the library as a retryable item. Restore or replace the configuration in Settings, then open the session again and retry transcription from the preserved session.

Review The Session

After transcription completes, BugNarrator opens the session library so you can inspect the transcript timeline, screenshots, review summary, and extracted issues in one place.

The intended mental model is:

record → review → refine → export

Tester Narration Guide

Good sessions come from short, factual narration. BugNarrator can produce better transcripts, better bug summaries, cleaner repro steps, and better Codex or Claude follow-up prompts when the recording clearly states what you were testing, what you expected, and what actually happened. Unrelated chatter makes bug extraction harder.

Use this pattern during live testing:

  1. Start with environment context.
    • This is BugNarrator version [version] on macOS [version] on Apple Silicon. Installed from the DMG.
    • This is a fresh install.
    • This is an upgraded install over an older version.
  2. State the goal of the test.
    • I'm testing first-launch microphone and screen recording permissions.
    • I'm testing that starting and stopping a recording creates a transcript and saved screenshots at the right moments.
  3. Narrate each action as you do it.
    • I'm clicking Start Recording now.
    • I'm opening Settings.
    • I'm stopping the session now.
  4. State the expected behavior before or during the action.
    • I expected a macOS permission prompt here.
    • I expected the transcript to appear in the session library.
  5. State the actual behavior immediately when something is wrong.
    • The prompt did not appear.
    • The session stopped, but no transcript was created.
  6. Call out system state when it matters.
    • BugNarrator is not listed under Microphone in Privacy & Security.
    • The microphone toggle is already enabled.
    • I reopened BugNarrator after changing permissions.
    • I'm launching the app from Applications, not from Xcode.
  7. Mention timing or responsiveness when it is relevant.
    • I waited ten seconds and no prompt appeared.
    • The window lost focus after I clicked Start Recording.
    • The spinner stayed visible for about twenty seconds.
  8. Use screenshot capture when something looks wrong, and say why.
    • I'm taking a screenshot here because the permission prompt is missing.
    • I'm taking a screenshot here because this button is disabled unexpectedly.
  9. End with a one- or two-sentence outcome summary.
    • Ending test: recording started, but permissions were not granted correctly.
    • Ending test: transcript, screenshot, and summary all appeared as expected.

Word-For-Word Example

You can follow this script almost exactly:

  • This is BugNarrator version [version] on macOS [version] on Apple Silicon.
  • I'm testing first-launch microphone and screen recording permissions.
  • I'm clicking Start Recording now.
  • I expected a macOS permission prompt here.
  • The prompt did not appear.
  • BugNarrator is not listed under Microphone in Privacy & Security.
  • I'm taking a screenshot here because the prompt is missing.
  • Ending test: recording started, but permissions were not granted correctly.

Do This / Avoid This

Do this:

  • use short, factual sentences
  • say one action at a time
  • say what you expected and what actually happened
  • mention version, install method, permissions state, or app location when they matter
  • capture a screenshot when a visual problem or missing prompt is important

Avoid this:

  • unrelated chatter or side conversations
  • long theories while the problem is still happening
  • vague comments like it broke without describing what broke
  • mixing multiple issues into one sentence
  • waiting until the end of the session to describe the main failure

Core Features

Recording Narrated Testing Sessions

Recording is designed for real software review work. You can switch apps, click, type, and navigate normally while the microphone session continues in the background.

Transcript Generation

BugNarrator generates the transcript only after the session ends. It does not try to type live dictation into the active app.

Screenshot Capture

Use screenshot capture to save visual evidence during a review. On macOS 14 and later, BugNarrator uses ScreenCaptureKit plus a drag-selection overlay that works like a lightweight macOS capture tool. Press Capture Screenshot, drag across the area you want, release to save it, or press Esc to cancel. Each screenshot is attached to the current session, automatically creates a timeline moment at the same timestamp, and appears in the Screenshots tab with a thumbnail, timestamp, and linked context when available.

Review Summary

The summary view gives you a quick understanding of what the session covered before you read the full transcript.

Issue Extraction

Issue extraction creates reviewable draft issues in categories such as:

  • Bug
  • UX Issue
  • Enhancement
  • Question / Follow-up

Each extracted item keeps evidence from the transcript and should be reviewed before export.

Export Session Bundle

Use this when you want a portable local copy of the session. The bundle includes:

  • transcript.md
  • summary.md — the review summary and extracted issues, when issue extraction has run
  • screenshots/
  • manifest.json — what the bundle contains, including any referenced screenshot files that were no longer on disk at export time

Export To GitHub (Experimental)

After you configure your GitHub token, repository owner, and repository name in Settings, you can export selected extracted issues as GitHub Issues. This integration is currently experimental.

Export To Jira (Experimental)

After you configure your Jira Cloud URL, email, API token, project key, and issue type in Settings, you can export selected extracted issues as Jira issues. This integration is currently experimental.

Export Debug Bundle

Use Export Debug Bundle when you need a fuller support package for a GitHub issue. Hold Option while the menu bar window is open to reveal the action. The bundle includes:

  • system-info.json
  • app-version.txt
  • macos-version.txt
  • recent-log.txt
  • session-metadata.json

The bundle is local-only and intentionally excludes API keys, GitHub tokens, Jira tokens, and other raw credentials.

Session Library

The session library is the main place to revisit earlier work.

You can:

  • browse Today, Yesterday, Last 7 Days, Last 30 Days, or All Sessions
  • use a custom date range
  • search transcript text, titles, and summaries
  • sort by newest first or oldest first
  • open a detail pane with the transcript timeline, screenshots, summary, and extracted issues
  • delete sessions you no longer need

BugNarrator keeps lightweight session-library metadata in memory so bigger histories remain more responsive when you switch filters, search, sort, or jump between sessions quickly.

Treat the session library as an archive of review sessions rather than a plain transcript list. It is where you compare evidence, refine extracted issues, and decide what should be exported.

The right-hand review workspace is organized around clear tabs so you can move between:

  • Transcript
  • Screenshots
  • Extracted Issues
  • Review Summary

If issue extraction returns no draft issues, BugNarrator keeps the review flow on Summary instead of leaving you in an empty Extracted Issues view.

Older sessions that already contain standalone markers still render safely in the transcript timeline and exports.

Deleting a session removes it from the library immediately and also removes local screenshot files that BugNarrator manages for that session. Exported files outside the app are not deleted.

Support Development

BugNarrator is free to use. Donations are optional and separate from any hosted AI-provider costs.

Reporting A Bug

If you need help with a problem:

  1. Reproduce the issue if you can.
  2. Hold Option while the menu bar window is open and use Export Debug Bundle.
  3. Attach the bundle to your GitHub issue.
  4. If the problem affects a specific session, attach an exported session bundle or relevant screenshots too.

BugNarrator keeps diagnostics local until you explicitly export or copy them for support.

Troubleshooting

No Transcript Generated

  • confirm your AI provider configuration is valid in Settings
  • validate the key if needed
  • for hosted providers, confirm the Mac has network access
  • for Local (Parakeet), confirm the local transcription server is running and Check Server succeeds; long recordings can take several minutes to transcribe
  • retry with a short test recording to rule out an empty or corrupt audio file

Microphone Permission Problems

  • use BugNarrator's Open Microphone Settings button if it appears in the menu bar window
  • or open System Settings > Privacy & Security > Microphone
  • verify microphone permission is granted to BugNarrator
  • if BugNarrator says microphone access is restricted, also check device-management, parental-control, or workplace policy restrictions
  • if BugNarrator says audio capture is unavailable even though permission is enabled, check that an input device is connected and not already failing at the macOS level
  • if you are testing from Xcode or DerivedData, keep launching the same local app copy or switch to the signed DMG build; macOS may treat different local build paths as different apps for microphone approval
  • if repeated local builds are cluttering Launch Services or permission state, run ./scripts/cleanup_local_build_apps.sh from the repo root so only the installed Applications copy remains active
  • restart the app after changing permission settings if needed

BugNarrator Opened Twice

  • BugNarrator is designed to allow only one running instance
  • if you try to launch a second copy, the existing instance should become active and the new copy should exit
  • if you see two BugNarrator menu bar items at once, quit both copies and relaunch the copy in Applications

Provider Credential Missing

  • open Settings
  • choose an AI provider and enter your own provider credential or base URL when that provider requires one
  • for Local (Parakeet), confirm the local server is running instead of adding an API key
  • click Validate Key or Validate Connection if you want to check it before transcription or issue extraction
  • BugNarrator stores provider credentials in macOS Keychain when available
  • if a completed session could not be transcribed because the provider configuration was missing at stop time, keep the session and retry after restoring the configuration

Provider Credential Rejected Or Revoked

  • open Settings
  • replace the provider credential or fix the configured endpoint/model
  • click Validate Key or Validate Connection
  • try the preserved session again after the provider accepts the new configuration

Screenshots Not Appearing

  • confirm the session was actively recording when the screenshot was requested
  • after pressing Capture Screenshot, drag to select a real on-screen region before releasing the mouse
  • press Esc if you want to cancel the selection without saving anything; BugNarrator keeps recording and shows a lightweight cancellation message instead of a blocking error
  • use BugNarrator's Open Screen Recording Settings button if it appears in the menu bar window
  • or open System Settings > Privacy & Security > Screen & System Audio Recording
  • confirm Screen Recording permission is granted if macOS prompted for it
  • remember that this permission is only needed for screenshots; audio recording and transcription can still continue without it
  • remember that audio recording can continue even if screenshots are unavailable
  • try another screenshot to rule out a temporary storage failure

Export Errors

  • for GitHub, verify the token, repository owner, and repository name
  • for Jira, verify the base URL, email, API token, project key, and issue type
  • confirm your Mac still has network access

Backups And Moving To A New Mac

Your transcripts and the search index are encrypted on disk with a key that is tied to this Mac. Screenshots and recorded audio are stored as ordinary files and are not encrypted. If you restore from Time Machine, move with Migration Assistant, or lose the machine, the session files come back but the key does not — and the library cannot be read.

Before you migrate or retire a Mac, run Settings > Diagnostics & Privacy > Export Data. That writes your sessions as plain JSON that opens anywhere. Because it is plain, keep it somewhere you would be comfortable keeping the transcripts themselves.

Recording Consent

BugNarrator records your microphone by default. It can also record system audio — everything your Mac is playing, which on a call or in a meeting means other people's voices — and a mixed mode that captures both.

System audio capture is off unless you turn on the experimental toggle, pick a system-audio source, and tick the consent notice. Until you do all three, recording is refused.

Getting consent is your responsibility. Many jurisdictions — including California, Illinois, Washington, and much of the EU — require every participant to agree before a conversation is recorded, not just the person doing the recording. BugNarrator cannot ask them for you and does not try to. Tell people they are being recorded before you start.

Recorded audio follows the normal path: stored locally, and sent to your configured AI provider only when transcription runs. If that provider is Local (Parakeet), the audio never leaves your Mac.

Privacy

What stays local on your Mac:

  • saved session history
  • screenshot-driven timeline markers and older marker data from existing sessions
  • screenshot image files, unless you turn on screenshot upload (see below)
  • extracted issue drafts
  • exported session bundles

What is sent to the configured AI provider:

  • for hosted or compatible providers, recorded audio after you stop a session and request transcription
  • for Local (Parakeet), audio is processed by the local server on this Mac instead of uploaded
  • transcript context used for review summary or issue extraction when a chat-capable provider is selected
  • screenshot filenames and timestamps during issue extraction, so the model can tie your narration to a capture
  • the screenshot images themselves, but only when Settings > Diagnostics & Privacy > "Send screenshots to the AI provider" is on. It is off by default
  • when duplicate review runs, the titles and summaries of candidate issues fetched from your GitHub or Jira tracker

BugNarrator does not continuously stream live audio to any AI provider while you are still recording.

More Documentation

Running The Windows Suite From macOS

If you are running the Windows test suite locally from a macOS worktree, the normal dotnet restore step can fail to reach https://api.nuget.org/v3/index.json on this host even when curl against the same URL returns HTTP 200. This does not affect CI; it is a local-developer workaround only.

From a fresh worktree, restore from the already-populated local NuGet cache, then build without restoring again before invoking the PowerShell test harness:

dotnet restore windows/BugNarrator.Windows.sln --source "$HOME/.nuget/packages"
dotnet build windows/BugNarrator.Windows.sln -c Debug --no-restore
pwsh -File windows/scripts/test-windows.ps1 -Configuration Debug -NoBuild

If you need a release build, switch both commands to Release and keep -NoBuild on the PowerShell step so it reuses the offline-restored build output.