데스크톱 배경으로 동영상을 무한 루프 재생하고, 앱을 꺼도 마지막 프레임이 실제 바탕화면으로 남는 macOS 라이브 월페이퍼 앱.
Loopaper는 로컬 .mp4/.mov를 데스크톱 아이콘 레이어 아래에 끊김 없이 재생하는 메뉴바 유틸리티입니다. 종료하면 마지막 프레임을 캡처해 실제 OS 바탕화면으로 고정(Freeze)하므로, 앱이 실행 중이 아니어도 골라둔 월페이퍼가 그대로 보입니다.
Note
상태: v1 구현 완료(Phase 0–8), 출시 준비 중. 라이브 재생·Freeze·멀티모니터·전력 자동정지·UI(Library | Screens 탭 메인 창 + 화면별 Disable/복원 + 리치 메뉴바 팝오버 + 설정)·로그인 실행이 모두 구현되었습니다. 남은 것은 Developer ID 서명 + 노터라이즈(Apple Developer 자격 증명 필요)뿐이며, 자동화 스크립트는 scripts/에 준비되어 있습니다. 상세 진척은 작업 계획서를 참고하세요.
- 라이브 월페이퍼 — 화면마다 borderless
NSWindow+AVPlayerLayer를 데스크톱 아이콘 아래 배치. 아이콘은 그대로 보이고 클릭·드래그가 영상 위로 통과합니다. - Freeze — 종료 시 현재 프레임을 화면 네이티브 해상도로 사전 렌더링해 실제 바탕화면(
NSWorkspace.setDesktopImageURL)으로 고정. 라이브 크롭과 픽셀 일치. - 화면별 독립 지정 — 모니터마다 다른 월페이퍼, 또는 "모든 화면에 적용". 디스플레이를 분리·재연결·재부팅해도 안정적인
screenKey로 배정이 복원됩니다. - 자동 정지로 배터리 절약 — 가려짐(occlusion)·저전력 모드·디스플레이 잠자기를 화면별로 감지해 재생을 멈춥니다(배터리 토글은 기본 OFF).
- 로컬 라이브러리 — 번들 CC0 샘플 + 사용자가 추가한 파일. 파일 추가(드래그 앤 드롭 / 파일 선택), 이름 변경, Like, 삭제를 지원합니다. 추가 파일은 App Support로 복사 소유하므로 원본을 지워도 재생됩니다.
- YouTube에서 추가 — 링크를 붙여넣고 구간(최대 60초)을 잘라 월페이퍼로 사용합니다. 오디오 포함 여부를 고를 수 있습니다(기본 OFF). 메타데이터·다운로드·트랜스코딩에 외부 CLI 도구
yt-dlp·ffmpeg를 사용하며, 설치되어 있지 않으면 시트에 설치 명령(brew install yt-dlp ffmpeg)을 안내합니다. 개인적 용도로만 사용하세요.
세 가지 상태를 명확히 구분합니다.
| 상태 | Desktop Window | 실제 바탕화면 |
|---|---|---|
| Pause | 영상 정지(마지막 프레임 유지) | 그대로 — 즉시 재개. 전력 자동정지는 Pause로 취급 |
| Disable | 닫음 | Original Wallpaper 복원 — 앱은 상주 |
| Quit | Freeze 후 닫음 | 마지막 프레임 고정 — 앱 종료 |
Important
첫 점유는 lazy입니다. 첫 실행 시 바탕화면을 건드리지 않고 라이브러리만 엽니다. 사용자가 처음 월페이퍼를 설정하는 순간에만 해당 화면의 Original Wallpaper를 1회 백업하고 Desktop Window를 생성합니다. 백업한 원본은 Disable 시 그대로 복원됩니다.
용어 정의는 CONTEXT.md를 참고하세요(Wallpaper, Freeze, Pause, Disable, Screen, Original Wallpaper 등).
요구사항: macOS 14.0+ 와 Xcode(macOS 14 SDK 포함).
# Xcode에서 열어 Loopaper 스킴 실행
open Loopaper.xcodeproj
# 또는 커맨드라인
xcodebuild -scheme Loopaper -configuration Debug build기본 서명은 ad-hoc("Sign to Run Locally") 이라 Developer ID 인증서 없이도 빌드·실행됩니다(개발용). 메뉴바 전용(LSUIElement) 앱이라 Dock 아이콘은 없고, 상태 메뉴에서 종료합니다. 첫 실행은 바탕화면을 건드리지 않고 라이브러리만 엽니다.
배포용 서명·노터라이즈된 .dmg는 scripts/release.sh로 만들며 Apple Developer 자격 증명이 필요합니다 — 절차는 scripts/README.md를 참고하세요.
| 영역 | 선택 |
|---|---|
| 언어 / UI | Swift + SwiftUI (리치 MenuBarExtra(.window) 팝오버 / Library·Screens 탭 메인 Window / Settings), Desktop Window는 AppKit NSWindow 브리지 |
| 영상 | AVFoundation (AVQueuePlayer, AVPlayerLooper, AVPlayerLayer) |
| 화면 / 전력 | AppKit(NSScreen, NSWorkspace), CoreGraphics(CGDisplay…), IOKit(전원 소스) |
| 영속화 | UserDefaults(@AppStorage) + Codable JSON (App Support) |
| 로그인 실행 | ServiceManagement(SMAppService) |
| YouTube 가져오기 | 외부 CLI yt-dlp + ffmpeg (번들 아님 — 사용자가 설치, 예: brew install yt-dlp ffmpeg) |
| 배포 | 비샌드박스, Developer ID 서명 → 노터라이즈 → staple → .dmg |
서드파티 Swift 패키지 의존성은 없습니다(순수 Apple 프레임워크). YouTube 가져오기만 외부 CLI 도구
yt-dlp·ffmpeg를 런타임에 호출하며, 이는 앱에 번들되지 않습니다.
- 최소 OS: macOS 14.0 Sonoma
- 아키텍처: Universal (Apple Silicon + Intel)
- 번들 ID:
com.jeongsk.Loopaper
Warning
Loopaper는 샌드박스 없이 동작합니다. 종료 후 실제 바탕화면을 유지하는 핵심 기능(setDesktopImageURL)이 App Sandbox에서 금지되기 때문입니다. 그래서 Mac App Store가 아닌 Developer ID 서명 + 노터라이즈로 배포합니다. 배경은 ADR-0001을 참고하세요.
| 문서 | 내용 |
|---|---|
| docs/PRD.md | v1 제품 요구사항 (목표/비목표, 사용자 스토리, 기능 명세, 기술 스택) |
| docs/work-plan.md | Phase 0–8 구현 계획, 모듈/파일 맵, 마일스톤, 리스크 |
| docs/pre-release-checklist.md | 출시 전 수동 검증 체크리스트 + 코드 후속 |
| docs/ui/ | UI/UX 재구성 — 시안(mockup), 구현 계획, 엔진 설계, 최종 리뷰 |
| CONTEXT.md | 도메인 용어집 |
| docs/adr/ | 아키텍처 결정 기록 |
| 마일스톤 | Phase | 데모 가능 상태 | 상태 |
|---|---|---|---|
| M1 — 핵심 증명 | 0–2 | 단일 화면 라이브 월페이퍼 + 종료 후 정적 유지 | ✅ |
| M2 — 멀티/전력 | 3–4 | 멀티모니터 + 자동 정지 배터리 절약 | ✅ |
| M3 — 제품 형태 | 5–7 | UI로 라이브러리 관리·설정·로그인 실행 | ✅ |
| M4 — 출시 | 8 | 노터라이즈 DMG 배포 | ✅ 도구 완료 / 서명·노터라이즈는 자격 증명 대기 |
v1 비목표(원격 카탈로그, 잠금화면 동영상, 인앱 결제, Sparkle 자동 업데이트, 다국어)는 vNext에서 검토합니다.
이 프로젝트의 코드는 MIT License 하에 배포됩니다. © 2026 jeongsk.
번들된 샘플 영상(Loopaper/Resources/Samples/)은 코드 라이선스와 별개로 공개 도메인 / CC0입니다(예: NASA 공개 자료). 직접 추가한 월페이퍼는 각 파일의 원 출처 라이선스를 따릅니다.