Screendrop 딥다이브
— Loom·CleanShot을 대체하면서 서버까지 내 계정에 두는 법

1프로젝트 한줄 요약

Screendrop은 맥 메뉴바에 사는 화면 캡처·녹화 앱입니다. 창이 없습니다. Dock에도 안 뜹니다. 단축키를 누르면 화면을 찍고, 찍은 것이 화면 구석에 카드처럼 떠오르고, 거기서 바로 화살표를 그리거나 개인정보를 가리거나 영상을 잘라내고, 복사하거나 저장하거나 링크로 공유합니다.

기능만 나열하면 CleanShot X나 Loom과 겹칩니다. 다른 점은 공유 링크를 만드는 서버가 개발자 것이 아니라 내 것이라는 데 있습니다. Screendrop은 서버를 운영하지 않습니다. 대신 Cloudflare에 올릴 수 있는 작은 서버 코드를 따로 주고, 앱은 그 주소와 비밀번호 한 개만 들고 있습니다.

숫자로 보면 이렇습니다. Swift 174개 파일 49,605줄, Go 2개 파일 1,061줄. 외부 라이브러리는 딱 2개(자동 업데이트용 Sparkle, Dock 아이콘 진행률용 DockProgress). 나머지 — 네트워크, JSON, 키체인, 이미지·영상 인코딩, 문자 인식, 음성 인식, 전역 단축키 — 는 전부 애플 기본 프레임워크로 직접 짰습니다.

2왜 주목받는가

① 이 카테고리는 전부 유료거나 전부 클라우드다

② 개발 속도가 눈에 보인다

자동 업데이트 목록 파일(appcast.xml)을 세어 보면 릴리스가 26개입니다. 첫 릴리스가 2026-05-26, 최신이 2026-08-20 — 86일 동안 3.3일에 한 번씩 냈다는 뜻입니다. 저장소를 보는 사람이 "이거 방치된 프로젝트인가"를 판단할 때 별 개수보다 정확한 신호가 이것입니다.

③ 진짜 볼거리 — 최신 API를 이유를 적어 놓고 안 쓴다

애플은 2022년부터 화면 캡처는 ScreenCaptureKit을 쓰라고 안내합니다. Screendrop은 스크린샷에는 안 씁니다. 대신 맥에 원래 들어 있는 명령줄 도구 /usr/sbin/screencapture를 실행합니다. 그리고 그 이유가 주석에 적혀 있습니다.

/// ScreenCaptureKit의 디스플레이 캡처는 창을 스스로 재합성하면서
/// WindowServer가 넣어 준 창 그림자를 떨어뜨린다. 그래서 밝은 배경 위
/// 창은 경계를 잃는다. screencapture는 실제 화면 합성 결과를 뜬다.
func captureFullscreen(displayID: CGDirectDisplayID?) async -> URL? {
    let displayIndex = Self.screencaptureDisplayIndex(for: displayID)
    guard let url = await runScreencapture(args: ["-D", "\(displayIndex)"]) else { return nil }
    trimEmptyMenuBarIfNeeded(at: url, displayID: displayID)
    return url
}

영상 녹화에는 반대로 ScreenCaptureKit을 씁니다. 녹화는 프레임을 초당 60번 실시간으로 받아야 하는데, 그건 screencapture로는 불가능하기 때문입니다. 같은 앱 안에서 용도에 따라 다른 답을 골랐고, 왜 그랬는지가 코드에 남아 있습니다.

④ 저장소가 AI 에이전트용 사용설명서를 같이 담고 있다

.agents/skills/ 폴더에 SKILL.md 4개가 들어 있습니다. "이 프로젝트를 빌드하는 법", "빌드해서 실행하는 법", "릴리스를 내는 법", 그리고 "맥 노치(카메라 홈) 모양 UI를 만드는 법". 앞의 셋은 이 저장소 전용이지만, 마지막 하나는 앱 이름이 {{AppName}} 자리표시자로 되어 있어 다른 앱에도 그대로 갖다 쓸 수 있게 쓰여 있습니다.

