우타링 (Utaring)

앱 이름은 우타링입니다. 歌(우타, 노래)에 -ring을 붙인 것으로, 한국어 화자가 한눈에 읽히고 무엇을 하는 앱인지 소리로 전합니다. 저장소 이름 Just와 번들 ID com.coby.just는 그대로 둡니다 — 바꾸면 기기의 앱 데이터와 프로비저닝이 함께 끊깁니다.

좋아하는 일본 아이돌 — KAWAII LAB. 다섯 그룹, iLiFE!, =LOVE — 의 노래 가사로 일본어를 공부하는 iPhone / iPad 앱.

노래 한 곡이 학습 한 세트입니다. 가사 줄을 누르면 그 줄이 단어로 쪼개지고, 담은 단어는 실제로 나온 가사를 예문 삼아 간격 반복 복습으로 넘어갑니다.

만드는 법

tuist generate

Xcode 26.6 이상, iOS 26 SDK, Swift 6.3 기준입니다.

실행 전 준비 (한 번만)

Apple Music은 앱에 붙여넣을 API 키가 없습니다. 대신 App ID에 서비스를 켜 주어야 MusicKit이 개발자 토큰을 스스로 발급합니다.

1. Apple Developer 계정의 Identifiers 에서 com.coby.just App ID를 만들고 MusicKit을 켭니다.
2. Xcode에서 Just 타깃 → Signing & Capabilities → 팀을 선택합니다.
3. 실제 기기에서 실행합니다. 시뮬레이터에는 Apple Music 계정이 없어 카탈로그 검색과 재생이 동작하지 않습니다.

첫 실행 시 앱이 Apple Music 접근 권한을 요청합니다.

화면

아이돌 ────┬─ 이어서 공부하기 (진도 표시)
          └─ 그룹 카드 — 아티스트 사진 위에 그룹 색 (KAWAII LAB. / iLiFE! / =LOVE)
             ↓ 그룹 선택
          그룹의 곡 목록
             ↓ 곡 선택

내 노래 ───── 내가 연 곡 전부, 최신순. 진도와 함께. 길게 눌러 목록에서 빼기
          플레이어 ──┬─ 싱크 가사 + 후리가나 → 줄 탭 → 단어 카드
                    ├─ 가사 싱크 조절 (곡별로 저장)
                    ├─ 한 줄 구간 반복
                    ├─ 가사 전체화면 / 가사 크기 4단계
                    └─ 단어 일괄 담기 · 이 곡의 단어
                    ↓ 내리면
          미니플레이어 (탭 바 위) — ⏮ ▶ ⏭, 열었던 목록 안에서 이전/다음 곡

단어장 ────┬─ CSV 내보내기 (Anki·스프레드시트)
          ├─ 통계 + JLPT 분포 차트
          └─ JLPT 필터 + 정렬 → 단어 상세

연습 ──────┬─ 복습 카드 (FSRS)
          ├─ 어려운 단어 집중 · 랜덤 믹스
          ├─ 빈칸 채우기 · 뜻 보고 쓰기 · 사지선다
          └─ 듣고 받아쓰기

이 앱은 일곱 그룹만 다룹니다. 검색이 없는 것이 결함이 아니라 정의입니다 — 좋아하는 그룹이 첫 화면에 있고 두 번 눌러 곡에 닿는 것이 강점입니다.

그룹	Apple Music ID
FRUITS ZIPPER	1617607581
CANDY TUNE	1671095780
SWEET STEADY	1729116371
CUTIE STREET	1763185226
MORE STAR	1855752654
iLiFE!	1578837625
=LOVE	1273762750

그룹 카드의 사진도 Apple Music 아티스트 조회에서 옵니다 — 곡 목록과 같은 요청이라, 카드를 그린 뒤 그룹을 열면 두 번 묻지 않습니다(GroupArtworkStore가 실행 중 한 번만 받아 둡니다). 사진이 없거나 아직 안 왔으면 그룹 색 그라데이션이 카드 자체라, 아무것도 깜빡이지 않습니다.

