--- name: "live_coding_streams" description: "Plan, record, and edit coding demo videos and live-coding streams: scripting the arc of a technical walkthrough, pacing for viewers who pause and rewind, on-screen annotation, and recovering calmly when the code breaks on camera. Use when producing a coding tutorial, a scripted screencast, a live coding stream, or a conference talk with live code." --- # Live Coding Streams ## Purpose Turn a coding demo into a video people can actually follow. Most coding videos fail in one of four ways: no arc (rambling through code), no pacing (typing too fast for viewers who pause and rewind), no annotation (viewers can't tell where to look), or a broken recovery (the demo breaks and the presenter either goes silent or panics). This skill gives you a repeatable plan for all four, for both scripted screencasts and live streams. ## Workflow ### 1. Plan the arc Write the plan before opening the editor. Every coding video, any length, gets the same three-act shape: 1. **Hook (first 10-15%).** Show the finished result running. Not a logo, not an intro, not "hey guys": the thing working. Viewers decide in the first seconds whether to stay. 2. **Build beats (70-80%).** Three to five beats, each one a single concept, in the order a real developer would write them. Each beat: explain what is coming, type it, run it, show what it did. 3. **Close (last 10-15%).** Land on the finished state and one call to action (one link, said out loud and shown on screen). One video, one concept. If it needs two concepts, it needs two videos. ### 2. Write the script to be spoken Write full spoken sentences, not bullet points to ad-lib from. Mark the code beats in the script with cues: `[TYPE: for line in rows:]`, `[RUN: python parse.py]`, `[EXPECTED: 12 rows, no errors]`. Read-aloud pace is roughly 130 words per minute; budget a 10-minute video at ~1,100 spoken words after pauses. Rehearse it out loud once. The rehearsal always catches tongue-twisters and the places where the demo drags. ### 3. Pace for viewers who pause and rewind Assume the viewer is coding along and needs twice the time you do. The Carpentries' live-coding research backs a tell-show-tell rhythm: 1. **Say** what you are about to type. 2. **Type** it while narrating, slowly. Do not paste blocks of code; pasting is how you lose half the audience. 3. **Point** at the line and its output afterward and explain it again. Then move on. Extra rules: - Pause 2-3 seconds between major beats. Give viewers time to catch up or hit pause themselves. - Keep on-screen text short (a step number or a command, not a paragraph). - Zoom or highlight the line being discussed. Never cut away before the viewer sees what the action did. - Big font in the editor (18pt or more), window maximized, clean desktop, notifications off. Viewers on phones have to be able to read it. - After every run, state the expected result out loud. "We should see 12 rows and no errors" is what turns output from a blur into a checkpoint. ### 4. Annotate the screen Annotation answers one question: where should the viewer look right now. Pick one visual language and stay with it: a highlight for the line being edited, an arrow or box for where to click, a short label for step numbers. Build the annotation up as you go rather than flashing a finished diagram. Keep it minimal: one highlighted thing at a time. If two things need attention at once, you planned the beat wrong. ### 5. Scripted vs. live Scripted screencasts get the full script and an edit pass that cuts dead air. Live streams get a beat sheet instead: one page with the arc, the code cues, and the expected outputs, kept visible on a second screen or printout. Lean on it. The stream's job is the interactive parts a screencast can't do: answering "what if" questions, going off the plan briefly, and being visibly human. Rehearse any off-plan trick thoroughly before trying it live. Untested detours are where streams die. ### 6. Recover when the code breaks It will break. A break handled well is the best teaching in the video; a break handled badly is where viewers leave. - **Reframe it.** Say "let's figure this out" and treat the bug as the lesson. Never narrate it as a personal failure. - **Debug out loud.** Silence is the worst bug on camera. Read the error message, say what you expected versus what you got, and state a hypothesis before touching the code. One change, then re-run. Predict the result before the output appears. - **Give yourself a timebox.** Two minutes on camera, then escalate to an escape hatch (see below). A long silent grind is not educational; it is boring. - **Escape hatches, set up in rehearsal:** commit the project at each beat (a git commit per beat), so any break can be reset to the last known-good state in seconds. Rehearse the whole demo end-to-end on a clean environment first; the errors you hit in rehearsal are the ones you should have fixes ready for. If you are truly stuck, name your hypothesis out loud, roll back to the last working commit, and keep going. The viewer learns "how to retreat cleanly," which is a real skill. - **Keep the instructive mistakes in the edit.** Cut the ones that were just typos or you fumbling with the window manager; keep the one where the logic failed and you traced it down. That one is why people watch humans code. ### 7. Edit and ship Trim dead air and long pauses, keep the arc's rhythm. Add chapter markers for anything over two minutes so rewind-viewers can jump back. Title is the concept plus the payoff, under 60 characters. Description is one sentence on what the viewer will be able to do after watching, then the link, then chapters. Thumbnail: one frame from the video with the result running, 3-5 words max. ## Output Contract Each production delivers: the spoken script (or beat sheet, for live streams) with code cues and expected outputs, raw takes, the edited master, and a title + description + thumbnail draft. Nothing is done until the master plays start to finish with no dead air and every run's output is visible on screen. ## Operating Rules 1. **Plan first, record second.** The script is the deliverable that decides quality. Footage can be re-shot; a bad arc cannot be saved in the edit. 2. **Type it, don't paste it.** Viewers who can't follow the typing can't follow the video. 3. **Tell, show, tell.** Say it, type it while narrating, explain the result. 4. **Never cut before the viewer sees the result.** The output on screen is the whole point of the beat. 5. **Debug like it's the lesson.** Because it is. Read the error, hypothesize, one change, re-run. Out loud, always. 6. **Commit per beat.** A known-good checkpoint before every beat is the cheapest insurance a coding demo has. 7. **Silence is the worst bug.** If you go quiet for more than a few seconds, narrate what you are thinking. 8. **One concept per video.** Two concepts means two videos. Tangents go in the next video, not this one. 9. **No invented stats.** Never claim retention numbers, watch-through rates, or timing claims you haven't verified. Cut them or frame them as opinion.