# Recording a whinge

The whole loop is talk, draw, clear. Everything here is about doing that without stopping to click
around.

## Starting

Any of these starts one:

| From | How |
| --- | --- |
| A terminal | `whinge start`, with optional `--output DIR` |
| The menu bar | **Start Whinge** |
| Anything that opens URLs | `open whinge://start` |

## Listening

Whinge doesn't record straight away. Its toolbar comes up **listening**, with a meter that moves
when the microphone hears you.

Say **"let's whinge"** (or **"it's whinging time"**) and it starts: a chime, and the toolbar turns
into a timer. Nothing is recorded before that, so hearing the chime means the microphone and speech
recognition both work. Speech recognition has hardly ever met the word "whinge", so it's generous
about what it counts: “let's twinge” and “let's binge” both work. Choose the enabled phrases and
microphone, or test what Whinge hears, in [Settings → Speech](/docs/settings#speech).

Press record on the toolbar to start without saying it, or ✕ if you've changed your mind.

Under the title, the toolbar shows what speech recognition is making of what it hears, for a few
seconds at a time. If it isn't starting, that's where to look: it may be hearing “let's binge” or
nothing at all. Each thing it hears, and why it wasn't the phrase, also goes in the
[debug log](#the-debug-log).

## While it's recording

Whinge records every display and your microphone, and notes which windows were where.

The **privacy screen** covers the desktop's icons while a whinge is on, so the recording shows your
work rather than your downloads folder. In [Settings → General](/docs/settings#general) it can also
swap the wallpaper for a plain colour or a picture, and hide every app but the one in front.

| Do | To |
| --- | --- |
| **⌃⌥D**, or the pencil | Draw. The mouse is yours again when you turn it off. |
| A colour swatch | Pick a marker, and start drawing. |
| The eraser, or **E** while drawing | Rub out strokes by dragging over them. **D** goes back to the pen. |
| **Esc** / **Return** while drawing, or the bin | Clear all the drawing, and start the next topic. |
| **⌘Z** while drawing | Undo a stroke, or an erase. |
| The ladybird, or `whinge bug` | [Report a problem with Whinge](#whingeing-about-whinge). |
| The stop button, or `whinge stop` | Finish. |
| `whinge cancel` | Throw the whinge away. |

⌃⌥D is only registered while a whinge is recording, so other apps can have it the rest of the time.
Change it in **Settings → Drawing**.

## Ink sticks to what you draw on

A stroke belongs to the window it's mostly over. Drag the window and the drawing goes with it; put
another window in front and the drawing is hidden behind it. In a browser, it belongs to the page:
switch tab and it goes, switch back and it's there again. Ink drawn over no window stays put on the
screen.

So you can circle something, flick to another tab to show what it should look like, and come back to
your circle. Before a drawing is switched away from, Whinge keeps a screenshot of it for the recording.

Clearing still clears everything, showing or not. Turn off **Ink sticks to windows** in
**Settings → Drawing** to keep all ink where you drew it.

## Clearing is the habit

Clearing is how Whinge knows one point has ended and the next has begun. It's also the moment it
grabs the screenshot, with your drawing still on it.

- One point per clear. Circle the thing, say what's wrong, clear.
- Going back to something you covered earlier is fine: it's treated as the same point.
- By default, clearing also stops drawing, so your mouse is back and ready. Turn off **Clearing
  stops drawing** in **Settings → Drawing** to keep the marker.

## Whingeing about Whinge

When Whinge itself gets something wrong, report it the same way you whinge about anything else.
Press the ladybird on the toolbar (or pick it on the wheel, choose **Report a Bug in Whinge…** from
the menu, run `whinge bug` or open `whinge://bug`), then say and draw what's wrong.

While you do, the whinge is paused: nothing goes into its video, audio, transcript or ink, and the
timer stops. A violet glow round the edge of every screen shows you're reporting a bug rather than
whingeing. Drawing, the eraser and clearing all still work, and a clear doesn't start a new topic.

You don't need to be in a whinge. With nothing recording, **Report a Bug in Whinge…** in the menu
(or `whinge bug`) brings up the toolbar and the glow just for the report; its stop button, or the
ladybird, finishes it, and `whinge cancel` throws it away.

Press the ladybird again to finish. Whinge takes screenshots with your drawing on them (the glow is
left out) and opens a window with everything it's about to send:

- the screenshots, each one removable,
- what you said, which you can correct,
- a box for anything else,
- and the [debug log](#the-debug-log), with a checkbox to leave it out and a way to read it first.

Nothing leaves your Mac until you press **Send**. If it can't be sent right then, Whinge keeps it and
tries again later. In a whinge, once the window closes, the ink you drew for the report comes off
and the whinge carries on where it was.

## The debug log

Whinge keeps a log of what it's doing: which microphone it's using and its format, the speech
model, everything speech recognition hears and why it wasn't the wake phrase, each step of
recording and saving, and any errors. Each whinge has its own copy, `debug.log` in its
[folder](/docs/sessions), and there's one rolling log of everything. **Show Debug Log** in the menu
opens the rolling one; `whinge log` prints its end and `whinge log DIR` a whinge's.

The log stays on your Mac. It holds what you said and window titles, so it's only sent if you tick
it in a bug report, after you've seen it.

## If Whinge quits mid-whinge

The video and audio are written in pieces a few seconds long, and what you say is transcribed as
you go, so a crash only loses the last few seconds. Next time Whinge opens, it offers to save
what was captured.

## Stopping

Press stop, or run `whinge stop`. Whinge saves the live transcript, groups it into topics,
selects screenshots and finishes the recording. It does not run a write-up or project instructions.
`whinge attach` waits for the saved folder path.

## Pedals, launchers and Stream Decks

Whinge answers these URLs, so anything that can open one can drive it:

| URL | Does |
| --- | --- |
| `whinge://start?context=…` | Start listening, with an optional note in the recording |
| `whinge://toggle` | The next step: start listening, start recording, or stop |
| `whinge://draw` | Turn drawing on or off |
| `whinge://clear` | Clear, and start the next topic |
| `whinge://bug` | Start or finish a bug report |
| `whinge://stop` | Finish |
| `whinge://settings` | Open Settings |

The CLI has the same: `whinge draw`, `whinge clear`, `whinge bug`, `whinge stop`.