명단만 앱에 있고 곡은 Apple Music 아티스트 조회로 옵니다 — 새 싱글이 나오면 앱 업데이트 없이 뜹니다. 이름이 아니라 ID로 찾는 이유는 동명이인입니다.

목록과 그룹 화면은 밝고 화사하게, 플레이어와 가사는 다크를 유지합니다. 가사는 어두운 배경에서 읽기가 훨씬 편하고, 이 앱에서 가장 긴 시간이 가사를 읽는 시간입니다.

두 톤은 팔레트 하나가 색상 모드를 따라 바뀌는 것으로 구현됩니다. JustTheme.Ink와 Surface가 다크·라이트 값을 각각 갖고 그리는 자리에서 해석되므로, 목록 화면은 루트에 .environment(\.colorScheme, .light) 한 줄을 붙이는 것으로 뒤집히고 그 안의 모든 라벨이 따라옵니다. 화면마다 수십 개의 색 참조를 고치는 대신 한 곳을 고쳤습니다.

앱 아이콘은 하트 안의 「歌」에 반짝임 셋입니다(Scripts/make-icon.py). 한자만으로는 일본어를 말하고 아이돌을 말하지 못했고, 하트만으로는 그 반대였습니다. 말풍선 꼬리도 시도했다가 뺐습니다 — 하트는 이미 뾰족한 끝이 있어서 꼬리를 붙이면 끝이 둘이 되고, 작은 크기에서 렌더링 오류처럼 읽혔습니다.

구조

Just (앱)
 ├── JustCore     도메인 모델, SwiftData 스키마, FSRS 스케줄러
 ├── JustDesign   팔레트 추출, 메시 배경, 후리가나 조판
 ├── JustMusic    MusicKit 검색 + ApplicationMusicPlayer
 ├── JustLyrics   LRCLIB 클라이언트, LRC 파서
 └── JustSensei   형태소 분석, 읽기, 온디바이스 해석 엔진

데이터 출처

	출처	비고
곡·앨범·아트워크	Apple Music (MusicKit)	키 불필요, 쿼터 없음
재생	ApplicationMusicPlayer	구독 없으면 30초 미리듣기로 대체
가사	LRCLIB	무인증, 싱크 LRC
해석	Apple Intelligence (온디바이스)	빠르게/정확하게 선택, 사전 + 시스템 번역
한자 음훈	번들 (1,591자)	한국어 학습자용

가사 싱크

두 가지가 어긋날 수 있고 원인이 다릅니다.

미리듣기에서는 가사가 따라가지 않습니다. 구독이 없으면 재생은 30초 클립이고, 그 클립은 곡 중간에서 잘려 나옵니다(미리듣기 첫 1초의 평균 음량이 클립 전체 평균과 0.3~3.5dB 차이뿐 - 곡의 시작이라면 무음에서 출발합니다). Apple은 어디서 잘랐는지 공개하지 않으므로 클립 시간을 곡 시간으로 환산할 방법이 없습니다. 그래서 환산하지 않고, 강조·자동 스크롤·줄 탭 이동·구간 반복을 모두 멈추고 이유를 한 줄로 표시합니다. 가사는 그대로 읽고 눌러 뜻을 볼 수 있습니다.

전곡 재생에서 몇 초 어긋나는 것은 시트가 그렇게 적힌 것입니다. 시트를 만든 사람이 한 줄의 시작을 어디로 잡았는지(첫 박, 첫 음절, 그 앞의 숨)는 데이터에 없고, 대조할 두 번째 출처도 없어서 자동으로는 찾을 수 없습니다. 대신 곡별로 StudySong.lyricsOffset에 저장되는 보정값을 사용자가 정합니다 - 다이얼로 0.1/0.5초씩 밀거나, 지금 들리는 줄을 눌러 한 번에 맞춥니다. 앱이 짚고 있는 줄이 아니라 실제로 들리는 줄을 눌러야 합니다(짚고 있는 줄은 정의상 틀린 줄입니다). ±5초를 넘기면 받지 않습니다 - 그건 타이밍이 아니라 다른 편집본이라는 뜻입니다.

