v0.2.4 — 인식이 느려지던 원인 수정 · Fixes slow recognition

Recognition had become slow — several seconds to unlock — and a red "The screen is not locked" error kept appearing in the menu bar. Both had the same root cause. Fixed.

The quality gate that decides whether a camera frame is usable was checking
that Vision's face bounding box sits fully inside the frame. But ArcFace
alignment never uses the box — it solves a similarity transform from five
landmarks only (eyes, nose, mouth corners). Vision's box is generous: it
extends above the forehead, below the chin, and past the ears, so sitting
normally in front of a laptop was enough for the box alone to leave the
frame. Every one of those frames was discarded as "clipped" even though every
point alignment actually needs was comfortably inside.

In one measured unlock, 40 of 41 detected faces were thrown away this way
(mean brightness 105–151 — lighting was not the problem). Of the 5.8 s that
unlock took, more than 4 s went to discarding usable frames.

The gate now tests the five landmarks — the thing alignment actually
consumes. Genuinely clipped faces are still rejected, and FaceAligner's
own extent check remains as a second guard.

Two smaller things fell out of the same log:

• After typing the password, the app slept a fixed 0.8 s and checked once
  whether the screen had opened. If loginwindow took 0.93 s, that single check
  missed it by 130 ms, a needless retry fired, and the retry's entry guard
  then reported "not locked" — at the exact moment the unlock had
  succeeded. That is where the red menu-bar error came from. The check now
  polls every 50 ms for up to 1.6 s, and "the screen is already unlocked" is
  no longer reported as a failure — it is the outcome you wanted.
• A discarded frame no longer resets the consecutive-match counter. A blurry
  or clipped frame is not evidence of a different person; it is no evidence
  at all. The anti-swap resets (face disappears, embedding does not match)
  are unchanged.

Measured after the fix: 0 discarded frames, 1.05 s from session start to
match, 2.6 s screen-on to unlocked (5.8 s before). About 1.1 s of what remains
is macOS itself — loginwindow's own processing and the dismissal animation.

The per-second progress line in the log now records why frames were
discarded and the geometry of the last one, so the next investigation starts
from numbers rather than guesses.

▶︎ Watch the install guide (video) — start to finish, if you
would rather follow along than read.

Updating from an earlier version — download this DMG and right-click
설치 도우미 (Install Helper).command → Open. It replaces the app in place and
skips the model download; your enrolled face, password, settings, and the
Camera / Accessibility permissions all carry over.

New install — open the DMG, drag the app to Applications, then right-click
설치 도우미 (Install Helper).command → Open.

---

_{아래는 한국어 릴리스 노트입니다.}

인식이 느려져 잠금 해제에 몇 초씩 걸리고, 메뉴바에 "화면이 잠겨 있지 않습니다" 라는 빨간 오류가 자꾸 뜨던 문제를 고쳤습니다. 둘은 뿌리가 같았습니다.

카메라 프레임을 써도 되는지 거르는 품질 게이트가 Vision 의 얼굴 바운딩
박스가 프레임 안에 다 들어오는지를 봤습니다. 그런데 ArcFace 정렬은 박스를
아예 쓰지 않습니다 — 눈·코·입꼬리 5점만으로 유사변환을 풉니다. Vision 의
박스는 이마 위·턱 아래·귀 바깥까지 넉넉히 잡기 때문에, 노트북 앞에 평범하게
앉아 있어도 박스만 화면 밖으로 나갑니다. 정렬에 필요한 점은 전부 안에 있는데
그 프레임을 전부 "잘림" 으로 버리고 있었습니다.

실측 한 번에서 검출된 얼굴 41장 중 40장이 이렇게 버려졌습니다(평균 밝기
105~151 — 조명 문제가 아닙니다). 5.8초 걸린 해제 중 4초 넘는 시간이
멀쩡한 프레임을 버리는 데 들어갔습니다.

이제 게이트는 정렬이 실제로 쓰는 5점을 봅니다. 정말 잘린 얼굴은 그대로
걸러지고, FaceAligner 의 자체 검사가 한 번 더 막습니다.

같은 로그에서 작은 것 둘이 더 나왔습니다.

• 비밀번호를 넣은 뒤 0.8초를 통째로 자고 화면이 열렸는지 딱 한 번
  봤습니다. loginwindow 가 0.93초 걸리면 0.13초 차이로 놓치고 헛재시도가
  나갔는데, 재시도의 진입 가드가 그 사이 열린 화면을 보고 "잠금 상태가
  아님" 을 보고했습니다. 해제에 성공한 바로 그 순간에 실패라고 알린
  겁니다. 메뉴바의 빨간 오류가 바로 이것이었습니다. 이제 0.05초마다 최대
  1.6초까지 확인하고, "이미 열려 있음" 은 실패로 알리지 않습니다 —
  그건 원하던 결과니까요.
• 버려진 프레임이 연속 일치 카운트를 초기화하지 않습니다. 흐리거나 잘린
  프레임은 "다른 사람" 이라는 증거가 아니라 아무 증거도 아닙니다. 바꿔치기를
  막는 초기화(얼굴이 사라짐, 임베딩 불일치)는 그대로입니다.

고친 뒤 실측: 버림 0장, 세션 시작 → 일치 1.05초, 화면 켜짐 → 해제
2.6초 (고치기 전 5.8초). 남은 시간 중 1.1초쯤은 macOS 몫입니다 —
loginwindow 처리와 잠금화면이 걷히는 시간이라 앱에서 줄일 수 없습니다.

초당 한 줄 남기는 진행 로그에 버린 사유와 마지막으로 버린 프레임의 기하를
함께 적습니다. 다음에 비슷한 일이 생기면 추측이 아니라 숫자부터 보고
시작할 수 있습니다.

▶︎ 설치 가이드 영상 보기 — 글로 읽는 것보다 따라 하는 게
편하시면 이 영상 하나로 처음부터 끝까지 됩니다.

