screencast-desktop

**Claude Code 플러그인으로, 에이전트가 Windows 애플리케이션을 조작하고 그 세션을 완성된 데모 비디오로 변환합니다 — 카메라가 클릭이 발생하기 0.5초 전에 각 클릭 지점으로 줌인하기 시작합니다.**

• 비전을 루프에 넣고 데스크톱을 제어합니다. 모든 작업은 동일한 응답에서 새로운 스크린샷을 반환하므로 에이전트는 스크립트를 맹목적으로 작성하는 대신 보기 → 행동 → 보기 방식으로 작업합니다. 컨트롤은 Windows UI Automation을 통해 이름으로 찾습니다. 컨트롤 트리를 노출하지 않는 Electron 앱은 스크린샷과 좌표(또는 디버깅 포트가 열려 있을 때 CDP를 통한 DOM)로 대체됩니다.

• 화면이 아닌 창을 녹화합니다. 캡처는 Windows Graphics Capture를 통해 창 핸들에 바인딩되므로 앱 뒤의 데스크톱은 프레임에 들어가지 않으며 창이 어떤 모니터나 GPU에 있는지는 중요하지 않습니다.

• 비디오는 푸티지가 아닌 이벤트 로그에서 만들어집니다. 모든 클릭, 입력된 문자열, 전체 커서 경로는 발생 시점에 타임스탬프가 기록됩니다. 카메라 이동은 해당 로그에서 계산됩니다.

• Screen Studio급 마감, 생성됨: 이징된 카메라 푸시와 팬, 부드러운 그림자가 있는 그려진 커서, 클릭 리플, 모션 블러, 그라데이션 배경 위의 둥근 모서리, 비네트와 그레인 — 그리고 에이전트의 사고 시간을 제거하는 데드 에어 제거.

• 비트에 맞는 내레이션. 선택적 ElevenLabs 음성 해설은 실행 전에 생성되어 클릭이 해당 문장 안에 떨어지도록 합니다.

• 한 스크립트로 더 풍부한 몽타주 레이어. 타이틀 및 아웃트로 카드, 캡션, 완전한 사운드 디자인 패스(클릭 트랙, 카메라 우쉬, 착지 임팩트, 클로징 라이저, 덕킹된 음악 베드, 라우드니스 정규화)는 cinematic.py, sfx.py, sfx_bank.py에 있습니다. 이들은 desktop_render 도구가 아닌 server/make_showcase.py에 의해 구동됩니다. 알려진 제한 사항을 참조하세요.

• 무료로 재렌더링. 렌더링은 애플리케이션을 건드리지 않습니다: 줌 캡, 내레이션 또는 효과를 변경하고 동일한 테이크를 원하는 만큼 재구축하세요.

왜 다른가

"자동 줌"을 하는 모든 화면 녹화기(Screen Studio 및 Windows 모방 제품)는 동일한 방식으로 작동합니다: 먼저 녹화한 다음 마우스 후크 또는 푸티지 자체를 다시 검토하여 흥미로운 순간이 어디였는지 추측합니다. 이 순서에는 아무도 해결할 수 없는 엄격한 결과가 있습니다: 줌은 클릭 전에 시작할 수 없습니다. 클릭 순간에 녹화기는 클릭이 오고 있다는 것을 방금 알았기 때문입니다. 최선의 경우 클릭 시 이동을 시작하고 잠시 후 도착합니다. 인간 편집자는 반대를 합니다 — 시청자를 먼저 이끌어서 버튼을 누를 때 눈이 이미 버튼에 있도록 합니다.

여기서 에이전트는 작업을 생성하므로 좌표와 타이밍은 단일 프레임이 합성되기 전에 알려집니다. 카메라에 리드인(server/camera.py의 LEAD_IN = 0.55 s)을 줄 수 있으므로 버튼을 누를 때 촬영이 이미 도착하고 안정화됩니다. 동일한 사전 지식은 사후 도구가 가질 수 없는 세 가지를 더 제공합니다:

• 펌핑 없음. 같은 영역에서 연속 클릭은 카메라가 모든 목록 항목에 대해 줌인/아웃하는 대신 하나의 안정된 촬영으로 병합됩니다.