광고

광고는 하나뿐입니다 — 곡을 분석하며 기다리는 동안 전면 광고 한 번. 가사가 아직 준비되지 않았고 무엇을 해도 대기가 줄지 않는, 화면을 쓰지 않는 유일한 순간입니다.

목록 아래에 붙어 있던 배너들은 걷어냈습니다. 마지막 행 밑의 띠는 모든 화면 끝의 잡동사니로 읽혔고, 벌이도 적었습니다.

띄우지 않는 곳도 적어 둡니다. 가사와 플레이어 위, 문제가 떠 있는 화면, 그리고 빠른 번역 / AI 번역을 고르는 질문 위 — 그건 독자가 답하는 중인 질문입니다. 그래서 선택이 끝나고 분석이 실제로 시작된 뒤에만, 남은 줄이 5줄 이상일 때만 띄웁니다. 더 적으면 광고가 닫히기 전에 분석이 끝납니다.

곡당 한 번, 그리고 2분 안에 두 번은 없습니다. 그룹의 곡을 넘겨 보는 독자가 매 곡 광고를 보는 일은 없어야 합니다.

GADApplicationIdentifier와 광고 단위 ID는 Google 공개 테스트 값입니다. 실제 수익에는 계정 보유자의 ID가 필요합니다. 맞춤 광고는 쓰지 않으므로 App Tracking Transparency 프롬프트도 띄우지 않습니다.

Apple Music API는 가사를 제공하지 않습니다. 음악 앱에 가사가 보이는 것과 별개로 공개 API에는 열려 있지 않아, 싱크 가사는 LRCLIB에서 받습니다.

로컬 저장

곡을 열면 그 곡에 딸린 모든 데이터가 기기에 남습니다.

데이터	위치	비고
가사 (LRC)	StudySong.lyricsData	오프라인 재열람 가능
줄별 해석 전체	StudySong.analysisData	번역 + 단어 + 문법. 모델은 곡당 한 번만 돈다
난이도 히스토그램	StudySong.levelCounts	목록에서 해석을 디코드하지 않아도 되도록 비정규화
단어·복습 일정	VocabEntry / ReviewState
앨범아트	Caches/Artwork	URL 해시 파일명. 시스템이 회수 가능

곡을 처음 열면 전곡 해석이 자동으로 시작됩니다. 줄마다 눌러 기다리는 대신 한 번에 만들어 저장합니다. 진행분은 즉시 기록되므로 중간에 닫아도 버려지지 않고, 다시 열면 남은 줄부터 이어서 합니다.

해석을 빠르게 하는 것 세 가지가 들어 있습니다. 후렴처럼 같은 줄이 반복되면 한 번만 모델에 묻고 나머지 인덱스에 복사합니다. 모델 세션은 줄마다 새로 만들지 않고 8줄마다 재활용합니다 — 매번 만들면 열다섯 줄짜리 지시문을 그때마다 다시 처리합니다. 저장은 다섯 줄마다 합니다(매 줄 저장은 곡 길이에 대해 제곱으로 늘어남).

곡을 열 때 아직 번역할 줄이 남아 있으면 **「어떻게 번역할까요?」**를 먼저 묻습니다 — 「빠르게」(몇 초, 뜻·문법은 정확, 문장은 직역에 가까움)와 「AI로 정확하게」(앞뒤 줄까지 읽어 자연스럽게, 몇 분) 두 카드에 각각 한 문장 설명이 붙습니다. 설정에 묻힌 선택기는 기다리는 동안 아무도 찾지 않으므로, 답이 필요한 그 순간에 묻습니다. 「다음에도 이걸로 열기」를 켜면 더 묻지 않고, 설정에서 다시 켤 수 있습니다. 이미 다 번역된 곡은 묻지 않습니다 — 답이 바꿀 것이 없습니다.