이전 버전에서 올리시는 경우 — 이 DMG 를 받아
설치 도우미 (Install Helper).command 를 우클릭 → 열기. 앱만 제자리에서
갈아끼우고 모델 내려받기는 건너뜁니다. 등록한 얼굴, 비밀번호, 설정,
카메라·손쉬운 사용 권한이 그대로 유지됩니다. 몇 초면 끝납니다.
처음 실행할 때 키체인 확인 창이 뜨면 '항상 허용' 을 눌러 주세요.

처음 설치하시는 경우 — DMG 를 열어 앱을 Applications 로 끌어 넣은 뒤,
설치 도우미 (Install Helper).command 를 우클릭 → 열기.

---

SHA-256 (FaceUnlock.dmg)

4514d662538cc973b3886bdebcf276c9521a7129e6f3d5e7cbc2a367fd89f59b

맥북에서 되던가요? 혼자서는 확인할 수 없는 부분입니다. 되든 안 되든
Discussions에 한 줄
남겨주시면 큰 도움이 됩니다 — 어떤 모델인지가 제일 중요합니다.

쓸 만하셨다면 저장소에 ⭐ 하나 눌러주시면 정말 도움이 됩니다. 깃허브는 별
개수로 검색과 목록 노출이 정해지는 구조라, 0개면 필요한 사람이 검색해도 찾을
수가 없습니다.

v0.2.3 — v0.2.2 회귀 수정 · Fixes a v0.2.2 regression

Fixes a regression introduced in v0.2.2. If you are on v0.2.2, please update.

v0.2.2 fixed the check that decides whether any display is awake, so the camera
watchdog would stop retrying while the screen is off. That part works — but it
exposed a second problem underneath it.

The screen-lock signal sometimes arrives after the screen has already gone
dark. The camera warm-up would then reopen the device, receive no frames at all
(the screen is off), and simply hold on to it. Before v0.2.2 the watchdog gave up
after three attempts and closed the session; with the new guard in place it waited
indefinitely instead. In one measured run it held the camera for 39 seconds while
the Mac fell asleep, and the stale session then cost an extra 800 ms to reopen on
wake — the warm-up was making things slower, not faster.

Now the warm-up simply does not start when the screen is already off. Opening the
screen starts the camera anyway.

Measured after 5 minutes of sleep: zero device reopens, 1995 ms from screen-on to
unlocked (2594 ms before this fix). Of that, roughly 1.5 s is macOS itself — the
camera's cold start and the lock screen's own dismissal animation.

▶︎ Watch the install guide (video) — start to finish, if you
would rather follow along than read.

Updating from an earlier version — download this DMG and right-click
설치 도우미 (Install Helper).command → Open. It replaces the app in place and
skips the model download; your enrolled face, password, settings, and the
Camera / Accessibility permissions all carry over.

New install — open the DMG, drag the app to Applications, then right-click
설치 도우미 (Install Helper).command → Open.

---

_{아래는 한국어 릴리스 노트입니다.}

v0.2.2 에서 생긴 문제를 고쳤습니다. v0.2.2 를 쓰고 계시면 올려 주세요.

v0.2.2 는 "켜진 화면이 있는지" 판정하는 코드를 고쳐서, 화면이 꺼진 동안
카메라 재시도를 멈추게 했습니다. 그 부분은 잘 동작합니다 — 그런데 그 밑에
가려져 있던 문제가 드러났습니다.

잠금 신호가 화면이 꺼진 뒤에 오는 경우가 있습니다. 그때 예열이 카메라를
다시 열면, 화면이 꺼져 있으니 프레임은 한 장도 오지 않고 장치만 붙잡고 있게
됩니다. v0.2.2 이전에는 감시 루틴이 세 번 시도하고 포기하면서 세션을
닫았는데, 새 가드가 들어가면서 포기 대신 무한정 기다리게 됐습니다. 실측에서는
카메라를 39초 동안 쥔 채로 맥이 잠들었고, 깨어나 보니 그 세션이 상해서 장치를
다시 여는 데 800ms 를 더 썼습니다. 예열이 오히려 느리게 만든 셈입니다.

이제 화면이 이미 꺼져 있으면 예열을 아예 시작하지 않습니다. 화면이 켜지면
어차피 카메라를 엽니다.

5분 절전 후 실측: 장치 재개방 0회, 화면 켜짐 → 잠금 해제 1995ms
(고치기 전 2594ms). 이 중 1.5초쯤은 macOS 몫입니다 — 카메라 콜드 스타트와
잠금화면이 걷히는 시간이라 앱에서 줄일 수 있는 부분이 아닙니다.

▶︎ 설치 가이드 영상 보기 — 글로 읽는 것보다 따라 하는 게
편하시면 이 영상 하나로 처음부터 끝까지 됩니다.

이전 버전에서 올리시는 경우 — 이 DMG 를 받아
설치 도우미 (Install Helper).command 를 우클릭 → 열기. 앱만 제자리에서
갈아끼우고 모델 내려받기는 건너뜁니다. 등록한 얼굴, 비밀번호, 설정,
카메라·손쉬운 사용 권한이 그대로 유지됩니다. 몇 초면 끝납니다.
처음 실행할 때 키체인 확인 창이 뜨면 '항상 허용' 을 눌러 주세요.

처음 설치하시는 경우 — DMG 를 열어 앱을 Applications 로 끌어 넣은 뒤,
설치 도우미 (Install Helper).command 를 우클릭 → 열기.

---

SHA-256 (FaceUnlock.dmg)

dc97bb940c4f9f665fbe72259d4f4c089dc11561dda8413ebe73f70557b942e6

맥북에서 되던가요? 혼자서는 확인할 수 없는 부분입니다. 되든 안 되든
Discussions에 한 줄
남겨주시면 큰 도움이 됩니다 — 어떤 모델인지가 제일 중요합니다.

쓸 만하셨다면 저장소에 ⭐ 하나 눌러주시면 정말 도움이 됩니다. 깃허브는 별
개수로 검색과 목록 노출이 정해지는 구조라, 0개면 필요한 사람이 검색해도 찾을
수가 없습니다.

v0.2.2 — 덮개를 열자마자 반응합니다 · Instant response on lid-open