• 맞는 내레이션. 음성은 실행 전에 생성되고(voice.plan()), 실제 지속 시간은 ffprobe로 측정되며, 에이전트의 일시 중지는 해당 숫자에서 설정됩니다 — 따라서 클릭은 설명하는 문장 안에 떨어지며 수동 조정이 필요 없습니다. 먼저 녹화하고 나중에 내레이션하면 항상 "저장을 클릭합니다"라는 음성이 저장이 이미 클릭된 1초 후에 나옵니다.

• 무슨 일이 있었는지에 대한 기계 판독 가능한 기록. desktop_describe_take는 테이크를 번호가 매겨진 절차("3. [12.4s] Multiply by 클릭")로 다시 읽습니다 — 스크린샷 더미보다 나은 산출물이며 재사용 가능한 스킬을 작성하기에 충분합니다.

이웃들 사이의 위치

아이디어는 모호하지 않습니다 — Windows에서 도달하기 어려울 뿐입니다. "액션 로그에서 편집"을 구현하는 네 개의 브라우저 측 프로젝트(argo, testreel, pagecast, playwright-recast)가 2026년 3월 2주 이내에 나타났습니다. Playwright가 로그를 무료로 제공하기 때문입니다. Windows에서는 로그를 입력 드라이버와 함께 구축해야 하며, 같은 5개월 동안 아무것도 나타나지 않았습니다: 녹화기에는 에이전트가 없고, 에이전트는 프레임을 생성하지 않습니다.

Related MCP server: windows-gui-mcp

요구 사항

Python 패키지

server/의 모든 모듈에서 가져온 것들:

pip install mcp pillow opencv-python numpy windows-capture uiautomation

개인 정보 보호 스캔에는 패키지가 필요 없습니다: Windows에 내장된 OCR을 PowerShell을 통해 사용하여 화면을 읽습니다.

설치

1. 플러그인 가져오기

git clone https://github.com/JHamidun/screencast-desktop.git

2. Claude Code에 등록

저장소는 자체 마켓플레이스(.claude-plugin/marketplace.json)이므로 Claude Code를 클론에 지정하고 거기서 설치합니다:

/plugin marketplace add <path-to-clone>
/plugin install screencast-desktop

.mcp.json은 두 서버를 ${CLAUDE_PLUGIN_ROOT}-상대 경로로 등록하므로 전역 설치가 필요 없고 클론은 어디에나 있을 수 있습니다.

3. 설정 실행

/screencast-desktop:setup

이것은 server/doctor.py를 실행하며, 조용히 실패하는 것들을 확인합니다:

• DPI 인식 — DPI 인식으로 선언되지 않은 프로세스는 실제로 3840×2160일 때 화면이 2560×1440이라고 알려주며 모든 클릭이 배율만큼 빗나갑니다.

• 모니터 레이아웃 — 좌표는 모든 화면에서 공유되며 보조 모니터에서는 음수가 됩니다.

• ffmpeg 및 사용 가능한 인코더.

• 창 캡처, 실제로 — 약 25프레임을 캡처하고 모두 동일하지 않은지 확인합니다.

• 내레이션 — 키가 있는지, 구성된 음성 ID가 계정에 여전히 존재하는지(삭제된 음성은 그렇지 않으면 404로 실패).

발견한 내용으로 machine.json을 작성합니다.

4. UI Automation 바이너리 가져오기

windows-ui 서버는 외부 바이너리입니다 — sbroenne/mcp-windows(MIT). 이 저장소에 의도적으로 포함되지 않았습니다: 약 60MB이고 다른 사람의 프로젝트이며 여기에 고정하면 오래된 버전만 배포될 것입니다. 요청 시 다운로드하세요:

python server/fetch_ui_binary.py          # --force to re-download

스크립트는 최신 GitHub 릴리스를 확인하고, 게시된 SHA256SUMS.txt와 아카이브를 검증하며, 불일치 시 아무것도 설치하지 않습니다. .mcp.json이 기대하는 bin/에 배치됩니다.

5. 두 서버가 모두 실행 중인지 확인

claude mcp list      # expect: screencast, windows-ui

빠른 시작

Windows 계산기 데모를 녹화합니다. /screencast-desktop:record 명령은 에이전트를 안내하지만, 실제 도구 이름으로 실제로 수행하는 작업은 다음과 같습니다.