즉 이 프로젝트는 "나를 어떻게 빌드·배포하는가"를 README 옆에 흘려 쓴 게 아니라, 버전 관리되는 별도 문서로, AI 협업자를 독자로 두고 관리합니다. 2026년 오픈소스 저장소가 실제로 어떻게 바뀌고 있는지 보여주는 표본입니다.

3기술 스택 전체 지도

앱 본체 (Swift)

외부 의존성이 2개뿐이라는 게 이 스택의 성격을 요약합니다. HTTP 클라이언트 라이브러리도, 이미지 처리 라이브러리도, 단축키 라이브러리도 없습니다. URLSession·Codable·SecItemAdd를 직접 씁니다.

동시성 설정 — 이 프로젝트에서 가장 배울 만한 빌드 설정

Xcode 프로젝트 파일(project.pbxproj)에 이렇게 박혀 있습니다.

SWIFT_VERSION = 5.0
SWIFT_APPROACHABLE_CONCURRENCY = YES
SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor
SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES

그러면 진짜로 백그라운드에서 돌아야 하는 것들(스트림 콜백, 인코더, 합성기)은 어떻게 할까요? 명시적으로 빠져나옵니다.

nonisolated final class ScreenRecordingCapture: NSObject,
        SCStreamOutput, SCStreamDelegate, @unchecked Sendable { ... }

이렇게 메인 스레드 밖으로 나간 클래스가 저장소 전체에 12개입니다 — 스트림 캡처(ScreenRecordingCapture), 파일 기록(ScreenRecordingWriter), 프레임 합성(StudioFrameCompositor), 웹캠(CameraCaptureEngine) 같은, 정말로 백그라운드여야 하는 것들뿐입니다. 49,605줄짜리 앱에서 동시성 버그를 찾을 때 들여다볼 곳이 nonisolated 한 단어 검색으로 12군데로 좁혀집니다.

릴리스 도구 (Go)

cmd/screendrop-release/main.go, 992줄, 외부 패키지 0개(Go 표준 라이브러리만). 이 하나가 빌드→공증→DMG→서명→appcast 갱신→GitHub 릴리스→Homebrew 캐스크 갱신까지 전부 합니다. 5장에서 단계별로 뜯습니다.

공유 인프라 (Cloudflare, 별도 저장소)

앱이 아는 비밀은 업로드 토큰 하나뿐입니다. R2 접근 키 같은 건 앱에 없습니다 — Worker 안에만 있습니다. 예전 버전은 S3 자격증명을 앱이 들고 있었는데, 그 시절 키체인 항목(cloud_s3_access_key_id 등)을 삭제하는 코드가 아직 남아 있어서 설계가 바뀐 흔적을 그대로 볼 수 있습니다.

4아키텍처 심화 분석

전체 흐름

패턴 ① 창을 "파일 주소"로 여는 SwiftUI 구조

@main
struct ScreendropApp: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        MenuBarExtra("Screendrop", image: "MenuBarIcon", isInserted: $showMenuBarIcon) {
            MenuBarView()
        }
        WindowGroup("Screendrop Annotate", id: "ANNOTATION_EDITOR", for: URL.self) { value in
            AnnotationEditorWindow(url: value)
        }
        WindowGroup("Screendrop Recording Editor", id: "VIDEO_EDITOR", for: URL.self) { value in
            RecordingStudioWindow(url: value)
        }
    }
}

WindowGroup(for: URL.self)가 핵심입니다. "주석 편집기 창"이 아니라 "이 파일을 편집하는 창"으로 정의됩니다. 그러면 같은 파일을 두 번 열어도 창이 하나만 뜨고, 앱을 껐다 켜면 열려 있던 창이 알아서 복원됩니다. 창 목록을 직접 관리하는 코드가 필요 없습니다.

다만 SwiftUI만으로 안 되는 것들이 있어 AppDelegate가 따로 붙습니다: Dock에 안 뜨게 하기, Carbon 단축키 등록, Sparkle 시작, 그리고 "녹화 중에 종료 누르면 막기". 마지막 것이 특히 실무적입니다 — 경고창을 띄우고 .terminateLater를 돌려줘서 파일 쓰기가 끝날 때까지 앱이 안 죽게 붙잡습니다.

