Build CleanShot X

The build, in order

1. 1

   Permission and a region screenshot

   hideshow

   Dragging a region writes a correct PNG to disk, with the Screen Recording permission handled honestly.

   1. 1.1Request Screen Recording and handle refusal

      Call CGRequestScreenCaptureAccess early. If it returns false, show a panel explaining what is lost and a button that opens x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture.

      Files Permissions.swift

   2. 1.2Draw the selection overlay

      A borderless transparent window at screen level covering every display, with a crosshair cursor and a dimmed region outside the selection. Escape cancels.

      Files SelectionOverlay.swift

   3. 1.3Capture and write with the correct scale

      SCContentFilter for the display, set the SCStreamConfiguration width and height to the selection multiplied by the display backing scale factor, then write PNG through CGImageDestination.

      Files Capture.swift

   done when · tick each as it passes

   • A 400 by 300 point selection on a Retina display produces an 800 by 600 pixel PNG
   • Escape during selection cancels and writes nothing
   • Denying the permission shows an explanation and a working Settings link
   • Capturing across two displays with different scale factors produces correct pixel sizes on both

   watch out

   • The Screen Recording grant is tied to your code signature. Re-signing with a different identity invalidates it and macOS will not prompt a second time; the user has to delete the entry in System Settings first. This will bite you during development every time the binary moves.
   • A captured image is in physical pixels, not points. On a Retina display a 400 point selection is an 800 pixel image, and forgetting the backing scale factor gives you a half-size or double-size file.

   next phase
2. 2

   Annotation, and a redaction that is real

   hideshow

   You can draw on a capture, and a redacted region is unrecoverable in the exported file.

   1. 2.1Build the shape model and the editor canvas

      Shapes are values with a type, a rect or a pair of points, a colour and a z index. Render them in a SwiftUI Canvas over the image. Undo is a stack of shape arrays.

      Files Editor.swiftShape.swift

   2. 2.2Implement destructive redaction

      For each redact shape, crop the region, resize it to roughly eight pixels across with CIImage, scale it back to the region size, and draw the result into the output context before any other annotation.

      Files Redact.swift

   3. 2.3Composite and export

      Draw the base image, then redactions, then the remaining shapes in z order, into a CGContext at full pixel size. Write PNG or JPEG.

      Files Export.swift

   done when · tick each as it passes

   • Text under a redacted region is unreadable in the exported file opened in another application
   • Undo removes the last shape and redo restores it
   • Moving an arrow changes the exported bytes
   • Text annotations render at the same size in the export as on screen

   watch out

   • A blur or a black box drawn as an overlay leaves the original pixels in the file if you ever export the layered form, and pixelation with a large enough block size is still reversible if the block grid is fine. Downsample the region to a few pixels and scale it back up, or fill it with a solid colour. Then verify by opening the exported file somewhere else.

   next phase
3. 3

   Screen recording with microphone audio

   hideshow

   A recording plays back with audio and video still in sync a minute in.

   1. 3.1Set up SCStream for video

      SCStreamConfiguration with the display size, a frame rate you choose deliberately, and showsCursor as a setting. Handle the stream stopping when the display configuration changes.

      Files Recorder.swift

   2. 3.2Add microphone capture and request permission

      AVCaptureSession with an audio device. Microphone is its own privacy grant, separate from Screen Recording, and it has its own usage description string in Info.plist.

      Files Audio.swiftInfo.plist

   3. 3.3Write one file with a shared session clock

      Create AVAssetWriter with a video input and an audio input. Call startSession(atSourceTime:) once with the first video sample's timestamp, and append audio using the same timebase.

      Files Writer.swift

   done when · tick each as it passes

   • A sixty second recording is still in sync at the end when scrubbed
   • The finished MP4 opens in QuickTime without a repair prompt
   • Denying microphone access still records video and says so
   • Changing display resolution mid-recording either stops cleanly or continues, never writes a corrupt file

   watch out

   • Screen samples and microphone samples arrive on separate callbacks with unrelated clocks. Start the AVAssetWriter session once, from the first video sample's presentation timestamp, and translate audio timestamps into that same timeline. Starting each input from its own first sample is the standard way to get audio that drifts steadily out of sync.

   next phase
4. 4

   Trim, export and the capture pipeline

   hideshow

   Every capture lands where you expect, in the format you asked for, with one keystroke.

   1. 4.1Add trimming with a real re-encode

      AVAssetExportSession with timeRange set. Verify the output duration, because setting a range on a player is not the same as writing a trimmed file.

      Files Trim.swift

   2. 4.2Add GIF export through ffmpeg

      Run ffmpeg twice: once with palettegen into a temporary PNG, once with paletteuse. Bundle ffmpeg or detect it and tell the user how to install it.

      terminalcopy

      ffmpeg -i in.mp4 -vf "fps=15,scale=800:-1:flags=lanczos,palettegen" palette.png
      ffmpeg -i in.mp4 -i palette.png -lavfi "fps=15,scale=800:-1:flags=lanczos[x];[x][1:v]paletteuse" out.gif

   3. 4.3Wire the global hotkeys and the pasteboard option

      Three hotkeys for region, window and full screen. On capture, write the file and optionally put it on the pasteboard so the next Cmd-V pastes the image.

      Files Hotkeys.swift

   done when · tick each as it passes

   • A trimmed export reports the trimmed duration in QuickTime, not the original
   • A GIF export shows smooth gradients rather than banded colour
   • Each hotkey produces the right capture kind
   • With the pasteboard option on, Cmd-V in another app pastes the capture

   watch out

   • A one-pass GIF from ffmpeg uses a fixed palette and looks like it came from 1998. Generate a palette with palettegen from the actual frames, then apply it with paletteuse. It is two commands and it is the whole difference.

   next phase
5. 5

   Library and cleanup

   hideshow

   Captures accumulate somewhere you can find them, and old ones do not fill the disk quietly.

   1. 5.1Build the library grid

      Read captures ordered by created_at, render thumbnails generated at capture time rather than by decoding full images on scroll.

      Files Library.swift

   2. 5.2Make deletion atomic and reconcile on launch

      One delete function removes the file then the row. On launch, drop rows whose file is missing and offer to import files with no row.

      Files Store.swift

   3. 5.3Add retention

      A setting for maximum age and maximum total size. Apply on launch and after each capture, oldest first, never starred.

      Files Retention.swift

   done when · tick each as it passes

   • Deleting from the library removes the file from disk
   • A file deleted in Finder does not leave a broken row after relaunch
   • Retention removes an aged capture and leaves a starred one
   • The grid scrolls smoothly with several hundred captures

   watch out

   • Deleting the row without deleting the file, or the file without the row, is the bug you will ship. Make deletion one function that does both and reconciles orphans on launch.