1 — 창을 배치합니다. 보조 모니터가 있으면 거기에 배치하여 작업 위에 놓이지 않도록 합니다:

desktop_monitors()
desktop_place_window(window="Calculator", monitor=1, fit=0.7)

응답을 읽으세요. 애플리케이션은 지시된 크기가 될 의무가 없습니다 — 여기서 2380×1490을 요청한 UWP 창은 3967×2426으로 돌아와 화면 밖으로 나갔습니다. desktop_place_window는 결과를 측정하고 수정하며 창이 맞는지 명확히 말합니다.

2 — 프레임에 개인 정보가 없는지 확인합니다.

desktop_screenshot(window="Calculator")
desktop_privacy_check(window="Calculator")

검사는 보고만 하며 차단하지 않습니다: 프레임을 OCR하고 카드 번호, API 키, 이메일 주소, 전화번호 및 개인 이름을 표시합니다. 녹화 전에 방해 금지 모드를 켜세요.

3 — 리허설. 실제 도구로 경로를 이동하고 반환된 스크린샷에서 의도한 대상을 누르고 있는지 확인합니다. 아직 아무것도 녹화되지 않습니다:

ui_snapshot(windowHandle=…)          # windows-ui: controls by name — try this first
desktop_snapshot(window="Calculator")# or the built-in UIA walk, which returns e1, e2, … refs
desktop_click(ref="e7")

4 — 앱을 재설정합니다. 리허설에서 열린 검색 상자가 테이크에 남게 됩니다.

5 — 실제 녹화.

desktop_record_start(window="Calculator")
desktop_click(ref="e12")                 # every click from here is logged for the camera
desktop_type("128")
desktop_click(ref="e19")
desktop_record_stop()

desktop_record_stop은 지속 시간, 프레임 수 및 로그에 포함된 클릭 수를 보고한 다음 렌더링할 out_dir을 알려줍니다.

6 — 렌더링한 다음 확인합니다.

desktop_render(out_dir="%USERPROFILE%/screencasts/take-143502", max_zoom=2.0)
desktop_render_status(out_dir="…")       # rendering runs in a child process

파일을 열고 눈으로 직접 확인하세요: 카메라가 있어야 할 곳에 도착했는지, 어느 가장자리에 검은 막대가 있는지, 커서가 보이는지. 잘못된 좌표는 카메라가 아무것도 보지 못하는 기술적으로 유효한 파일을 만들어 냅니다. 위치가 어긋나 있다면 desktop_render를 다른 설정으로 다시 실행하세요. 애플리케이션이 다시 시작되거나 화면이 다시 녹화되지는 않습니다.

도구 참조

screencast 서버 — desktop_monitors, desktop_windows, desktop_screenshot, desktop_snapshot, desktop_dom, desktop_dom_launch, desktop_click, desktop_type, desktop_key, desktop_move_mouse, desktop_scroll, desktop_focus, desktop_launch, desktop_place_window, desktop_privacy_check, desktop_record_start, desktop_record_stop, desktop_render, desktop_render_status, desktop_describe_take.

desktop_click, desktop_type, desktop_key, desktop_scroll, desktop_focus 및 desktop_launch는 모두 see="shot"(기본값) 또는 see="none"을 받습니다. 후자는 화면의 모양을 이미 알고 있을 때 컨텍스트를 절약합니다.

windows-ui 서버 (노출된 하위 집합) — ui_snapshot, ui_find, ui_click, ui_type, ui_select, ui_read, ui_wait, window_management, app.

작동 방식