화면 문구에는 기술 용어를 쓰지 않습니다. 「AI 번역」과 「빠른 번역」, 「간단 번역」이 전부입니다. 줄 카드의 버튼도 「정확하게 다시 번역」입니다.

기다리기 싫으면 **'지금 듣기'**로 바로 넘어갈 수 있고, 남은 줄은 들으면서 이어서 해석합니다. 긴 곡은 알아서 넘어갑니다 — 첫 두 줄을 넘긴 뒤 남은 시간이 30초를 넘으면 플레이어를 먼저 열고 나머지를 뒤에서 채웁니다(WaitBudget). 완성된 곡을 보여주는 것이 여전히 기본이고, 빨리 끝나는 곡은 끝까지 기다립니다 — 사람에게 요구할 수 있는 대기와 기기가 할 수 있는 대기는 다르기 때문입니다.

속도를 위해 정확도를 조금 내준 것이 세 가지 있습니다. 문법 노트를 더 이상 묻지 않습니다 — 측정에서 아홉 줄 중 다섯~일곱 줄이 비어 있었는데, 거의 비는 칸도 모델이 매 줄 지나가는 칸입니다. 단어는 한 줄에 최대 세 개입니다(전에는 여섯). 그리고 greedy 디코딩을 씁니다 — 표본 추출 비용이 사라지고, 무엇보다 같은 줄이 같은 답을 주므로 프롬프트를 바꿨을 때 숫자가 움직이면 그것이 이유가 있어 움직인 것입니다(전에는 잡음을 넘겨보려고 세 번씩 돌려야 했습니다).

영어 줄은 번역 한 칸만 묻습니다. 단어와 문법은 어차피 버리므로, 버릴 출력을 생성하느라 기다릴 이유가 없습니다.

자동 해석 시점은 설정에서 고릅니다 — 항상 / 저전력 모드가 아닐 때(기본) / 안 함. 기본값이 저전력 모드를 따르는 이유는, 사용자가 이미 시스템에 에너지 사용 방침을 말해 두었기 때문입니다. 학습 앱이 그걸 앞질러 판단할 이유가 없습니다.

해석이 빠지는 줄을 없애는 세 층

영어 구절은 번역만 합니다. J-POP은 후렴이 통째로 영어인 경우가 흔합니다. 그 줄도 노래의 일부라 뜻은 알려주지만, 거기서 외울 일본어 단어는 없습니다 — baby에 가나 읽기를 지어 붙인 카드는 복습 일정에 들어가서 계속 돌아옵니다. 가나나 한자가 하나라도 있으면 일본어로 보고(비율이 아닙니다 — 영어 줄에 섞인 일본어 한 단어도 배울 값이 있습니다), 섞인 줄에서는 일본어 단어만 남깁니다.

실패한 줄은 진전이 있는 동안 다시 시도합니다. 남은 줄이 없어질 때까지 돌면 항상 실패하는 줄에서 영원히 돌아오지 않으므로, 조건은 완료가 아니라 진전입니다 — 한 바퀴가 아무것도 해결하지 못하면 끝입니다. 한 줄당 최대 한 바퀴이므로 반드시 끝납니다.

그래도 남은 줄은 시스템 번역으로 채웁니다. Apple Intelligence는 최신 기기를 요구하지만 Apple 번역은 그렇지 않습니다. 예전 기기에서는 해석이 사전 뜻에서 멈추고 번역이 아예 없었는데, 그게 정작 필요한 절반입니다. 뉘앙스는 없는 직역이지만 번역은 번역입니다.

해석 방식은 두 가지고, 고를 수 있습니다

같은 세 가지 질문 — 단어가 무슨 뜻인지, 어떤 문법을 쓰는지, 줄이 무슨 말인지 — 에 서로 다른 것이 답합니다.

	빠르게	정확하게
단어	번들 사전	모델 + 사전이 사실 교정
문법	패턴 매칭	패턴 매칭
문장	시스템 번역(직역)	모델이 앞뒤 줄까지 읽고 해석
한 곡	몇 초	몇 분

