How It Was Built Part 2

Part of How ShadePlay was built

Part 2: how we worked

Who did what

• The maintainer set the requirements and made the key decisions: the hotkey, the frame rate, always recording, no Google sign-in, one simple settings page, AMD and Intel support, the name, going public and the credit. Several times the maintainer picked something other than Claude's recommendation: the settings window before the first test, F10 instead of Alt+F10, Intel graphics as well as AMD, and no Google app. Twice the maintainer cut back what Claude had built: "too complicated", and "we can remove that too" for the YouTube helper.
• The maintainer did every hands-on test that needs a person at the PC: the first start, real clips in real games, the Discord check, every YouTube upload and the HDR checks afterwards, and every restart of their own recorder.
• Claude (an AI model made by Anthropic) did the research, the design, the code, the automated tests and the measurements, wrote the docs, and explained each step in plain words.
• Claude worked in parallel. For big jobs, Claude first wrote the shared contracts itself (the headers that every part must follow) and then had several Claude instances build separate parts at the same time, each in its own files. Other instances then reviewed the result, checked each other's findings and fixed them.
• For the release, the work was split across several Claude sessions: one for the app (code, tests, installer, docs), one for the release (git, the repository, scans, publishing) and one coordinating them. Written handoff notes carried the state from one session to the next, and the sessions reported to each other through files.

Research before code

September 24, and again on September 27

Before any code, every risky question got a research note: 12 notes in all.

• The first round covered screen capture and HDR, FFmpeg's programming interface, the graphics card's encoders, Windows audio, the app shell (start-up, hotkey, recovery, tray) and a toolchain test on the real PC.
• Later rounds covered YouTube uploads (five notes) and AMD and Intel encoders (one note).
• Primary sources first: Microsoft's documentation, FFmpeg's source code read at the exact version used, NVIDIA's encoder guides, Google's YouTube documentation, and open-source recorders and tools. Two of those, OBS Studio and Sunshine, are GPL-licensed. Their approaches were described in our own words, and all of ShadePlay's code was written new.
• Every claim got a confidence mark: high (measured on the PC, or from a primary source), medium (strong indirect evidence) or low (a community report or a guess).
• Then a skeptical second pass. A separate Claude instance re-checked the important claims of each note with its own test programs, not the researcher's, and wrote its corrections straight into the note. The toolchain test was pure measurement and needed no second pass, and the AMD and Intel note rests on test programs run on a real AMD GPU. No claim of the first round was refuted outright, but many were corrected in detail, and several corrections changed the design (When the AI got it wrong).
• The notes are working papers full of details about one private PC, so they are not published. What they found is on this page and in ARCHITECTURE.md.

Small programs first

September 24

Before the design was written, small throwaway programs proved each risky piece on the real PC: the toolchain itself; HDR screen capture at about 360 frames per second on the right graphics adapter; the whole picture path from capture through GPU colour conversion and the NVIDIA encoder to an MP4 file, which held 240 and 360 fps at 1440p with the conversion costing about 0.045 ms of GPU time per frame; what Windows' per-program audio recording accepts and records; and how long encoding four audio tracks takes. The probes saved no screen images and no audio, changed no settings and wrote only to a scratch folder. The design was written on what they proved, and the first recorder was built on that design the same day.

The chair rules

• Only the maintainer starts, quits or restarts their running recorder. Claude asks first. The maintainer can give a standing OK, "redeploy when it's ready", and even then Claude first checked that no clip was being saved.
• Nothing may steal focus or pop up, because the maintainer may be in a fullscreen game.
• Claude's copies never touch the real one. Test copies run under their own name, with their own settings folder and hotkey (Live checks that disturb nobody).
• Screen tests need the maintainer. A monitor that is off sends no picture. Claude declined to fake keyboard or mouse input just to wake one, and the screen test waited for the maintainer.
• Test clips that captured the screen were deleted as soon as they were checked. Files the maintainer might want back went to the Recycle Bin, never straight into oblivion.

How claims were checked

Big pieces of work went through the same stages: build in parallel, integrate (a clean build, every test, live checks on the PC), review, verify every finding, fix, and a final clean rebuild.

• Reviews by dimension. Each reviewer looked at one side of the code: threads and locks, video, audio, saving and MP4 files, start-up reliability, resource use over days of uptime and robustness; later also the move-over from the private build, the installer, what goes public, and simplicity.
• A skeptic for every finding. Each finding went to another Claude instance that was told to try to refute it, and to confirm it only with a concrete path through the code.
• The first review (September 24) reported 47 findings. All 47 were confirmed (2 high, 17 medium, 28 low) and all were fixed. The two high ones: start-with-Windows was registered only on the very first run (Starting with Windows, every time), and a hang in the video thread went unnoticed whenever audio had a problem (Hangs that went unnoticed).
• The second review (September 27) reported 24 findings: 23 were confirmed and fixed, and 1 was refuted. The worst was a hotkey picker that pressed buttons.
• The release review (September 28) reported 33 findings: 32 confirmed and 1 uncertain. The three high ones were all about going public: GPL code inside an FFmpeg DLL, missing notices for small components inside those DLLs, and personal details in the private working notes (which are never published anyway).
• Mutation checks. For important fixes, the old bug was put back on purpose, to prove that the new tests catch it. Restoring the old audio rule, for example, makes 3 tests fail (Counted once).
• Independent references. The colour conversion was checked on the GPU against a separate reference written in Python, with expected values that did not come from the C++ code.