⚠️ 이 버전은 내렸습니다 — v0.2.3 을 받아 주세요.
화면이 꺼진 뒤 잠금 신호가 오면 예열이 카메라를 놓지 않고 붙잡는 문제가
있었습니다. v0.2.3 에서 고쳤습니다. (다운로드 0건 — 받아 가신 분은 없습니다.)

⚠️ Withdrawn — please use v0.2.3 instead.

---

The lock screen now responds the moment you open the lid.

Feedback from a testing group: "it feels slow — the password field only shows up
about a second after opening the lid." That was accurate, and there were two
causes behind it.

• The camera warm-up never actually worked. When the screen turns off,
  FaceUnlock is supposed to stop retrying the camera. The check that decides
  whether any display is awake treated "the call failed" and "zero displays are
  awake" as the same thing, and counted both as awake. Closing a MacBook lid
  removes the built-in display from the list entirely — so the count really is
  zero, and the guard never fired. The watchdog burned through its whole reopen
  budget and gave up, meaning every lid-open paid for a cold camera start.
• Nothing summoned the password field until recognition had finished. The
  macOS lock screen shows only a clock until it receives a keystroke, and the
  first keystroke it got was the beginning of the password injection. Now a
  single Shift is sent as soon as the recognition window opens, so the field is
  already up and focused while your face is being matched. Shift is used because
  it types nothing, and the screen-lock state is verified before sending it.

Unlocking itself is also more reliable: across repeated lid-open tests, password
injection completed in ~340 ms every time with no retries. Previously a failed
first attempt could push a single unlock past five seconds.

Already have FaceUnlock installed? You do not need to start over. Download
this DMG and right-click 설치 도우미 (Install Helper).command → Open, exactly
as before. It replaces the app in place and skips the model download — your
enrolled face, password, settings, and the Camera / Accessibility permissions all
carry over, because everything but the app itself lives outside the app bundle.
The whole thing takes a few seconds. If a Keychain prompt appears on first
launch, choose "Always Allow".

New install — open the DMG, drag the app to Applications, then right-click
설치 도우미 (Install Helper).command → Open.

---

_{아래는 한국어 릴리스 노트입니다.}

덮개를 여는 즉시 잠금화면이 반응합니다.

테스트해 주신 분들의 의견이었습니다 — "느리다. 덮개를 열면 1초쯤 지나서야
비밀번호 창이 뜬다." 정확한 지적이었고, 원인이 둘이었습니다.

• 카메라 예열이 사실상 한 번도 동작하지 않았습니다. 화면이 꺼지면
  카메라 재시도를 멈춰야 하는데, "켜진 화면이 있는지" 판정하는 코드가
  호출 실패와 켜진 화면 0개를 같은 것으로 보고 둘 다 "켜져 있다"로 셌습니다.
  맥북 덮개를 닫으면 내장 화면이 목록에서 아예 빠져 개수가 정말 0이 되므로,
  그 가드가 한 번도 걸리지 않았습니다. 결국 감시 루틴이 재시도 예산을 전부
  소진하고 포기해서, 덮개를 열 때마다 카메라를 맨바닥에서 다시 켜야 했습니다.
• 인식이 끝나기 전까지 비밀번호 칸을 띄우는 것이 없었습니다. macOS 잠금화면은
  키 입력을 받기 전까지 시계만 보여주는데, 지금까지 그 첫 입력 역할을
  비밀번호 주입의 맨 앞 글자가 했습니다. 이제 인식 창이 열리는 순간 Shift 를
  한 번 보내, 얼굴을 대조하는 동안 칸이 이미 떠 있고 커서도 들어가 있습니다.
  Shift 를 쓰는 이유는 글자를 넣지 않는 키이기 때문이고, 보내기 전에 화면이
  잠겨 있는지 먼저 확인합니다.

해제 자체도 안정적이 되었습니다. 덮개 열기를 반복한 실측에서 비밀번호 주입이
매번 약 340ms 에 끝났고 재시도가 한 번도 없었습니다. 이전에는 첫 시도가
실패하면 한 번 해제하는 데 5초를 넘기는 경우가 있었습니다.

이미 쓰고 계시다면 처음부터 다시 설치하지 않으셔도 됩니다.
이 DMG 를 받아 설치 도우미 (Install Helper).command 를 우클릭 → 열기,
전과 똑같이 하시면 됩니다. 앱만 제자리에서 갈아끼우고 모델 내려받기는
건너뜁니다 — 등록한 얼굴, 비밀번호, 설정, 그리고 카메라·손쉬운 사용 권한이
그대로 유지됩니다. 앱 자체를 뺀 나머지가 전부 앱 바깥
(~/Library/Application Support/FaceUnlock, 키체인)에 있기 때문입니다.
몇 초면 끝납니다. 처음 실행할 때 키체인 확인 창이 뜨면 '항상 허용' 을
눌러 주세요.

앱을 그냥 끌어다 덮어써도 되긴 하지만, 그러면 공증이 없는 탓에
Gatekeeper 차단 해제를 다시 해야 합니다. 설치 도우미는 그것까지 처리합니다.

앞으로는 메뉴바에서 새 버전이 나왔다고 알려드립니다. v0.2.0 부터 들어간
기능이라, 이번 알림부터 실제로 보이실 겁니다.

처음 설치하시는 경우 — DMG 를 열어 앱을 Applications 로 끌어 넣은 뒤,
설치 도우미 (Install Helper).command 를 우클릭 → 열기.

---

SHA-256 (FaceUnlock.dmg)

e6249568b0c7a33d9eb6ce753da7d26530c78021cc181e709872ba102ff5c44c

맥북에서 되던가요? 혼자서는 확인할 수 없는 부분입니다. 되든 안 되든
Discussions에 한 줄
남겨주시면 큰 도움이 됩니다 — 어떤 모델인지가 제일 중요합니다.

쓸 만하셨다면 저장소에 ⭐ 하나 눌러주시면 정말 도움이 됩니다. 깃허브는 별
개수로 검색과 목록 노출이 정해지는 구조라, 0개면 필요한 사람이 검색해도 찾을
수가 없습니다.

v0.2.1 — Works without Homebrew · Homebrew 없이도 설치됩니다