원래는 선택이 아니라 기기 사양이었습니다. Apple Intelligence가 없으면 사전으로 떨어지고, 있으면 거절할 방법이 없었습니다. 하지만 그 폴백은 구형 기기만을 위한 것이 아닙니다 — 후렴을 지금 보고 싶은 사람, 배터리가 아까운 사람, 이미 한 번 읽은 곡을 다시 여는 사람에게 느린 쪽은 선택하지 않은 비용입니다. 그래서 폴백이 모드가 되고, 모드가 설정이 되었습니다.

대기 화면에도 전환 버튼이 있습니다. 조급함은 설정 화면이 아니라 기다리는 자리에서 생기고, 거기서 찾을 수 없는 모드는 없는 모드입니다. 누르면 진행 중인 줄만 모델이 끝내고 나머지는 즉시 채워집니다. 이미 해석된 줄은 좋은 답을 그대로 유지합니다.

빠르게로 해석한 곡을 정확하게로 바꾸면 다시 해석합니다. 사전 결과도 번역을 갖고 있어서, 번역이 있으면 완료라는 기존 규칙만으로는 빠르게 읽은 곡이 영원히 빠른 상태로 남았습니다. 반대 방향은 대칭이 아닙니다 — 빠르려고 이미 받은 더 좋은 답을 버릴 이유는 없습니다.

문법은 물어보지 않고 찾습니다

모델에 문법 노트를 요청하는 것은 그만뒀습니다. 아홉 줄 중 다섯~일곱 줄이 빈 배열로 돌아왔고, 쓰이지 않는 필드도 생성되는 출력만큼 비용을 냅니다. 그런데 그걸 끊으면 문법 모아보기 화면에 공급이 사라집니다.

그래서 찾습니다. 일본어 문법 패턴은 유한하고 잘 정리된 집합이고, 어떤 줄이 「〜てしまう」를 포함하는지 아닌지는 판단이 아니라 사실이며, 그게 무슨 뜻인지는 곡에 따라 달라지지 않습니다. 이 파일의 나머지가 이미 하는 분업과 같습니다 — 판단은 모델, 사실은 고정 데이터.

줄에 맞춘 설명을 포기하는 대신, 항상 작동하고 항상 같은 말을 하고 생성 비용이 0입니다. 긴 패턴은 자기가 포함한 짧은 패턴을 가립니다 — 「なきゃ」는 「ない」에 대한 수업이 아닙니다. 한 줄에 최대 3개인데, 짧은 가사 한 줄에 노트 여덟 개는 수업이 아니라 소음입니다.

모델이 있는 기기에서는 모델이 먼저 다 시도한 뒤에 남은 줄만 채웁니다. 그러지 않으면 위의 재시도가 무의미해지고 일시적 실패가 직역으로 굳습니다.

Translation 프레임워크는 뷰 밖에서 init(installedSource:target:)만 쓸 수 있어서, 언어팩 다운로드는 설정 화면의 버튼(.translationTask)에서 시작합니다 — 시스템 프롬프트가 뜨는 일이라 해석 도중이 아니라 사용자가 연 화면에 있어야 맞습니다. 스위치로 끌 수 있고 기본은 켬입니다.

해석 품질 측정

Report/SenseiReport.swift는 테스트가 아니라 측정 장치입니다. 고정된 가사에 실제 해석기를 돌려 나온 것을 찍고, 셀 수 있는 실패(이웃 줄 침범, 금지어, 번역에 남은 일본어, 부풀림, 사전으로 대체된 줄)와 소요 시간을 표로 냅니다. 품질은 단언할 수 없지만 이 숫자들은 단언할 수 있고, 두 실행을 비교하는 것이 프롬프트나 묶음 변경을 판단하는 유일한 방법입니다.

