← Docs hub

PUI Launcher 화자 등록 Overlay 연동 구현 설계

이 문서는 SKMLauncher2의 setLauncherScreen과 VitalSign PUI 진입 구조를 실제 코드로 추적하고, ondevice 앱의 기존 화자 관리·등록 화면을 PUI 버튼과 DeviceAgent 이벤트에서 안전하게 여는 구현안을 정리한다.

현재 상태: 이 페이지는 구현 전 설계 기준선이다. 기존 ondevice overlay와 등록 엔진은 코드에 존재하지만, Launcher용 Receiver·service action·결과 callback은 아직 구현하지 않았다. UI 가이드가 제공되면 4장의 교체 가능 영역을 확정한 뒤 이 계약을 기준으로 구현한다.

핵심 결론은 다음과 같다.

• VitalSign 화면은 런처 내부 Fragment가 아니라 별도 패키지 com.gbsoft.vitalsign의 launch Activity다.
• PUI 버튼과 setLauncherScreen(screenName=vitalSign)은 SKMLauncherApp.launchVitalSignApp()으로 합쳐진다.
• ondevice 앱에는 이미 화자 관리 overlay, 등록 overlay, 녹음 전환, WAV 저장, embedding 등록 로직이 존재한다.
• 현재 빠진 것은 PUI에서 이 내부 화면으로 들어가는 보호된 앱 간 진입점이다.
• 1차 구현은 UI와 마이크를 ondevice에 유지하고, 런처가 explicit component + signature permission으로 화면 표시만 요청하는 방식이 가장 작고 안전하다.

버전 주의: 분석한 MR6 SKMLauncher2 소스는 0.277, 연결 기기 192.168.123.118:5555의 설치본은 0.285다. 구조적 결론은 유효하지만 실제 반영 전 0.285 소스에서 동일 callback과 화면 정책을 대조해야 한다.

1. 현재 구현에서 확인된 사실

1.1 PUI VitalSign 버튼

apps/SKMLauncher2/.../ui/stay/StayActivity.java:92-98

binding.btnVitalSign.setOnClickListener(
    __ -> ((SKMLauncherApp) getApplication()).launchVitalSignApp("PUI")
);

PUI 버튼은 런처 화면을 교체하지 않고 SKMLauncherApp의 공통 실행 함수로 넘긴다.

1.2 DeviceAgent setLauncherScreen

apps/SKMLauncher2/.../ui/SKMLauncherApp.java:1428-1436

method == setLauncherScreen
  -> outdata.screenName
  -> LauncherScreen.fromScreenName()
  -> launchScreenByLlm()

LauncherScreen.java에는 VITAL_SIGN("vitalSign")이 있고, launchScreenByLlm()의 VITAL_SIGN 분기는 launchVitalSignApp("LLM")을 호출한다.

따라서 진입 주체만 다를 뿐 다음 두 경로는 같은 함수로 수렴한다.

PUI button -> launchVitalSignApp("PUI")
LLM callback -> setLauncherScreen(vitalSign) -> launchVitalSignApp("LLM")

1.3 VitalSign은 별도 앱

SKMLauncherApp.java:2072-2095는 다음을 수행한다.

1. Privacy mode를 확인한다.
2. com.gbsoft.vitalsign 설치 여부를 확인한다.
3. 현재 공기청정, interaction schedule, 이동을 정지한다.
4. getLaunchIntentForPackage("com.gbsoft.vitalsign")를 얻는다.
5. START_VITAL_SIGN_BY=PUI|LLM extra를 넣고 Activity를 실행한다.

연결 기기에서도 다음이 확인됐다.

VitalSign main component는 com.gbsoft.vitalsign/.MainActivity다.

1.4 ondevice에는 등록 화면이 이미 있다

ForegroundService.kt의 현재 구현:

등록 중 마이크 소유권도 이미 처리한다.

resumeSttAfterEnrollment = AudioRecordManager.isRecording()
-> stopContinuousRecording()
-> requestAudioRecord(speakerEnrollmentClientId)
-> 등록 녹음
-> stopSpeakerEnrollment()
-> restoreSttAfterEnrollment()