터미널에서 읽는 사람을 위해, 같은 내용을 텍스트로 나타내면:

  AGENT                                                   server/
  ─────                                                   ───────
  desktop_click / desktop_type / …                        desktop_server.py
        │                                                 (MCP, FastMCP)
        ├──► real SendInput: cursor eased to the target,  driver.py
        │    clicked, keys sent                           ── moves + clicks
        │                                                    the real desktop
        │
        ├──► EVENT LOG  t, kind, x, y, label, dur         driver.py → events.json
        │    + the sampled cursor path (track)               ◄── the ground truth
        │
        └──► screenshot back to the agent in the same reply

  desktop_record_start                                    recorder_proc.py (child process)
        └──► Windows Graphics Capture, bound to the HWND  wgc.py
             ├─ frames arrive only when the picture       ── writer thread re-sends
             │  changes …                                    the last frame on a
             └─ … so a writer thread feeds ffmpeg at a       fixed clock
                constant rate, logging the true
                wall-clock time of every frame
                                                          → raw.mp4 + frame_times.json

  desktop_render                                          render_proc.py (child process)
        │
        ├─ 1. TIMELINE   collapse the dead air            timeline.py
        │      keep 1.1 s before and 1.5 s after every
        │      action, squeeze the gaps to 0.55 s
        │
        ├─ 2. CAMERA     event log → keyframes            camera.py
        │      lead-in 0.55 s BEFORE each click,
        │      nearby clicks merged into one shot,
        │      pan instead of pumping in and out
        │
        ├─ 3. COMPOSITOR one affine matrix per frame      composer.py
        │      recording on a gradient backdrop, rounded     + cinematic.py
        │      corners, drop shadow, drawn cursor, click     (vignette, grain;
        │      ripples, motion blur, breathing idle,          title cards and
        │      vignette, grain                                captions available)
        │                                                 → silent.mp4
        │
        └─ 4. SOUND      optional narration               voice.py
               ElevenLabs TTS mixed onto the cut          → demo.mp4

  make_showcase.py — the fuller montage, run as a script rather than a tool:
        the same four stages plus title/outro cards, captions, and the whole
        sound design pass (clicks, whooshes, impacts, riser, ducked music bed,
        loudness normalisation)                           sfx.py + sfx_bank.py

파일 레이아웃의 대부분은 두 가지 설계 결정으로 설명됩니다.

캡처와 렌더링은 하위 프로세스에서 실행됩니다. MCP 서버 프로세스 안에서 캡처 라이브러리나 OpenCV를 임포트하면 서버가 멈춰 버리고, 렌더링은 수 분이 걸리므로 어떤 도구 호출도 그 시간을 점유한 채 열려 있으면 안 됩니다. recorder_proc.py와 render_proc.py는 오직 그 이유 하나로 존재합니다. 이들은 파일(started.json, stop, render.log)을 통해 통신하며, 둘 다 stdin=DEVNULL로 시작됩니다. 서버의 stdin을 상속받은 하위 프로세스는 서버로 향하는 JSON-RPC 요청을 가로채 소비하기 시작합니다.

프레임은 인덱스가 아니라 타임스탬프로 매칭됩니다. 머신이 따라잡지 못하면 소스 프레임 N은 N/fps 위치에 있지 않습니다. frame_times.json은 모든 프레임의 실제 캡처 시각을 담고 있고, 컴포저는 이 파일을 통해 프레임을 조회합니다. 이 덕분에 머신이 버벅일 때도 카메라가 클릭 위치에 머물러 있습니다.

구성

렌더링

desktop_render(out_dir, name="demo.mp4", max_zoom=2.0, narration="") — narration은 {"text": …, "at": seconds} 형식의 JSON 목록을 받습니다.

그 외 모든 것은 모듈 상수이며, 해당 위치에서 직접 수정합니다.

desktop_record_start(window, out_dir="", fps=30)의 기본값은 ~/screencasts/take-HHMMSS입니다.

max_zoom을 지정하지 않으면 camera.build()가 창 높이의 최소 70%가 프레임 안에 남도록 상한을 스스로 정합니다. 16:9 프레임에 맞춘 키가 크고 좁은 창은 이미 작은데, 거기에 2배를 강제하면 동작의 의미를 보여 주는 부분이 잘려 나갑니다. (계산기에서는 결과를 표시하는 디스플레이가 잘려 나갔습니다.)

내레이션

ELEVENLABS_API_KEY를 환경 변수 또는 플러그인 루트의 .env 파일에 설정하세요(KEY=value, 한 줄에 하나 — 이 파일은 git에서 무시됩니다). 선택적으로 ELEVENLABS_VOICE_ID로 음성을 지정할 수 있습니다. 설정하지 않으면 계정의 첫 번째 음성이 사용됩니다. 모델: eleven_multilingual_v2. 키를 다른 곳에 보관한다면 SCREENCAST_ENV_FILE을 다른 위치로 지정하세요.