별도 타깃(JustReport)이고 앱이 호스트입니다. 그래서 실기기에서 돌릴 수 있습니다 — 시뮬레이터의 온디바이스 모델 자산은 하루에 세 번 사라졌고, 그때마다 보고서는 「모든 줄이 사전으로 대체됐습니다」라고 스스로 말합니다.

# 시뮬레이터
xcodebuild -workspace Just.xcworkspace -scheme JustReport \
  -destination 'platform=iOS Simulator,name=iPhone 17' test

# 실기기 (모델이 진짜인 곳). 기기 잠금을 풀어야 합니다.
xcodebuild -workspace Just.xcworkspace -scheme JustReport \
  -destination 'platform=iOS,name=Coby' -allowProvisioningUpdates test

기본 Just 스킴의 테스트는 JustTests만 돌립니다. 유닛 테스트는 1초 미만이고 매 변경마다 돌리는 것이라, 그 앞에 앱 실행을 얹지 않기 위해 타깃을 나눴습니다.

오매칭을 재는 눈

커버리지 보고서에 **「가나 표기가 한자 표제어로 잡힌 것」**을 셉니다. 가사가 가나로 쓴 말이 한자 단어로 돌아온 경우인데, 옳을 때도(ゆめ → 夢) 있고 그 반대가 문제였습니다 — 부정 어미 「ない」가 119줄에서 「泣く(울다)」로, 「また」가 「待つ」로, 「いい」가 「言う」로 잡혔습니다. 가나 단어를 활용 되돌리기로 다른 가나로 구부린 뒤 읽기 인덱스에서 한자 동사를 찍어 온 것입니다.

세 가지로 막았습니다. 읽기 인덱스는 먼저 들어온 항목 대신 흔한 뜻(손으로 확인한 것, 그중 쉬운 급)을 고릅니다. 가나로 쓴 말은 같은 가나 표제어가 있으면 그것을, 없으면 손으로 확인한 흔한 한자 단어까지만 받고 수입된 희귀 표기로는 넘어가지 않습니다. 그리고 되돌린 후보 중 어미(た·て·ない·ます·よう)가 붙어 있던 것만 읽기로 한자 동사에 닿을 수 있고, 끝 글자 하나를 바꿔 만든 후보는 표기로만 찾습니다 — 어미는 동사가 있었다는 증거고, 끝 글자는 증거가 아닙니다.

측정: 오매칭 227 → 25, 남은 25건은 전부 옳은 매칭입니다. 커버리지는 66% → 63%로 내려갔는데, 빠진 3점이 가짜 적중이었습니다.

번들 사전

Modules/JustSensei/Resources/seed-dictionary.json은 생성물입니다.

python3 Scripts/build-dictionary.py

Scripts/build-dictionary.py는 옆 프로젝트가 없으면 직전 빌드에서 가져온 항목을 그대로 유지하고, 결과가 이전보다 10% 넘게 줄면 쓰기를 거부합니다. 경고만 내고 진행하던 때에는 6,900개 사전이 179개로 덮여 쓰였고 앱은 어휘 대부분을 잃은 채로 계속 돌았습니다 — 옆 프로젝트는 모든 기계에 있지 않습니다.

두 층으로 나뉩니다. Scripts/curated.json의 149개는 손으로 확인한 것이라 품사와 JLPT 등급까지 신뢰할 수 있고, 나머지 6.8천개는 옆 프로젝트인 jlpt-app의 일한 단어 데이터에서 가져왔습니다. 후자는 뜻과 읽기만 씁니다 — 원본의 lv 필드는 난이도가 아니라 교재 소속 태그라(전 행이 n1, 안경과 도서관까지) 등급으로 쓰면 없느니만 못합니다.

해석 파이프라인

가사 한 줄
 ├─ CFStringTokenizer   문맥 인식 분절 + 읽기
 ├─ NLTagger            사전형(lemma) · 품사
 ├─ FoundationModels    한국어 번역 · 뜻 · 뉘앙스 (guided generation)
 └─ 번들 사전 교차검증   표제어 · 읽기 · 품사 · JLPT 등급 덮어쓰기
                        (가사에 쓰인 표기를 읽기보다 우선)