즉 새로 만들어야 할 핵심은 등록 UI 자체가 아니라 외부에서 내부 UI를 열 수 있는 계약이다.

1.5 지금 바로 직접 실행할 수 없는 이유

ondevice manifest에서 다음 컴포넌트는 모두 exported=false다.

• .ui.SpeakerListActivity
• .ui.SpeakerHistoryActivity
• .service.ForegroundService

이는 외부 앱이 임의로 진입하지 못하게 하는 올바른 기본값이다. 런처에서 현재 Activity 이름을 직접 start하거나 service component를 호출하는 방식으로 풀면 권한과 수명주기 계약이 무너진다.

2. 권장 목표 구조

2.1 책임 배치

2.2 ondevice 변경

1. com.skmagic.ondeviceai.permission.SPEAKER_ENROLLMENT를 protectionLevel=signature로 선언한다.
2. 이 권한으로 보호된 SpeakerEnrollmentReceiver를 만든다.
3. 런처는 package가 아니라 Receiver component까지 지정한 explicit intent를 보낸다.
4. Receiver는 기존 ForegroundService에 ACTION_SHOW_SPEAKER_MANAGE를 전달한다.
5. 서비스는 main thread에서 기존 showSpeakerManageOverlay()를 호출한다.
6. overlay 추가 성공, 이미 표시 중, 권한 없음, 서비스 미초기화를 각각 구분해 로그와 결과로 남긴다.

권장 action 예시:

com.skmagic.ondeviceai.action.SHOW_SPEAKER_MANAGE
com.skmagic.ondeviceai.action.SHOW_SPEAKER_REGISTER

현재 코드를 그대로 재사용하는 기준안은 관리 화면부터 여는 것이다. 등록, 목록, 뒤로가기의 현재 UX를 유지할 수 있고 향후 삭제·동의 화면도 같은 entrypoint 아래 확장할 수 있다. 다만 PUI가 곧바로 “등록 씬”을 요구하면 targetScreen=REGISTER로 직접 등록 overlay를 열 수 있다. 최종 기본값은 UI 가이드에서 결정하고 IPC 계약은 두 진입을 모두 지원한다.

2.3 SKMLauncher2 변경

LauncherScreen에 다음 값을 추가한다.

SPEAKER_REGISTRATION("speakerRegistration")

PUI 버튼과 LLM 경로는 반드시 같은 함수로 수렴시킨다.

PUI button
  -> launchSpeakerEnrollment("PUI")

setLauncherScreen(speakerRegistration)
  -> launchScreenByLlm()
  -> launchSpeakerEnrollment("LLM")

launchSpeakerEnrollment()은 다음을 책임진다.

• Privacy mode와 화면 충돌 정책 확인
• ondevice package/component 존재 확인
• explicit intent + signature permission 전송
• 전송 성공과 실제 overlay 표시 완료를 구분

2.4 완료 시점

현재 launchScreenByLlm()은 switch 실행 직후 reportScreenApplied(appliedScreenName)를 호출한다. 외부 앱/overlay 연동에서는 intent 전송 성공이 화면 표시 성공과 같지 않다.

따라서 speakerRegistration은 다음 중 하나로 완료를 닫아야 한다.

• ondevice가 overlay WindowManager.addView() 성공 뒤 결과 callback 전송
• 요청에 correlation ID를 넣고 DeviceAgent가 terminal result를 기다림
• 최소 구현에서는 timeout과 실패 상태를 둔 explicit result receiver 사용

REQUEST_ACCEPTED != SCREEN_APPLIED != ENROLLMENT_COMPLETED

제품 정책상 어떤 상태를 setLauncherScreenStatus=success로 볼지 먼저 정해야 잘못된 조기 완료를 막을 수 있다. 화면 전환 task라면 SCREEN_APPLIED, 등록 workflow라면 ENROLLMENT_COMPLETED가 terminal 기준이다.

3. 상세 구현 계약

3.1 런타임 시퀀스

시퀀스 SVG 원본 크게 보기

외부 진입에서는 다음 경계를 지킨다.