The model installer failed on Macs without Homebrew. It looked for Python by
name (python3.12, python3.11) and gave up if neither was there — even though
the Python that ships with macOS can do the job. If your download stopped at
Error: Neither Python 3.11/3.12 nor Homebrew was found, this release fixes it.

• It now asks each candidate interpreter for its version instead of trusting
  its name, and accepts anything from 3.9 to 3.12 (what coremltools supports).
• On a Mac with no Python at all, it explains why Python is needed, asks first,
  then installs Apple's Command Line Tools for you and carries on where it left
  off. Homebrew is no longer required at any point.

Nothing in the app itself changed — if the model is already installed and
working, there is no reason to update.

Install — open the DMG, drag the app to Applications, then right-click
설치 도우미 (Install Helper).command → Open.

---

_{아래는 한국어 릴리스 노트입니다.}

Homebrew 가 없는 맥에서 모델 설치가 실패하던 문제를 고쳤습니다. 파이썬을
이름(python3.12, python3.11)으로만 찾다가, 둘 다 없으면 맥에 기본으로 있는
파이썬으로 충분한데도 그냥 포기했습니다.
Error: Neither Python 3.11/3.12 nor Homebrew was found 에서 멈추셨다면 이
버전으로 해결됩니다.

• 이제 이름이 아니라 실제 버전을 물어보고, coremltools 가 지원하는
  3.9~3.12 중 하나면 무엇이든 씁니다.
• 파이썬이 아예 없는 맥이라면 왜 필요한지 설명하고 동의를 받은 뒤, 애플
  명령어 도구를 대신 설치하고 하던 자리에서 이어서 진행합니다. Homebrew 는
  이제 어느 단계에서도 필요하지 않습니다.

앱 자체는 바뀐 것이 없습니다. 모델이 이미 설치되어 잘 쓰고 계시다면 굳이
올리실 필요 없습니다.

설치

아래의 DMG 파일을 클릭하여 설치한다음

DMG파일 내부의 안내를 따라서 진행하세요.

'설치 도우미 (Install Helper).command'를 우클릭 → 열기. 앱 복사 · 차단 해제 · 얼굴 인식 모델 설치까지 자동입니다.

공증이 없어 macOS가 막습니다. 위 과정을 두 번 반복해야 전체 설치가 완료됩니다 — DMG 배경과 Read Me에 안내되어 있습니다.

ArcFace 가중치는 InsightFace 비상업 연구용 라이선스라 DMG에 넣을 수 없어, 설치 도우미가 공식 배포처에서 직접 내려받습니다.

---

SHA-256 (FaceUnlock.dmg)

e8fde2112635199fe1bfdbff20b38cab2a56cc4f7f6a4b03cfce367b0a2a8c0e

맥북에서 되던가요? 혼자서는 확인할 수 없는 부분입니다. 되든 안 되든
Discussions에 한 줄
남겨주시면 큰 도움이 됩니다 — 어떤 모델인지가 제일 중요합니다.

쓸 만하셨다면 저장소에 ⭐ 하나 눌러주시면 정말 도움이 됩니다. 깃허브는 별
개수로 검색과 목록 노출이 정해지는 구조라, 0개면 필요한 사람이 검색해도 찾을
수가 없습니다.

v0.2.0 — Pick which camera to use · 쓸 카메라를 고를 수 있습니다

The DMG has been removed — please use v0.2.1 instead.
The model installer in this version fails on Macs without Homebrew. Everything
described below is in v0.2.1 as well.

_{이 버전의 DMG 는 내렸습니다 — v0.2.1 을 받아주세요.
이 버전의 모델 설치 도우미는 Homebrew 가 없는 맥에서 실패합니다.
아래 내용은 v0.2.1 에도 그대로 들어 있습니다.}

You can now choose which camera to use, and the app tells you when a new version is out.

Choosing a camera

Until now FaceUnlock took the built-in camera whenever one existed. If you keep the
MacBook closed on an external monitor, that meant it stared at a covered lens and
failed, every time.

Settings → Behaviour → Camera now lets you pick, and the change takes effect
immediately — leave the recognition test window open while you switch and you can
watch the preview move to the other camera.

If the camera you picked isn't connected when the Mac locks, it falls back to the
built-in one. Unplugging a webcam doesn't take face unlock down with it.

Building this turned up two bugs, fixed here as well:

• External webcams never appeared in the list. Device discovery was narrowed to
  "front camera", and external devices report their position as unspecified.
• The camera never actually changed once opened. The capture session was
  configured once and reused, so picking your iPhone and then switching back kept
  using the iPhone until the app was restarted.

Update check

Versions v0.1.0–v0.1.4 had a defect where the camera returned nothing but black frames
on the lock screen. v0.1.5 fixed it and the old DMGs were taken down — but there was
no way to reach anyone already running one of them. Next time something like that
happens, this is the path.

• The menu bar carries one line: You're up to date (0.2.0), or a button to go get the
  new version. If the check couldn't run — offline, or automatic checks turned off — it
  says nothing at all. It won't call you up to date when it doesn't know.
• Settings → Updates shows the current version and the last check, and lets you check
  by hand or turn it off.
• Offline failures are silent. No error dialog.

What leaves your Mac: one unauthenticated request a day to GitHub's releases page,
reading the latest version number. No face data, no password, no usage, no device
identifier — all GitHub's server can see is your IP address. Turn it off in Settings and
the request is never made. Downloading and installing is always something you do
yourself.

Also

• GitHub Actions now builds the app and runs the self-checks (safety guard, alignment
  geometry, render orientation) on every push. Checks that need the ArcFace weights stay
  out of CI for licensing reasons.

Install

Open the DMG and right-click 설치 도우미 (Install Helper).command → Open. It copies
the app, clears quarantine, downloads the ArcFace model and launches — all automatic.

The build isn't notarized, so Gatekeeper blocks the first run. Go to System Settings →
Privacy & Security → Open Anyway, then open it again.

The ArcFace weights are not in the DMG. InsightFace's pretrained weights are under a
non-commercial research license and can't be redistributed, so the helper fetches them
from the official source. The DMG's SHA-256 is at the bottom of this page.