패턴 ② 커서를 일부러 안 찍고, 나중에 그린다

녹화 설정에 showsCursor = false가 있습니다. 마우스 커서를 영상에 안 담습니다. 대신 커서가 어디 있었는지를 좌표로만 따로 기록해 두고(input.json), 편집·내보내기 때 가짜 커서를 부드럽게 그려 넣습니다.

패턴 ③ 크래시해도 영상이 살아남는 기록 방식

let writer = try AVAssetWriter(outputURL: outputURL, fileType: .mov)
// 조각 단위 무비: 중간에 죽어도 마지막 조각까지는 재생 가능한 파일이 남는다.
writer.movieFragmentInterval = CMTime(seconds: 2, preferredTimescale: 600)
let bitRate = max(20_000_000, videoWidth * videoHeight * 4)
let videoSettings: [String: Any] = [
    AVVideoCodecKey: AVVideoCodecType.hevc,
    AVVideoWidthKey: videoWidth, AVVideoHeightKey: videoHeight,
    AVVideoCompressionPropertiesKey: [
        AVVideoAverageBitRateKey: bitRate,
        AVVideoExpectedSourceFrameRateKey: 60,
        AVVideoMaxKeyFrameIntervalKey: 60
    ] as [String: Any]
]

보통 동영상 파일은 맨 마지막에 목차를 써야 완성됩니다. 녹화 중에 앱이 죽으면 목차가 없어서 파일 전체가 열리지 않습니다. movieFragmentInterval = 2초는 2초마다 작은 목차를 붙이라는 뜻이고, 그러면 죽어도 직전 2초까지는 멀쩡히 재생됩니다.

소스 주석에 이 원칙이 한 줄로 적혀 있습니다: "시작된 녹화는 조용히 버려지지 않는다." 같은 원칙이 저장 위치에도 적용돼 있어서, 녹화 폴더는 임시 폴더가 아니라 ~/Library/Application Support에 만들어집니다 — OS가 임시 폴더를 청소하다 영상을 지우는 일을 막기 위해서입니다.

패턴 ④ 좌표계를 하나로 고정하고, 화면은 "카메라"로 본다

주석(화살표·사각형·블러 등)의 좌표를 어디에 맞출 것인가는 이런 편집기의 최대 설계 결정입니다. Screendrop의 답은 Engine/Shape.swift 주석에 있습니다.

이 선택의 보상이 주석에 그대로 적혀 있습니다 — "캔버스가 그 위의 순수한 카메라가 되고, 그래서 모든 도구가 같은 회전/크기조절 동작을 공짜로 얻는다." 도구를 새로 추가할 때 회전·크기조절 코드를 다시 안 짜도 된다는 뜻입니다.

흥미로운 건 같은 앱 안에서 녹화 쪽은 반대로 0~1 정규화를 씁니다. 커서 좌표(input.json)는 나중에 1080p로도 4K로도 렌더링될 수 있으니 해상도에 독립적이어야 하거든요. 규칙을 통일한 게 아니라, 각 데이터가 살아갈 미래에 맞춰 다르게 정한 것입니다.

패턴 ⑤ 되돌리기를 두 가지 방식으로 구현했다

private func applyClipTimeline(_ requested: RecordingClipTimeline, ...,
                               actionName: String) {
    let next = requested.normalized(to: sourceDuration)
    guard !next.segments.isEmpty, next != clipTimeline else { return }
    let previousTimeline = clipTimeline          // 이전 값을 붙잡아 두고
    let previousSelection = selectedClipID
    registerUndo(actionName) { target in         // 그 값으로 자기 자신을 다시 호출
        target.applyClipTimeline(previousTimeline, selectedID: previousSelection, ...)
    }
    clipTimeline = next
}

등록한 클로저가 같은 함수를 다시 부르기 때문에, 되돌리기를 실행하는 순간 "다시 실행(redo)"이 자동으로 등록됩니다. 한 함수로 undo/redo가 둘 다 되는 구조입니다. 한 앱 안에 두 방식이 공존하니 비교 학습 자료로 드물게 좋습니다.