1. Launcher는 requestId를 생성하고 explicit broadcast를 보낸다.
2. SpeakerEnrollmentReceiver는 권한과 필수 extra만 검증한다.
3. UI 처리는 Receiver에서 하지 않고 기존 ForegroundService action으로 전달한다.
4. Service는 main thread에서 WindowManager.addView()를 수행한다.
5. addView() 성공 뒤에만 SCREEN_APPLIED를 반환한다.
6. 사용자 등록 성공, 취소 또는 실패 시 Service가 overlay를 제거하고 terminal result를 한 번만 반환한다.
7. Launcher는 terminal result 또는 timeout 뒤 기존 PUI 화면을 복구한다.

Receiver는 짧게 끝나야 한다. 마이크 획득, 파일 저장, embedding 생성처럼 시간이 걸리는 처리는 현재처럼 Service가 소유한다.

3.2 앱 간 message contract v1

아래 이름은 구현 시 상수 파일로 고정할 제안값이다. UI 문구나 색상과 독립적인 IPC 계약이므로 UI 가이드가 바뀌어도 유지한다.

보안과 개인정보 원칙:

• Launcher는 ondevice의 Receiver component를 명시한다.
• open Receiver와 result Receiver 모두 com.skmagic.ondeviceai.permission.SPEAKER_ENROLLMENT signature permission으로 보호한다.
• 양쪽 앱 manifest에 동일 permission 사용 관계를 명시하고 platform certificate를 배포 전 비교한다.
• 결과 broadcast에는 사용자 표시 이름, 음성 샘플 경로, embedding을 넣지 않는다.
• speakerProfileId가 필요하면 내부 식별자만 선택적으로 반환한다.
• requestId, event, reason, elapsed time만 운영 로그에 남기고 음성·이름은 마스킹한다.

권장 reason code:

3.3 Service 내부 명령

외부 Receiver가 private ForegroundService에 전달할 action은 앱 내부 상수로 분리한다.

ACTION_SHOW_SPEAKER_ENROLLMENT
  requestId
  entrySource
  targetScreen

ACTION_DISMISS_SPEAKER_ENROLLMENT
  requestId
  dismissReason

onStartCommand()은 action을 기존 handleAction()으로 넘기므로, 여기에 화자 등록 action 분기만 추가하면 된다. Receiver가 Service의 private 함수를 직접 호출하거나 Activity를 실행하지 않는다.

Service가 보관해야 할 최소 session:

data class SpeakerEnrollmentSession(
    val requestId: String,
    val entrySource: EntrySource,
    val targetScreen: TargetScreen,
    val startedAtElapsedMs: Long,
    var state: EnrollmentUiState,
    var terminalResultSent: Boolean = false,
)

requestId가 같은 재전송은 idempotent하게 처리하고, 다른 요청이 이미 진행 중이면 정책에 따라 기존 session에 attach하거나 ALREADY_RECORDING으로 거부한다.

3.4 UI·녹음 상태 머신

상태 머신 SVG 원본 크게 보기

모든 종료 경로에서 다음 순서를 보장한다.

등록 녹음 중지
→ AudioRecord callback 해제
→ 필요 시 STT 소유권 복구
→ IME 숨김
→ WindowManager.removeView()
→ terminal result 1회 전송
→ session 정리

현재 onDestroy()는 녹음 중지와 등록 overlay 제거를 수행하지만 관리 overlay 제거와 결과 callback은 없다. 구현 시 두 overlay를 모두 정리하고 진행 중 외부 요청에는 FAILED/SERVICE_DESTROYED를 반환하도록 보강한다.

3.5 entrySource별 닫기·뒤로가기

현재 showSpeakerRegisterOverlay()의 닫기와 뒤로가기는 모두 다음과 같다.

stopSpeakerEnrollment()
→ hideSpeakerRegisterOverlay()
→ showSpeakerManageOverlay()

외부 PUI 진입에 그대로 사용하면 사용자가 닫기를 눌러도 다른 ondevice overlay가 다시 열리므로 자연스럽지 않다. 목표 동작은 다음처럼 분리한다.

Android system back, 화면 닫기 버튼, timeout, service destroy도 동일한 finishEnrollmentSession() 경로로 수렴시켜 terminal result 중복을 막는다.

3.6 Launcher 완료 의미