Tests that fake the system

September 24

Problem. Unit tests that touch the real system are dangerous on a PC someone uses every day. In Claude's sandbox they are also misleading: writes to the registry and to AppData are quietly redirected, so a test can look as if it worked while it did nothing, but a call to Windows' Task Scheduler is real and would change the actual system (Traps in Claude's own workspace).

Fix. A standing rule, carried over from the maintainer's other open-source tools: tests never touch the real registry, processes, audio or video devices, capture sessions, user files or network ports.

• Pure logic is kept apart from Windows code. The watchdog takes a fake clock, the video recovery rules and the audio mixing rules are pure functions, and the move-over from the private build talks to small interfaces that the tests replace with fakes.
• Temporary files go to a fresh folder under Temp that is deleted at the end.
• The test framework is tiny and built in, so testing needs no downloads.
• A test keeps the command lines printed in the README and in BUILDING.md valid.
• The count grew with the work: 255 tests at the first full build, 331 after the first review, 421 and then 503 on September 27, 602 at the end of the first release work, and 764 at release (0.1.0), with 0 compiler warnings at the end of every stage.

Live checks that disturb nobody

Unit tests can't prove that a real screen, a real headset and a real Discord call end up in a clip. For that, Claude ran live checks on the maintainer's PC, built so that they could not bother anyone:

• An inaudible stand-in game. A tiny helper played a 17 kHz tone at -80 dBFS on the headset only, never on the bass shaker. That is far too quiet and too high to hear. The recorder was told the helper was "the game", and the clip was analysed in blocks of 100 ms.
• Test copies. A test copy runs under its own instance name, with its own settings folder, the hotkey Ctrl+Alt+F12, no sounds, no notifications, no start-with-Windows, and a switch that stops it from opening a browser, File Explorer or the clipboard.
• Screenshots without a screen. The settings window was captured on a hidden desktop, never on the maintainer's.
• The clipboard in a sealed room. One clipboard check ran in a private window station. The maintainer's clipboard counter read the same before and after.
• Watching for stray processes. To prove that a feature started no helper process, a watcher took 515 snapshots of the process list, 5 ms apart.
• Clips from live checks were inspected with FFmpeg's own tools and then deleted.

When the AI got it wrong

Being candid here is part of the transparency promise. Most of the bugs on this page were in Claude's own code. This section collects the wrong assumptions, the wrong claims and the slips.

• It assumed the game plays on the Windows default output. The first audio design recorded "the desktop" from the default output only. In every live run of the first day that track was digital silence, because the game played on the headset (The game plays on the headset).
• It called the first clip "in sync" too early. All four audio tracks of that clip were digital silence. They started together and were equally long, which is not the same as being in sync. The real evidence came later, from the inaudible-tone tests and from clips with a real call and a real microphone.
• It left a question unanswered. The maintainer asked "what about AV1 encoding?" and got no direct answer at the time, although AV1 was already the plan.
• It overstated the save time. Claude told the maintainer that the default audio encoder "would add about 11 seconds to every save". That figure came from a single-threaded test that ran while other test programs were busy with the same hardware. Measured properly, encoding four 60-second tracks in parallel took about 1 second, and a real 60-second clip saves in 3 to 4 seconds. The correction didn't reach the maintainer that day.
• Its own test runs disturbed each other. Several research programs used the graphics card's encoder at the same time, which caused stalls and distorted readings. The affected numbers were marked as medium confidence.
• The second research pass corrected several claims before any code was written:
  • that NVIDIA's AV1 encoder writes HDR information into the video itself. The claim was even marked "verified", but the HDR data the researcher saw came from the MP4 file's own label, copied over by the decoder (HDR metadata the encoder doesn't write);
  • that a new bitrate can be applied to a running encoder (for HEVC it silently broke the file's headers);
  • that FFmpeg's texture arrays fail from 4 slices up (they fail from 3);
  • that one setting of FFmpeg's resampler counts output samples (it counts input samples, and would have injected hours of silence: Hours of silence from one wrong unit);
  • that Discord can be recorded in stereo as it is (it came back 13.5 dB too quiet);
  • that switching off B-frames avoids MP4 edit lists (FFmpeg writes them anyway);
  • that an error code reveals a clash with NVIDIA's own hotkeys (F10, and a check you do once);
  • that a tray app can hold off Windows' shutdown while it saves (apps without a visible window can't; they are ended after about 5 seconds);
  • that one Windows-version setting of the compiler hides a display structure (it is the other way round).
• It shipped a known limit. The first rule for counting every sound once had a limit that its own review had written down: a silent stream on a second device counted as "playing there". It shipped anyway, and in real use a game and Discord were doubled in the mix until the fix later that day (Counted once).
• It suggested a wrong stopgap. While that fix was being built, Claude suggested recording the Windows default output for the time being. The maintainer: "Windows default isn't the right device, the audio is set correctly." Claude withdrew the suggestion.
• It had the wrong theory about YouTube and HDR. YouTube's documentation lists HDR only up to 60 fps, so Claude assumed that 240 fps clips lose their HDR. A helper that made 60 fps copies was built on that. The maintainer's own uploads proved that YouTube simply adds the HDR version later, and that 240 fps clips work as they are (The HDR scare). Part of that work turned out to be unnecessary.
• It over-built the settings. Six pages with per-track volumes and offsets, game lists and a YouTube page, until the maintainer said: "The app is too complicated. I want it to be simple and just work." (Too complicated).
• It trusted a build's own description of its licence. On September 27 Claude told the release session that the FFmpeg DLLs were LGPL-licensed, because ffmpeg -buildconf showed no --enable-gpl. That did not prove it. The release review found GPL code (the FFTW library, pulled in by the Chromaprint library) compiled into one of the DLLs, which puts that DLL as a whole under the GPL. The fix, chosen by the maintainer, is ShadePlay's own minimal LGPL build of FFmpeg (Licences, and a GPL surprise).
• Its code carried personal details. Code comments named the maintainer's own devices, the default never-record list contained the maintainer's own device, one start-up rule named a folder on the maintainer's PC, and the program file contained the path of the build folder, which includes the Windows user name (No personal information).
• Its fixes brought new bugs, caught before shipping: a "not recording" warning written to the log every second (23 lines in 22 seconds), and a gap in the guard for development copies, which would have let a freshly built copy move the maintainer's real install over. And its calm standby for a missing monitor missed a sleeping one, which caused a restart every minute (A monitor that is asleep, not gone).
• A quick edit broke a test. Changing the default hotkey with a search-and-replace also changed a test that checks how "Alt+F10" is written. It was put back straight away, and all 331 tests passed again.
• Its tests reached the maintainer's desktop. Twice a test copy's tray icon showed up on the maintainer's taskbar for about a minute, and one check ran a second recording engine next to the maintainer's own for about half a minute. The Claude instances that did it reported each one themselves.
• A README promise that would have broken. The first README said that ShadePlay "never goes online by itself". With an update check that stops being true. Claude flagged it before the update checker was built, so the sentence can't ship.

What went right is worth a line too:

• Claude flagged YouTube's "private until audited" lock before building anything on YouTube's programming interface.
• It measured how Windows' audio level meters behave before designing the fix that depends on them.
• When the maintainer's recorder stopped unexpectedly, Claude checked everything (crash dumps, logs, every test and every command that ran) before "fixing" anything, then asked. The maintainer's answer: "It's running, I closed it earlier." Nothing needed changing.
• It asked before every restart of the maintainer's recorder.

Traps in Claude's own workspace

Problem. Some wrong turns came from Claude's tools, not from the app. Claude runs inside the Claude desktop app's sandbox on Windows.

What we found, each one checked:

1. The sandbox quietly redirects writes to AppData and to the user's part of the registry. A recorder started by Claude would have used a private copy of the settings, and it could not register itself to start with Windows. So the maintainer had to start the recorder for the first time, with a double-click.
2. For the same reason the move-over from the private build must run on the maintainer's own first start of ShadePlay: started by Claude, it would never see the real settings folder.
3. When the maintainer allowed a restart, Claude started the recorder through its own start-with-Windows task, so that it ran outside the sandbox with the real settings.
4. Task Scheduler is not redirected. A test that registers a task would change the real system: one more reason why the tests fake everything.
5. Git Bash's tar can't unpack zip files. Windows' own tar.exe can.
6. Claude's shell mangles backslashes in inline scripts, so scripts are written to a file first.
7. A Windows path with a drive letter broke an FFmpeg filter, whose options are separated by colons.
8. One test command lacked its separate settings folder and would have written a log into the maintainer's real settings folder. The integration step caught it.

Fix. The lessons went into the handoff notes and the chair rules: the maintainer starts the real app, Claude restarts it only through its own task and only with the maintainer's OK, and anything that must act as the user runs outside the sandbox.

---

---

<- Part 1: why ShadePlay exists | Contents | Part 3: the picture ->