패턴 ⑥ 녹화 한 건 = 폴더 한 개 (자체 포맷)

static let directoryExtension    = "screendroprec"
static let screenFileName       = "screen.mov"      // 화면
static let cameraFileName       = "camera.mov"      // 웹캠
static let pointerCaptureFileName = "input.json"    // 커서·키 입력 기록
static let captureManifestFileName = "capture.json" // 촬영 당시 설정
static let editDocumentFileName = "edit.json"       // 저장한 편집 내용
static let draftDocumentFileName = "edit.draft.json"// 자동 저장 (별도!)
static let renderStampFileName  = "render.json"     // 내보낸 파일이 최신인지 증명
static let posterFileName       = "poster.jpg"      // 썸네일

맥의 .rtfd나 .pages처럼 겉으론 파일 하나로 보이지만 실제로는 폴더인 구조입니다. 애플이 제공하는 NSDocument/FileWrapper를 안 쓰고 FileManager로 직접 만들었습니다.

여기서 눈여겨볼 세 가지:

• edit.draft.json과 edit.json을 분리 — 자동 저장과 "저장 버튼 눌러 저장"을 다른 파일에 씁니다. 편집 중 크래시해도 잃는 게 없고, 저장 안 한 상태는 저장 안 한 상태로 남습니다.
• render.json은 캐시 무효화 도장 — 내보낸 mp4가 지금 편집 내용과 일치하는지를 해시나 수정시각이 아니라 값 비교로 판정합니다. 같으면 재사용, 다르면 다시 렌더.
• 앱 종료 직전 flushDrafts() — 끄기 전에 초안을 전부 디스크에 밀어 넣습니다.

5디렉토리 구조 해부

파일 크기 순위 — 어디에 살이 붙어 있는가

이어서 AnnotationCanvas.swift(769) · Engine/AnnoEditorInteraction.swift(717)가 붙습니다. 2천~3천 줄짜리 파일이 상위에 있는 게 눈에 띌 겁니다. 교과서적 MVVM이라면 RecordingStudioModel 하나를 열댓 개로 쪼갰을 텐데, 이 프로젝트는 편집기 창 하나당 "만능 객체" 하나로 갑니다. 재생·자르기·속도·줌·자막·필러 제거·내보내기·공유가 전부 그 안에 있습니다.

Go 릴리스 도구가 하는 일 (992줄 단계별)

runCmdRetry라는 헬퍼가 네트워크가 필요한 단계들을 재시도로 감쌉니다. 그리고 이 도구의 존재 이유가 release-screendrop/SKILL.md에 적혀 있습니다 — "채팅 세션에서 바로 릴리스를 낼 수 있도록". 사람이 아니라 AI 에이전트가 실행할 것을 전제로 설계된 릴리스 파이프라인입니다.

먼저 읽으면 좋은 순서

1. ScreendropApp.swift (220줄) — 앱 전체 구조가 한 화면에 들어온다
2. ScreenshotManager.swift — 2장의 "왜 ScreenCaptureKit을 안 쓰나" 주석을 원문으로
3. PreviewWindowCaptureExclusion.swift — 가장 짧고 가장 놀라운 파일 (아래 6장)
4. Engine/Shape.swift — 좌표계 결정과 그 근거
5. RecordingSession.swift — 폴더 번들 포맷 정의
6. CloudCredentialStore.swift — 키체인 사용법의 교과서적 예시

6학습 포인트 (기술별)

① 한 줄짜리 마법 — 내 창을 화면 캡처에서 빼기

화면 녹화 앱의 고전적 문제: 녹화하는 앱 자신의 UI가 녹화 화면에 찍힙니다. 미리보기 카드, 녹화 컨트롤바 같은 것들이요. Screendrop의 해결책 전부가 이 한 줄입니다.

private func applyCaptureVisibility(to window: NSWindow) {
    window.sharingType = Self.includesAppWindowsInCaptures ? .readOnly : .none
}