---

Does it work on your MacBook? That is the one thing I can't check on my own. Whether
it works or fails, say so in Discussions — which model you're on is the single
most useful detail.

And if you find it useful, a ⭐ on the repository genuinely helps. GitHub ranks search
results and listings by star count, so at zero the people who need this can't find it.

---

_{아래는 한국어 릴리스 노트입니다.}

설정에서 쓸 카메라를 고를 수 있게 되었고, 앱이 새 버전을 스스로 알려줍니다.

카메라 선택

지금까지는 내장 카메라가 있기만 하면 무조건 내장을 썼습니다. 맥북을 덮고 외장
모니터로 쓰면 가려진 렌즈를 잡고 계속 실패했다는 뜻입니다.

설정 → 동작 → 카메라 에서 고르면 그 자리에서 바로 바뀝니다. 인식 테스트
창을 열어둔 채 바꾸면 미리보기가 넘어가는 게 보입니다.

고른 카메라가 잠글 때 안 보이면 내장 카메라로 되돌아갑니다. 웹캠 케이블을
뽑아놨다고 얼굴 해제가 통째로 죽지는 않습니다.

이 과정에서 버그 둘을 찾아 함께 고쳤습니다.

• 외장 웹캠이 목록에 들어온 적이 없었습니다. 장치 탐색이 "전면 카메라" 로
  좁혀져 있었는데, 외장 장치는 위치를 '지정 안 됨' 으로 보고합니다.
• 한 번 연 카메라가 바뀌지 않았습니다. 캡처 세션을 한 번만 구성하고
  재사용하다 보니, 아이폰 카메라를 골랐다가 내장으로 되돌려도 앱을 다시 켜기
  전까지 계속 아이폰이 켜졌습니다.

새 버전 확인

v0.1.0~0.1.4 에는 잠금 화면에서 카메라가 검은 화면만 주는 결함이 있었습니다.
v0.1.5 에서 고치고 옛 DMG 를 내렸지만, 이미 그 버전을 쓰고 있는 사람에게 알릴
방법이 없었습니다. 다음에 같은 일이 생기면 이 경로로 닿습니다.

• 메뉴바에 한 줄이 붙습니다. 최신이면 최신 버전입니다 (0.2.0), 새 버전이
  있으면 그걸 받으러 가는 버튼입니다. 확인하지 못했으면(오프라인, 자동 확인을
  꺼둔 경우) 아무 말도 하지 않습니다 — 모르는 것을 최신이라고 하지 않습니다.
• 설정 → 업데이트 에서 현재 버전·마지막 확인 시각을 보고, 직접 확인하거나 끌 수
  있습니다.
• 오프라인이면 오류 창 없이 조용히 넘어갑니다.

무엇이 나가는가: 하루 한 번, GitHub 릴리스 페이지에 인증 없는 요청 하나.
최신 버전 번호만 읽어옵니다. 얼굴도, 비밀번호도, 사용 기록도, 기기 식별자도
보내지 않습니다 — GitHub 서버가 알 수 있는 것은 접속 IP 뿐입니다. 설정에서 끄면
요청 자체가 나가지 않습니다. 내려받기와 설치는 언제나 직접 하십니다.

그 밖에

• GitHub Actions 로 빌드와 자체 검증(안전 가드 · 정렬 기하 · 상하 방향)을
  자동으로 돌립니다. ArcFace 가중치가 필요한 검사는 라이선스 때문에 넣지
  않았습니다.

설치

DMG 안의 설치 도우미 (Install Helper).command 를 우클릭 → 열기 로 시작하세요.
앱 복사 · quarantine 해제 · ArcFace 모델 내려받기 · 실행까지 자동입니다.

무공증 배포라 첫 실행은 Gatekeeper 가 막습니다. 시스템 설정 → 개인정보 보호 및
보안 → '그래도 열기' 를 누른 뒤 다시 열어주세요.

ArcFace 가중치는 DMG 에 들어 있지 않습니다. InsightFace 사전학습 가중치는
비상업 연구용 라이선스라 재배포할 수 없어, 설치 도우미가 공식 배포처에서 직접
내려받습니다.

---

DMG 를 교체했습니다(2026-08-30). 버전은 0.2.0 그대로이고, 메뉴바 표시만
손봤습니다 — '최신 버전입니다' 를 띄우고, 알려줄 것이 없는 '대기 중' 줄을
뺐습니다. 얼굴 인식과 잠금 해제 경로는 그대로입니다. 위 SHA-256 은 교체 후
파일 기준입니다.

---

맥북에서 되던가요? 혼자서는 확인할 수 없는 부분입니다. 되든 안 되든
Discussions에 한 줄 남겨주시면 큰 도움이 됩니다 — 어떤 모델인지가 제일
중요합니다.

쓸 만하셨다면 저장소에 ⭐ 하나 눌러주시면 정말 도움이 됩니다. 깃허브는 별 개수로
검색과 목록 노출이 정해지는 구조라, 0개면 필요한 사람이 검색해도 찾을 수가 없습니다.

v0.1.5 — It unlocks the moment the screen wakes · 화면이 켜지는 순간 얼굴로 풀린다

⚠️ Old version — the download has been removed

This version uses the built-in camera only, so if you keep the MacBook closed on an
external monitor it keeps failing on a covered lens. It also cannot tell you when a
new version is out. Both are solved in v0.2.0.

👉 Get the latest release

_{지난 버전입니다 — 최신 버전만 내려받으시도록 이 버전의 DMG 를 내렸습니다.
이 버전은 내장 카메라만 쓰기 때문에, 맥북을 덮고 외장 모니터로 쓰시면 가려진
렌즈를 잡고 계속 실패합니다. 앱이 새 버전을 스스로 알려주지도 않습니다.
v0.2.0 에서 둘 다 해결됐습니다.}

---

_{아래는 당시의 릴리스 노트입니다.}

잠긴 뒤 화면이 꺼졌다 다시 켜졌을 때 얼굴 인식이 동작하지 않던 문제를 고쳤습니다.

무엇이 문제였나