voice.resolve_voice()는 구성된 ID를 사용하기 전에 계정의 실제 음성 명단과 대조합니다. 그렇게 하지 않으면 삭제된 음성이 설명 없는 404 오류로 실패하기 때문입니다.

키가 없어도 아무것도 깨지지 않습니다. doctor.py는 이를 실패가 아닌 경고로 보고하며, desktop_render는 음성 없는 동영상을 생성합니다. 이는 narration 인자를 전달하지 않은 채 키가 있어도 생성되는 결과이기도 합니다.

사운드 디자인 계층은 키가 없어도 죽지 않고 저하됩니다. sfx_bank.build()는 팔레트를 생성하기 위해 ElevenLabs가 필요하지만, sfx_bank.build_synthetic()은 numpy로 동일한 계열을 오프라인에서 합성하며(*_syn1.wav / *_syn2.wav 파일), sfx.click_samples()는 샘플 에셋이 없으면 synth_click()으로 폴백합니다. 따라서 오프라인 머신에서도 클릭, 휘익, 충격음을 얻을 수 있습니다. 목소리만 잃을 뿐입니다.

알려진 제한 사항

솔직한 목록입니다. 이것들은 실제이며 현재도 사실이고, 대부분은 개발 중에 부딪힌 것들입니다. 각 항목의 배경이 되는 측정값과 함께 우선순위별 계획은 ROADMAP.md에 있습니다.

• desktop_render 도구는 코드베이스가 할 수 있는 것보다 적게 렌더링합니다. composer.compose()를 intro, outro, captions 없이 호출하고, 내레이션만 믹싱합니다. 클릭 트랙도, 휘익 소리도, 음악 배경도 없습니다. 그 외 모든 것은 구현되어 동작하지만, 현재는 자체적으로 하드코딩된 테이크 경로와 비트 목록을 가진 스크립트인 server/make_showcase.py를 통해서만 접근할 수 있습니다. 이러한 매개변수를 도구에 연결하는 것은 이 저장소에서 가장 명백한 남은 작업입니다.

• 드래그 없음. 드래그나 드래그 앤 드롭 도구가 없습니다. 마우스 다운과 마우스 업은 항상 같은 위치에서 발생하므로, 누르기-이동-놓기 제스처가 필요한 모든 것(슬라이더, 순서 변경, 캔버스 그리기, 손잡이로 크기 조정)은 사용할 수 없습니다.

• 키 입력은 이벤트 로그에 기록되지 않습니다. desktop_key는 키 입력을 보내지만 기록하지 않으므로, 카메라는 키보드만 사용하는 단계에 절대 반응하지 않으며 그러한 단계는 desktop_describe_take에 나타나지 않습니다. 클릭과 입력된 텍스트(desktop_type)는 기록되지만, 개별 키 입력은 기록되지 않습니다.

• UWP 창은 프레임 창으로 주소를 지정해야 합니다. Windows Graphics Capture는 최상위 창 핸들을 사용합니다. UWP/

이슈와 풀 리퀘스트는 환영합니다. 리뷰를 빠르게 해 주는 몇 가지 사항:

• Windows 전용입니다. 실제 데스크톱에서 테스트하세요. 여러분 대신 버튼을 클릭해 줄 CI는 없습니다.

• 먼저 doctor를 실행하세요 (python server/doctor.py) 그리고 그 출력을 버그 리포트에 붙여넣으세요 — 여기서 발생하는 대부분의 문제는 환경적인 것(DPI 배율, 모니터 배치, 인코더 누락)이며 doctor가 그 문제들을 직접 지목합니다.

• 조용히 실패했다면, 댓글로 알려주세요. 이 코드베이스는 한 줄이 왜 그렇게 되어 있는지 설명하는 주석으로 가득합니다. 거의 모든 줄이 성공처럼 보였던 실패이기 때문입니다: 녹화로 오인되는 동일한 프레임, 화면 가장자리를 벗어나는 카메라, 줌이 전혀 없는 비디오를 만들어내는 빈 이벤트 로그. 이러한 주석을 남겨 두는 것은 의도적인 것입니다.

• 카메라 또는 타임라인 상수를 변경할 때는 전후 클립이 필요합니다. 이러한 변경은 결과가 어떻게 보이는지에 대한 주관적 판단이며, 어떤 테스트도 이를 결정할 수 없습니다.