NSWindow.sharingType = .none은 시스템에게 "이 창은 화면 공유·녹화 대상에서 빼 달라"고 말하는 속성입니다. ScreenCaptureKit 쪽에서 필터로 걸러낼 필요도, 좌표를 계산해 잘라낼 필요도 없습니다. 화면 녹화 도구를 만들 때 이걸 모르면 며칠을 헤맵니다.

② 2001년 API가 아직도 정답인 자리 — 전역 단축키

Screendrop은 캡처 단축키에 Carbon을 씁니다. 2001년에 나온 C API이고, 애플이 "레거시"라 부르지만 권한 없이 키를 가로챌 수 있는 유일한 방법이라 2026년에도 표준입니다. C 콜백에서 Swift 객체를 되찾는 방식이 볼 만합니다.

// 등록할 때: self의 주소를 그냥 포인터로 넘긴다
Unmanaged.passUnretained(self).toOpaque()

// C 콜백 안에서: 그 포인터를 다시 Swift 객체로 되돌린다
let manager = Unmanaged<HotkeyManager>.fromOpaque(userData).takeUnretainedValue()
manager.handleHotKey(id: hotKeyID.id)

한편 키 입력 자막 기능은 어떤 키를 눌렀는지 표시만 하면 되므로 가로챌 필요가 없고, 대신 모든 키를 봐야 하니 CGEventTap과 NSEvent 모니터를 둘 다 켭니다. 그러면 같은 키가 두 번 들어오는데, 이걸 이렇게 처리합니다.

/// 같은 물리 키 입력이 CGEventTap과 NSEvent 모니터 양쪽에서 도착할 수 있다.
/// duplicateEventWindow 안의 중복은 버린다.
private var lastProcessedEventTimes: [Int: TimeInterval] = [:]
private static let duplicateEventWindow: TimeInterval = 0.05

③ 키체인 쓰는 법 — 30줄이면 끝난다

private static func setKeychainItem(key: String, value: String) {
    let data = Data(value.utf8)
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrAccount as String: key,
        kSecAttrService as String: keychainService,
    ]
    SecItemDelete(query as CFDictionary)        // 있으면 지우고
    var newQuery = query
    newQuery[kSecValueData as String] = data
    SecItemAdd(newQuery as CFDictionary, nil)   // 새로 넣는다 (update보다 단순)
}

"수정"이라는 개념 없이 지우고 다시 넣습니다. SecItemUpdate는 항목이 있는지 먼저 확인해야 해서 분기가 늘어나는데, 삭제는 없어도 에러가 아니라서 이 방식이 더 짧고 안전합니다.

중요한 건 무엇을 어디 넣었는가입니다: 업로드 토큰(비밀) → 키체인, Worker 주소(비밀 아님) → UserDefaults. 비밀만 금고에 넣습니다. 전부 키체인에 넣으면 느려지고 디버깅이 괴로워집니다.

④ 외부 프로그램 실행 시 절대 잊으면 안 되는 것

49,605줄 전체에서 Process()를 쓴 곳은 딱 2곳입니다 — screencapture와, 배경 이미지 팩을 푸는 /usr/bin/ditto. 그 두 번째에 교훈이 하나 붙어 있습니다.

그리고 비동기 처리 방식도 볼 만합니다 — Process는 옛날 블로킹 API인데, 이걸 async/await 세계로 끌어올리는 표준 다리가 withCheckedContinuation입니다.

return await withCheckedContinuation { continuation in
    DispatchQueue.global(qos: .userInitiated).async {
        let process = Process()
        process.executableURL = URL(fileURLWithPath: "/usr/sbin/screencapture")
        process.arguments = args + ["-x", "-t", "png", filePath]
        try? process.run()
        process.waitUntilExit()
        continuation.resume(returning: process.terminationStatus == 0
            ? URL(fileURLWithPath: filePath) : nil)
    }
}

⑤ 왜 딱 한 클래스만 옛날 방식(Combine)을 쓰는가