macOS 는 잠긴 상태에서 카메라를 처음 여는 경우 오류 없이 새까만 프레임만
돌려줍니다. 프레임은 초당 13~15장씩 정상 속도로 오고 내용만 전부 0이라 앱
입장에서는 정상 스트림과 구분되지 않습니다. 장치를 통째로 다시 열어도, 포맷을
시스템 기본값으로 되돌려도 같았습니다.

어떻게 고쳤나 — 예열

잠기는 순간 카메라를 몇 초 돌려놓으면, 같은 잠금 세션 안에서 다시 열 때는
정상 영상이 나옵니다. 실측:

카메라를 여는 시점	결과
예열 없이 화면만 껐다 켠 뒤 (5회)	❌ 전부 밝기 0
예열 후 같은 절차 (3회)	✅ 전부 얼굴 일치 → 해제

두 경우의 차이는 잠금 직후의 5초짜리 스트리밍 하나뿐입니다.

가장 긴 검증은 화면이 꺼진 채 41초를 보낸 경우로, 깨운 뒤 2.4초 만에
풀렸습니다 (냉시동 → 얼굴 일치 0.85초 → 해제 2.4초).

동작

시점	카메라
화면 잠김	몇 초 예열 (표시등 잠깐 켜짐)
화면 꺼짐	끔 — 표시등도 꺼짐
화면 켜짐	켬 → 인식 → 해제
덮개 닫음	끔

화면이 꺼져 있는 동안 카메라가 돌지 않으므로 맥도 평소대로 절전에 들어갑니다.
(돌아가는 캡처 세션은 시스템 유휴 절전을 막습니다.)

그 밖에

• 검은 프레임이 이어지면 조용히 실패하지 않고 "비밀번호로 로그인하세요" 로 알립니다
• 카메라 포맷 고정(1280×720)을 제거했습니다 — 증상과 무관했고, 시스템 기본값을 씁니다
• 화면이 자는 동안 감시 타이머가 재시도 횟수를 소진하던 문제를 고쳤습니다

설치

DMG 안의 설치 도우미 (Install Helper).command 를 우클릭 → 열기 로 시작하세요.
앱 복사 · quarantine 해제 · ArcFace 모델 내려받기 · 실행까지 자동입니다.

무공증 배포라 첫 실행은 Gatekeeper 가 막습니다. 시스템 설정 → 개인정보 보호 및
보안 → '그래도 열기' 를 누른 뒤 다시 열어주세요.

ArcFace 가중치는 DMG 에 들어 있지 않습니다. InsightFace 사전학습 가중치는
비상업 연구용 라이선스라 재배포할 수 없어, 설치 도우미가 공식 배포처에서 직접
내려받습니다.

v0.1.4 — Erase everything · 완전 삭제

⚠️ Old version — the download has been removed

Earlier versions have a defect where the camera returns nothing but black frames on
the lock screen, so face unlock does not work. It was fixed in v0.1.5.

👉 Get the latest release

_{지난 버전입니다 — 최신 버전만 내려받으시도록 이 버전의 DMG 를 내렸습니다.
예전 버전에는 잠금 화면에서 카메라가 새까만 프레임만 보내 얼굴 인식이 되지 않는
문제가 있습니다. v0.1.5 에서 고쳐졌습니다.}

---

_{아래는 당시의 릴리스 노트입니다.}

이번에 바뀐 것

지우는 버튼이 생겼습니다. 지금까지는 앱을 지우려면 터미널에 명령어를 여러 줄 붙여넣어야 했습니다. 대부분은 앱만 휴지통에 넣고 나머지를 남기게 되는데, 남는 것 중에는 봉인된 로그인 비밀번호와 얼굴 특징값이 있습니다. 제일 쉽게 지워져야 할 것들이 제일 어려웠습니다.

메뉴바 아이콘 → 설정 → 맨 아래 '완전 삭제' 를 누르면 됩니다. 확인 창 한 번을 거쳐 아래를 지운 뒤 앱을 휴지통으로 옮기고 종료합니다.

• 등록한 얼굴
• 저장된 로그인 비밀번호와 Secure Enclave 키
• 내려받은 얼굴 인식 모델
• 설정값 · 캐시
• 로그인 시 자동 실행 등록
• 앱 자신 — 지우지 않고 휴지통으로 보냅니다. 실수로 눌렀다면 앱은 꺼낼 수 있습니다(데이터는 이미 지워진 뒤라 다시 등록해야 합니다)

macOS 계정 비밀번호 자체는 바뀌지 않습니다.

앱을 이미 휴지통에 넣으셨다면 이 버튼을 누를 수가 없습니다. macOS 는 앱을 지울 때 그 앱의 코드를 실행해 주지 않아서, 앱만 사라지고 나머지는 그대로 남습니다. 그런 경우를 위해 저장소에 scripts/uninstall.command 를 넣어 두었습니다 — 더블클릭하면 같은 것들을 지웁니다. 직접 지우실 수 있게 명령어도 README 의 '지우기' 절에 적어 두었습니다.

얼굴 인식·잠금 해제 동작 자체는 v0.1.3 과 같습니다.

설치

아래의 DMG 파일을 클릭하여 설치한다음

DMG파일 내부의 안내를 따라서 진행하세요.

'설치 도우미 (Install Helper).command'를 우클릭 → 열기. 앱 복사 · 차단 해제 · 얼굴 인식 모델 설치까지 자동입니다.

공증이 없어 macOS가 막습니다. 위 과정을 두 번 반복해야 전체 설치가 완료됩니다 — DMG 배경과 Read Me에 안내되어 있습니다.

ArcFace 가중치는 InsightFace 비상업 연구용 라이선스라 DMG에 넣을 수 없어, 설치 도우미가 공식 배포처에서 직접 내려받습니다.

v0.1.3 — Legal review · 법적 검토 반영

⚠️ Old version — the download has been removed

Earlier versions have a defect where the camera returns nothing but black frames on
the lock screen, so face unlock does not work. It was fixed in v0.1.5.

👉 Get the latest release