두 완료 단계를 섞지 않는다.

SCREEN_APPLIED
  = overlay가 실제 WindowManager에 추가됨
  = setLauncherScreen 작업의 성공 후보

COMPLETED
  = 유효 샘플 저장 + embedding/profile 등록 성공
  = 화자 등록 workflow의 성공

PUI 버튼은 SCREEN_APPLIED 뒤 사용자 상호작용을 기다리고, LLM/TaskManager가 “화자 등록 완료”까지 요구한 경우에만 COMPLETED를 terminal 기준으로 사용한다. 화면 표시 timeout과 등록 workflow timeout은 서로 다른 timer로 둔다.

4. UI 가이드 반영 계약

UI 가이드가 제공되면 기존 app/src/main/res/layout/overlay_speaker_register.xml과 관련 drawable, color, string을 교체해 구현할 수 있다. 통신·오디오·상태 머신과 View 렌더링을 분리하면 시안 변경이 기능 로직에 영향을 주지 않는다.

4.1 현재 UI 기준선

현재 코드에서 확인된 값:

이는 기능 검증용 기준선이며 최종 제품 UI 확정값은 아니다.

4.2 UI 가이드에서 받아야 할 항목

특히 전체등록과 초기화는 개발·관리 성격이 강하므로 일반 사용자 PUI에 노출할지 제품 정책 확인이 필요하다. UI 가이드 전에는 삭제하지 않고 visibility 정책으로 분리한다.

4.3 UI 상태별 화면 산출물

UI 가이드는 최소 다음 상태를 포함하면 그대로 구현 가능하다.

1. 최초 진입/이름 입력
2. 이름 미입력 validation
3. 녹음 준비
4. 녹음 중
5. 녹음 처리 중
6. 등록 성공
7. 재시도 가능한 실패
8. 취소 확인이 필요한 경우
9. 중복 이름 또는 기존 profile 처리
10. Privacy/마이크 사용 안내

각 화면에 normal, pressed, focused, disabled 상태와 최종 문구가 있으면 XML resource와 상태 renderer로 옮긴다. Figma, SVG/PNG, 해상도 스펙, color/font token 중 제공 가능한 형식으로 전달하면 된다.

4.4 변경에 강한 구현 경계

SpeakerEnrollmentReceiver / IPC contract
            │ 변경하지 않음
SpeakerEnrollmentSession + state reducer
            │ UI 상태만 전달
SpeakerEnrollmentOverlayController
            │ inflate / render / dismiss
XML + drawable + color + string
            │ UI 가이드에 따라 교체

버튼 listener 안에서 직접 저장·결과 전송을 모두 처리하지 않고 onRecordClicked, onBackClicked, onCloseClicked 이벤트를 controller로 보내면 UI 레이아웃이 바뀌어도 기능 동작을 재사용할 수 있다.

5. Receiver와 Activity 중 무엇이 맞나

기존 Phase 1 문서는 장기 제품형 구조로 Launcher-native UX + ondevice 등록 엔진 경계를 제안했다. 이번 코드 발견으로 현재 제품 브랜치의 빠른 통합 경로는 ondevice overlay 재사용이 더 현실적이라는 사실이 추가됐다. 두 설계는 경쟁안이 아니라 단계가 다르다.

Phase 1A: protected entrypoint + existing ondevice overlay
Phase 1B: enrollment controller/API 분리
Phase 1C: Launcher-native product UX + bound service/AIDL

6. 화면·오디오·TaskManager 정책

6.1 화면 충돌

진입 전에 최소한 다음 상태를 결정해야 한다.

• VitalSign 실행 중
• Security mode 화면 실행 중
• 제품 이동 중
• Privacy mode
• 다른 overlay 표시 중
• 화자 등록이 이미 진행 중

정책은 allow, queue, reject 중 하나로 명시하고 reason code를 남긴다.

6.2 마이크와 STT

현재 등록 구현은 STT 녹음을 중지하고 등록 client가 AudioRecord를 독점한 뒤 복구한다. 따라서 STT와 등록 녹음을 동시에 수행하는 새 fan-out은 필요하지 않다.