앱 전체가 @Observable인데 UpdaterManager 하나만 ObservableObject + Combine입니다. 실수가 아닙니다 — Sparkle이 canCheckForUpdates를 KVO(옛날 Objective-C 관찰 방식)로 노출하기 때문이고, KVO를 Swift 값으로 바꾸는 다리가 Combine의 .publisher(for:)입니다. "낡은 걸 남겨 둔 게 아니라, 외부 라이브러리와 맞닿은 한 지점에만 남긴 것"입니다.

⑥ 주석 엔진의 출처 — 이 폴더는 통째로 재사용품이다

Engine/ 29개 파일의 헤더 주석에 출처가 적혀 있습니다: "드로잉 앱의 Model/Shape.swift에서 이식, 화이트보드엔 없는 도구(가리기·스포트라이트·번호 콜아웃)까지 넓힘." 저자가 예전에 만든 별도 프로젝트의 2D 벡터 엔진을 통째로 가져와 확장한 것입니다.

그 안에는 perfect-freehand(tldraw·Excalidraw가 쓰는 필압 자유곡선 알고리즘)의 Swift 포팅도 있습니다 — thinning·smoothing·streamline 같은 필드명과 펜 감속 공식 t*0.65 + sin(t*π/2)*0.35가 그대로 남아 있어 확인됩니다.

⑦ 픽셀에 직접 그리는 영상 합성

최종 내보내기(RecordingStudioExporter.swift)는 AVVideoComposition이나 Core Animation 레이어를 쓰지 않습니다. CVPixelBuffer의 메모리 주소를 잠그고 거기에 직접 픽셀을 씁니다. 화면·웹캠·가짜 커서·키 입력 자막·자막·줌 화면을 프레임마다 손으로 합칩니다.

튜토리얼에서는 거의 안 나오는 저수준 기법입니다. 대신 합성 규칙을 100% 내 마음대로 정할 수 있습니다 — 프레임워크가 지원하지 않는 효과라도 넣을 수 있죠. 대가는 성능·정확도를 전부 직접 책임진다는 것.

7하드웨어 / 시스템 요구사항

배포된 앱을 처음 열면 "확인되지 않은 개발자" 경고가 뜰 수 있습니다. 앱을 우클릭 → 열기, 또는 시스템 설정 → 개인정보 보호 및 보안에서 허용하면 됩니다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

이 프로젝트

• fayazara/Screendrop — 저장소 본체
• fayazara/screendrop-worker — 공유용 Cloudflare Worker (별도 저장소, "Deploy to Cloudflare" 버튼 있음)
• 최신 릴리스 — DMG 직접 내려받기
• appcast.xml — 릴리스 이력의 진짜 원본 (README보다 정확)

저장소 안에서 먼저 읽을 파일

• Screendrop/ScreendropApp.swift (220줄) — 전체 구조가 한 화면에
• Screendrop/PreviewWindowCaptureExclusion.swift — 가장 짧고 가장 놀랍다
• Screendrop/ScreenshotManager.swift — "왜 ScreenCaptureKit이 아닌가" 주석 원문
• Screendrop/Engine/Shape.swift — 좌표계를 왜 픽셀로 고정했는지
• Screendrop/RecordingSession.swift — 폴더 번들 포맷 정의
• cmd/screendrop-release/main.go (992줄) — 배포 자동화의 실물
• .agents/skills/macos-notch-ui/ — 다른 앱에 그대로 옮겨 쓸 수 있는 레시피

애플 공식 문서

• ScreenCaptureKit · AVAssetWriter
• MenuBarExtra · NSPanel
• NSWindow.SharingType — 6장 ①의 근거
• Keychain Services
• 공증(notarization) 가이드

배경 지식 · 비교해 볼 저장소

• Sparkle — 맥 자동 업데이트 표준
• Cloudflare R2 · D1 — 12주차 실습용
• wulkano/Kap — 같은 카테고리의 Electron 대안. 네이티브와 비교해 볼 것
• steipete/Peekaboo 등 맥 캡처 계열 저장소 — 같은 문제를 다르게 푼 예시 모으기
• perfect-freehand — Engine/의 자유곡선 알고리즘 원본(JS)