_{지난 버전입니다 — 최신 버전만 내려받으시도록 이 버전의 DMG 를 내렸습니다.
예전 버전에는 잠금 화면에서 카메라가 새까만 프레임만 보내 얼굴 인식이 되지 않는
문제가 있습니다. v0.1.5 에서 고쳐졌습니다.}

---

_{아래는 당시의 릴리스 노트입니다.}

이번에 바뀐 것

공개 배포본을 법적으로 한 바퀴 점검했습니다. 코드 출처·모델 라이선스·의존성·에셋을 전부 확인했고, 위반은 없었습니다. 다만 사용자에게 알려야 할 문구 세 곳이 부족해서 채웠습니다.

• 상표 고지. Apple · Mac · MacBook · Face ID · Touch ID 는 Apple Inc. 의 상표이고, 이 프로젝트는 Apple 과 아무런 제휴·후원·보증 관계가 없다는 사실을 README 하단에 명시했습니다.
• 카메라 권한 문구 정정. 기존 문구는 "영상은 저장되지 않습니다" 만 말해서, 얼굴 특징값은 기기에 보관된다는 사실이 가려졌습니다. 이제 무엇을 저장하지 않고 무엇을 저장하는지 둘 다 그대로 적습니다.
• 비상업 연구용 제한 안내. ArcFace 가중치의 라이선스는 저장소뿐 아니라 받아 쓰는 사람에게도 적용됩니다. 개인 기기는 상관없지만 회사 지급 기기나 업무 목적은 범위를 벗어날 수 있어서, README 와 설치 도우미에서 미리 알려줍니다.

고친 것

• DMG 용량 2.9MB → 0.9MB. 앱 번들 안에 디버그 심볼(FaceUnlock.dSYM, 6MB)이 함께 복사되고 있었습니다. 실행에 전혀 필요 없는 파일이라 뺐습니다.

얼굴 인식·잠금 해제 동작 자체는 v0.1.2 와 같습니다.

설치

아래의 DMG 파일을 클릭하여 설치한다음

DMG파일 내부의 안내를 따라서 진행하세요.

'설치 도우미 (Install Helper).command'를 우클릭 → 열기. 앱 복사 · 차단 해제 · 얼굴 인식 모델 설치까지 자동입니다.

공증이 없어 macOS가 막습니다. 위 과정을 두 번 반복해야 전체 설치가 완료됩니다 — DMG 배경과 Read Me에 안내되어 있습니다.

ArcFace 가중치는 InsightFace 비상업 연구용 라이선스라 DMG에 넣을 수 없어, 설치 도우미가 공식 배포처에서 직접 내려받습니다.

v0.1.2 — Starts at login, checked for the long haul · 로그인 자동 실행 · 장기 사용 점검

⚠️ Old version — the download has been removed

Earlier versions have a defect where the camera returns nothing but black frames on
the lock screen, so face unlock does not work. It was fixed in v0.1.5.

👉 Get the latest release

_{지난 버전입니다 — 최신 버전만 내려받으시도록 이 버전의 DMG 를 내렸습니다.
예전 버전에는 잠금 화면에서 카메라가 새까만 프레임만 보내 얼굴 인식이 되지 않는
문제가 있습니다. v0.1.5 에서 고쳐졌습니다.}

---

_{아래는 당시의 릴리스 노트입니다.}

새로 생긴 것

재시동해도 알아서 다시 뜹니다. 얼굴로 잠금 해제를 처음 켤 때 로그인 항목으로 한 번 등록합니다. 그 뒤로는 설정창의 로그인 시 자동 실행 토글이 주인이라, 껐다면 다시 켜지 않습니다.

재시동 직후 첫 로그인 화면은 얼굴로 못 엽니다. 그때는 macOS가 아직 앱을 띄우기 전이라 비밀번호를 직접 입력해야 하고, 그 뒤의 화면 잠금부터 얼굴이 동작합니다.

고친 것

• 설정창 하단 버전이 옛 버전으로 보이던 문제. 태그만 올리고 Info.plist는 그대로 두는 실수가 가능했습니다. 이제 버전의 단일 출처는 Makefile이고 빌드할 때 각인되므로 두 곳이 어긋날 수 없습니다.
• 모델 캐시 자가 복구. 컴파일된 .mlmodelc를 못 열면 버리고 한 번 다시 컴파일합니다. 예전에는 그냥 실패해서, macOS 대형 업데이트로 캐시가 한 번 깨지면 "모델 없음"으로 영구히 굳었습니다.
• 예열이 메모리를 붙잡지 않습니다. 1280×720 버퍼(3.7MB)와 검출기를 앱 수명 내내 들고 있던 걸 놓게 했습니다.

장기 사용 점검 (1~3년)

쌓이는 것이 없는지 전부 확인했습니다.

• 자체 로그 파일 0개 — OSLog만 사용, 3일치 디스크 기록 0줄
• 쓰는 파일은 3개뿐이고 전부 덮어쓰기 (faces.sealed / ArcFace.mlmodelc / 설정 plist)
• Keychain 항목 3개 고정 — 저장 전에 항상 지우고 씁니다
• 무한히 커지는 배열 없음 — 등록 3명 · 포즈 9개 상한
• 타이머 · 옵저버 · 절전 어서션 · App Nap 표 전부 짝이 맞음
• 재시도 카운터는 정상 프레임을 받으면 0으로 복귀 (오래 쓴다고 서서히 망가지지 않음)
• 유휴 시 CPU 0.0% — 잠기지 않은 동안은 아무것도 하지 않습니다

설치

아래의 DMG 파일을 클릭하여 설치한다음

DMG파일 내부의 안내를 따라서 진행하세요.

'설치 도우미 (Install Helper).command'를 우클릭 → 열기. 앱 복사 · 차단 해제 · 얼굴 인식 모델 설치까지 자동입니다.

공증이 없어 macOS가 막습니다. '그래도 열기'를 두 번 반복해야 실제로 열립니다 — DMG 배경과 Read Me에 안내되어 있습니다.

ArcFace 가중치는 InsightFace 비상업 연구용 라이선스라 DMG에 넣을 수 없어, 설치 도우미가 공식 배포처에서 직접 내려받습니다.