프롬프트에는 그 줄 단어의 사전 뜻이 함께 들어갑니다(<words>). 모델은 문장을 읽는 데는 강하고 단어를 기억하는 데는 약해서, 空을 「공기」(空気)로 옮기는 일이 반복됐습니다 — 사전은 「하늘」로 정확히 갖고 있는데 아무도 모델에게 말해주지 않았습니다. 넣는 개수는 네 개로 제한합니다. 문맥 창이 세 줄에서 넘치는 상황에서 줄 길이에 따라 늘어나는 목록은 그 시점을 앞당깁니다.

번역으로 받아들이는 조건도 기계적으로 검사합니다. 한글이 인용부호 밖 글자의 다수여야 하고, 인용부호 밖에 일본어가 남아 있으면 받지 않습니다. 인용은 괜찮습니다 — 원문이 「さよなら」를 인용하면 번역이 그대로 인용하는 것이 옳고, 영어 후렴을 인용하는 한국어 문장도 옳습니다. 「한글이 하나라도 있으면」으로 두었을 때 「가 fence across from each other.」가 통과했습니다.

온디바이스 모델은 문맥에는 강하고 암기에는 약합니다. 「〜てる」를 「〜ている」로 되돌리거나 가사를 자연스러운 한국어로 옮기는 일은 잘 하지만, JLPT 등급을 지어내고 표제어 자리에 읽기를 쓰기도 합니다. 그래서 판단은 모델에, 사실은 사전에 맡기고, 가사에 실제로 없는 단어는 버립니다 (JustSensei/Sensei.swift의 refine).

접근성

모든 본문 텍스트가 Dynamic Type을 따릅니다. Font.system(size:)는 시스템 글자 크기 설정을 무시하고 Font.custom(_:size:relativeTo:)는 폰트 파일 이름을 요구하므로, UIFont를 UIFontMetrics로 통과시키는 Font.just(_:weight:relativeTo:)를 씁니다 — 디자인된 포인트 크기를 유지하면서 설정을 존중합니다.

고정 크기로 남긴 것은 SF Symbol 아이콘과 연속일수 링의 숫자뿐입니다. 둘 다 글자와 함께 커지면 안 되는 고정 지오메트리 안에 있습니다.

가사는 여기에 앱 자체의 4단계 조절이 곱해집니다. 시스템 설정과 앱 설정이 같은 텍스트에 함께 작용하므로, 접근성 크기에서는 가사 크기를 낮춰 쓰면 됩니다.

딥링크

just://review와 just://words로 화면을 지정할 수 있습니다. 복습 알림과 위젯이 이 링크를 씁니다 — 알림이 앱을 열되 사용자가 마지막에 보던 화면으로 데려가면 그 알림은 실패한 것입니다.

알림은 onOpenURL로 오지 않으므로 NotificationRouter가 대신 받습니다. 앱 시작 시점에 등록하는 이유는, 콜드 스타트에서 탭한 알림이 뷰가 만들어지기 전에 전달되기 때문입니다.

위젯

홈 화면 위젯은 앱의 SwiftData를 열지 않습니다. 앱이 App Group 컨테이너에 작은 스냅샷(JSON)을 쓰고 위젯은 그걸 읽습니다 — 위젯이 앱 데이터베이스를 여는 것은 스키마 변경을 따라다녀야 하고 쓰기도 못 하며, 숫자 세 개를 읽자고 기존 사용자 데이터를 마이그레이션할 이유도 없습니다.

App Group group.com.coby.just가 필요합니다. 자동 서명이 등록하지 못하면 developer.apple.com > Identifiers > App Groups에서 만들고, App ID의 App Groups 기능에서 연결해 주세요.

MusicKit App ID 설정 (필수, 1회)

검색이 "개발자 토큰 요청 실패"로 죽으면 이것 때문입니다.