다만 다음 종료 경로에서도 반드시 복구돼야 한다.

• 등록 완료
• 사용자 취소/뒤로가기
• overlay 제거
• timeout
• service destroy
• AudioRecord 획득 실패
• embedding 등록 예외

6.3 화자인식 추론 구조와의 연결

등록 화면은 화자 embedding을 생성해 profile에 저장하는 producer다. 실제 음성 turn에서는 CPU STT와 QNN speaker identification이 병렬 실행되고 hard join 뒤 VOICE_ID를 확정하는 consumer 구조로 연결된다.

PUI 등록
  -> speaker profile / embedding 저장

일반 발화
  -> CPU STT ----------------------┐
  -> QNN speaker identification ---┤ hard join
                                   -> text + VOICE_ID
                                   -> profile/personalization lookup

자세한 추론 구조는 CPU STT + QNN 화자인식 병렬 통합 문서와 Speaker Context Contract에서 이어서 본다.

7. 구현 순서

1. UI 가이드의 확정 항목과 TBD를 4장 표에 채우고 PUI 최초 화면을 REGISTER 또는 MANAGE로 결정한다.
2. 설치본 0.285와 MR6 0.277의 setLauncherScreen, completion, domain policy 차이를 대조한다.
3. ondevice에 signature permission, explicit Receiver, service action, idempotency guard를 추가한다.
4. session/state reducer와 source별 닫기 정책을 단위 테스트한다.
5. adb explicit intent로 ondevice 단독 진입과 STT stop/restore를 검증한다.
6. SKMLauncher에 speakerRegistration enum과 공통 launch 함수를 추가한다.
7. PUI 버튼 경로를 연결한다.
8. DeviceAgent callback allowlist와 TaskDomainResourcePolicy를 확장한다.
9. REQUEST_ACCEPTED, SCREEN_APPLIED, CANCELLED, FAILED, TIMEOUT을 실기기 log로 검증한다.
10. 제품 UX가 확정되면 overlay를 전용 Activity/controller 구조로 단계적으로 옮긴다.

8. 최소 검증 매트릭스

8.1 구현 완료 정의

다음 조건을 모두 충족해야 “연동 구현 완료”로 판단한다.

• Launcher PUI 버튼과 setLauncherScreen(speakerRegistration)이 같은 공통 함수로 수렴한다.
• 권한 없는 앱의 open broadcast가 거부된다.
• 실제 기기에서 ondevice 등록 overlay가 1회만 표시된다.
• PUI와 INTERNAL 진입의 닫기 동작이 설계대로 다르다.
• 등록 성공 후 profile이 저장되고 다음 화자인식 turn에서 조회된다.
• 완료·취소·오류·timeout 모두 STT와 overlay 자원을 복구한다.
• platform certificate가 설치본과 일치하는 release APK로 검증한다.
• UI 가이드 상태 화면과 실제 screenshot을 대조한다.

9. 최종 판단

구현은 가능하며 새 화면을 처음부터 만드는 작업보다 작다. 현재 ondevice가 이미 UI와 녹음/등록 상태를 소유하므로, PUI/Launcher는 화면 선택과 정책만 담당하고 ondevice의 보호된 entrypoint를 호출하는 구조가 1차 목표에 맞다.

제품형 Launcher-native UX는 이후 controller/API를 분리한 다음 진행한다. 지금 바로 UI와 AudioRecord를 Launcher로 옮기면 이미 동작하는 등록 경로를 복제하고 앱 간 PCM 전달, 취소, timeout, 저장 책임까지 동시에 새로 설계해야 하므로 리스크가 커진다.

현재 문서는 구현에 착수할 수 있는 계약 수준까지 정리됐으며, UI 가이드에서 미정인 항목은 4장에 격리했다. 이후 UI 가이드가 제공되면 화면 리소스와 renderer 부분을 확정하고, 사용자가 구현을 요청하는 시점에 Launcher와 ondevice 두 저장소의 코드를 이 기준으로 변경한다.

Connections

• Speaker Identity Service
• Speaker Enrollment Service Phase 1 Plan
• Speaker Context Contract
• CPU STT + QNN 화자인식 병렬 통합
• DeviceAgent / SoC