v0.1.1 — The camera runs only when the screen wakes · 화면이 켜질 때만 카메라를 켠다

⚠️ Old version — the download has been removed

Earlier versions have a defect where the camera returns nothing but black frames on
the lock screen, so face unlock does not work. It was fixed in v0.1.5.

👉 Get the latest release

_{지난 버전입니다 — 최신 버전만 내려받으시도록 이 버전의 DMG 를 내렸습니다.
예전 버전에는 잠금 화면에서 카메라가 새까만 프레임만 보내 얼굴 인식이 되지 않는
문제가 있습니다. v0.1.5 에서 고쳐졌습니다.}

---

_{아래는 당시의 릴리스 노트입니다.}

잠긴 채 화면이 켜지는 그 순간에만 카메라를 켜도록 바꿨습니다. 배터리와 사생활 양쪽에서 크게 나아집니다.

바뀐 점

카메라가 필요할 때만 켜집니다. 지금까지는 "잠겨 있고 화면이 켜져 있는가" 라는 상태로 판단해서, 조건이 유지되는 내내 카메라가 돌았습니다. 다른 앱이 화면을 붙잡고 있으면(영상 재생 중인 브라우저 등) 그 몇 분 동안 계속 — 잠금이 풀릴 때까지 렌즈 옆 초록불이 켜져 있었습니다. 이제는 "화면이 켜졌는가" 라는 사건으로 판단합니다. 인식 창을 열고, 성공·실패·시간초과·화면 꺼짐 중 하나가 오면 닫습니다. 창 밖에서는 카메라도 타이머도 전부 멈춥니다.

직접 잠그면 바로 풀리지 않습니다. 예전에는 잠그자마자 인식을 시작하고 쿨다운도 없어서, 깜빡임 확인을 끈 기본 설정에서는 잠금 버튼을 누른 채 화면을 보고 있으면 1초 뒤에 도로 풀렸습니다. 이제 화면이 꺼졌다 깨어날 때 인식이 시작됩니다.

차가운 상태의 첫 인식이 10배 빨라졌습니다. 임베딩을 뉴럴 엔진 대신 CPU 로 돌립니다. 프레임당 속도는 뉴럴 엔진이 빠르지만 차이가 6.6ms 라 체감되지 않는 반면, 모델을 처음 올리는 시간은 1.67초 대 0.16초로 뒤집힙니다. 사건 기반이 된 지금은 뉴럴 엔진이 거의 항상 차갑기 때문에 CPU 가 유리합니다. 이 비용을 가리려고 1분마다 돌던 예열 타이머도 없앴습니다 — 잠기지 않은 시간 내내 앱을 깨우지 않습니다. 이미 등록한 얼굴은 그대로 인식됩니다 (두 방식의 임베딩 코사인 유사도 평균 0.998).

설치 도우미가 뒷정리를 제대로 합니다. pip 캐시를 작업 폴더 안에 두도록 고쳤습니다. 예전에는 설치가 끝나도 ~/Library/Caches/pip 에 수백 MB~수 GB 가 남았습니다. 0.1.0 으로 설치하셨다면 rm -rf ~/Library/Caches/pip 로 한 번 비워주세요.

---

What changed (English)

The camera now turns on only when the screen wakes while locked, instead of running for as long as "locked and a display is awake" held true. Manual locks no longer unlock themselves a second later. Face embeddings run on the CPU rather than the Neural Engine — 10× faster from cold (0.16s vs 1.67s), which is what you actually feel, and the 60-second warmup timer is gone. Existing enrollments keep working (cross-backend cosine similarity 0.998). The install helper now cleans up its pip cache; if you installed 0.1.0, run rm -rf ~/Library/Caches/pip once.

---

설치 (DMG)

1. FaceUnlock.dmg 다운로드 후 열기
2. 창의 안내대로 앱을 Applications 로 드래그
3. 설치 도우미 (Install Helper).command 를 우클릭 → 열기
4. 첫 실행은 macOS 가 차단합니다 (zsh: killed 로 끝나며 정상):
   • 시스템 설정 → 개인정보 보호 및 보안 → 아래 보안 항목으로 스크롤
   • "그래도 열기" 클릭 → Mac 로그인 암호 입력
   • 설치 도우미를 다시 우클릭 → 열기 — 이번엔 끝까지 자동입니다
     (앱 복사, 실행 차단 해제, 얼굴 인식 모델 다운로드·변환, 앱 실행.
     Python 3.12 가 없으면 Homebrew 로 설치할지 물어봅니다)
5. 설정에서 권한·얼굴·비밀번호 등록

이미 0.1.0 을 쓰고 계시면 설치 도우미가 알아서 교체합니다. 등록한 얼굴과 비밀번호는 그대로 유지됩니다.

Install (English)

1. Download and open FaceUnlock.dmg
2. Drag the app into Applications as the window shows
3. Right-click 설치 도우미 (Install Helper).command → Open
4. macOS blocks the first run (it ends with zsh: killed — expected):
   go to System Settings → Privacy & Security, scroll down to Security,
   click "Open Anyway", enter your password, then right-click → Open the
   helper again. The second run finishes everything automatically
   (copies the app, removes quarantine, downloads and converts the model,
   launches FaceUnlock). The helper speaks English unless your Mac is set to Korean.
5. Grant permissions and enroll your face/password in Settings

Upgrading from 0.1.0 is handled by the helper; your enrolled faces and password are kept.

---

ArcFace 모델은 InsightFace 비상업 라이선스라 DMG 에 동봉하지 않고, 설치 도우미가 공식 배포처에서 직접 내려받습니다. / The ArcFace weights are under InsightFace's non-commercial research license, so the DMG does not bundle them — the helper downloads them from the official source.

⚠️ 공증(notarization) 없음 — 무공증 배포에서 위의 "두 번 열기" 절차는 macOS 정책상 생략할 수 없습니다. 신뢰가 어려우면 소스 빌드(권장, README 참고)를 이용하세요. / No notarization — the double-open procedure above is required by macOS for unnotarized downloads and cannot be skipped. If in doubt, build from source (recommended, see README).

Full Changelog: v0.1.0...v0.1.1