MusicKit은 개발자 토큰을 자동으로 발급하지만, 명시적 App ID에 MusicKit 서비스가 켜져 있을 때만 가능합니다. 와일드카드 팀 프로비저닝 프로파일(TEAM.*)로 서명하면 실패하고, 오류 메시지는 토큰만 말하고 정작 원인인 포털 스위치는 언급하지 않습니다.

1. developer.apple.com > Certificates, Identifiers & Profiles > Identifiers
2. + > App IDs > App > Bundle ID는 Explicit로 com.coby.just
3. 그 App ID의 App Services에서 MusicKit 체크 후 저장
4. 다시 빌드 (-allowProvisioningUpdates가 새 프로파일을 받아옵니다)

설정 화면의 카탈로그 연결 > 연결 확인으로 실제 성공 여부를 볼 수 있습니다.

빌드와 배포

옆 프로젝트 mana와 같은 구성입니다.

bash Scripts/setup.sh        # tuist generate
bundle exec fastlane test    # 시뮬레이터 테스트
bundle exec fastlane beta    # TestFlight 업로드

Tuist 버전은 .mise.toml에 고정합니다. 서명은 자동이고 팀 id는 매니페스트에 있으므로 tuist generate만으로 기기 빌드가 됩니다.

TestFlight는 App Store Connect API 키로 클라우드 서명합니다 — 인증서를 손으로 갱신할 일이 없습니다. 인증 플래그는 xcargs 한 곳에만 둡니다(gym이 archive와 export 양쪽에 그대로 넘기므로 export_xcargs로 중복하면 xcodebuild가 거부합니다).

v* 태그를 밀면 .github/workflows/deploy.yml이 돌고, 필요한 시크릿은 APPSTORE_KEY_ID / APPSTORE_ISSUER_ID / APPSTORE_PRIVATE_KEY입니다.

버전은 MARKETING_VERSION과 CURRENT_PROJECT_VERSION이 정합니다. Info.plist에 값을 박아두면 fastlane이 넘기는 빌드 번호가 무시되어 업로드가 매번 충돌합니다.

App/Resources/PrivacyInfo.xcprivacy는 필수입니다. 이 앱은 추적을 하지 않고 수집 항목도 없으며, 필수 사유 API는 UserDefaults(CA92.1) 하나입니다.

테스트

xcodebuild -workspace Just.xcworkspace -scheme Just \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' test

순수 로직만 덮습니다 — 파싱, 스케줄링, 문자열 처리. 지금까지 실제로 나온 버그가 전부 그 영역이었고, 기기·계정·모델 없이 검증할 수 있는 부분도 거기까지입니다. 62개 테스트가 있고, 그중 여러 개는 실제로 겪은 회귀를 그대로 고정해 둔 것입니다: CRLF 가사 분할, 번역본 오선택, 동음이의어 표기 뒤바뀜.

남은 것

• 번들 사전 6.9천 단어 중 등급·품사가 붙은 것은 손으로 확인한 149개뿐입니다.
• 뮤직비디오는 다루지 않습니다. 공개 API로는 전체 재생이 불가능합니다.
• 곡 난이도는 분석한 줄에서만 집계되므로, 일부만 분석한 곡은 표본이 작습니다.

시뮬레이터에는 Apple Music 계정이 없어 곡을 열 수 없습니다. 검색·재생·추천·앨범은 실기기에서만 확인됩니다.

라이선스

MIT. 다만 번들 데이터의 출처는 구분해서 봐 주세요.

• Scripts/curated.json (149단어), Modules/JustSensei/Resources/kanji-ko.json (한자 1,591자 음훈), 그리고 seed-dictionary.json의 대부분은 이 저장소 소유자의 다른 프로젝트에서 가져온 데이터입니다.
• 가사는 저장소에 포함되지 않습니다. 실행 시 LRCLIB에서 받아 기기에만 저장됩니다.
• 곡 정보와 아트워크는 Apple Music 카탈로그에서 옵니다. Apple Media Services 이용약관이 적용됩니다.