영어 3,000단어 앱의 음성 6,146개 — 공식 어휘표에서 클립 압축까지, 그리고 배포를 멈춘 파일 수
영어 몬스터에 들어간 3,000단어는 교육부 고시 별표의 기본 어휘 목록을 그대로 파싱했고, 뜻과 예문은 AI 에이전트 30배치로 쓰고 따로 검수해 75건을 고쳤습니다. 단어·예문·동사 변화형을 Edge TTS로 읽혀 6,146개 클립을 만들면서 겪은 edge-tts 403, 무음 제거 필터가 단어 중간을 자른 문제, 개발 중 듣기가 무음이던 이유를 적고, 같은 클립을 사이트 웹판에 올렸다가 GitHub Pages 배포가 10분 시간 초과로 멈춘 사고와 그 뒤 한 번 더 난 시간 초과까지 정리했습니다
Read in English 6,146 Audio Clips for a 3,000-Word English App — From an Official Word List to Tiny MP3s, and the File Count That Stalled My Deploy
영어 몬스터는 초등·중학·고등 영단어 3,000개를 몬스터를 잡으며 익히는 앱입니다. 앱이 무엇을 하는지는 소개글에 적었고, 이 글은 그 뒤쪽 이야기입니다. 단어 목록을 어디서 가져왔는지, 뜻과 예문을 어떻게 만들고 검수했는지, 단어와 예문을 읽어 주는 음성 클립 6,146개를 어떻게 작게 만들었는지, 그리고 그 클립을 사이트 웹판에 그대로 올렸다가 배포가 멈춘 일까지 순서대로 적습니다.
수치는 모노레포의 계획 문서(hubs/monsters/PLAN.md), 생성 스크립트, 커밋 기록, 사이트 리포의 커밋과 GitHub Actions 실행 기록에서 다시 확인한 값입니다.
1. 단어 목록: 고시의 별표를 그대로 파싱했다
단어는 직접 고르지 않았습니다. 2022 개정 영어과 교육과정(교육부 고시 제2022-33호 [별책 14])에 붙은 [별표 3] 기본 어휘 목록을 그대로 썼습니다. 원문은 한국교육과정평가원의 영어 어휘 검색 프로그램 안내서에 별표 3이 전재된 PDF(경기도교육청 게시본)에서 받았고, PDF의 sha256과 고시 번호, 쪽수를 데이터 파일 머리에 적어 두었습니다.
| 구분 | 단어 수 | 앱 안 위치 |
|---|---|---|
| 초등 권장 | 800 | Day 1~40 |
| 중학 | 1,200 | Day 41~100 |
| 고등 | 1,000 | Day 101~150 |
| 합계 | 3,000 | 하루 20단어 |
파싱한 JSON의 건수가 800/1,200/1,000으로 별표와 맞는지 먼저 확인했습니다. 처음 계획은 초등과 중학까지 2,000단어였는데, 같은 날 저녁에 고등 1,000단어까지 넣기로 범위를 넓혀 별표 전체가 들어갔습니다.
저작권은 이렇게 판단했습니다. 교육과정은 교육부 고시이고 별표는 고시의 일부라서, 저작권법 제7조가 보호하지 않는 저작물(고시·공고 등)로 보았습니다. 다만 이건 제 판단이고 법률 자문이 아닙니다. 그래서 목록 자체만 가져오고, 뜻·품사 풀이·예문·보기는 전부 새로 썼습니다. 목록 밖의 남의 콘텐츠는 가져오지 않았습니다.
2. 뜻과 예문: 100단어씩 30배치, 생성과 검수를 나눴다
3,000단어의 뜻과 예문은 AI 에이전트에게 100단어씩 나눠 맡겼습니다. 생성한 에이전트와 검수한 에이전트를 나누는 방식은 자격증 문제은행 제작기와 같습니다.
| 단계 | 초등·중학 2,000 | 고등 1,000 |
|---|---|---|
| 생성 | 20배치(초등 8 + 중학 12) | 10배치 |
형식 검사 vocab_check.py | FAIL 0 | FAIL 0 |
| 교차 검수 수정 | 48건 | 27건 |
교차 검수에서 나온 수정안은 파일 6개에 75건으로 남아 있습니다. 형식 검사는 기계적으로 확인할 수 있는 것만 봅니다. 품사 표기가 정해진 목록 안에 있는지, 뜻이 1~3개이고 12자 이내인지, 예문이 3~10단어이고 그 단어(또는 변화형)가 실제로 들어 있는지, 예문 번역이 있는지, 아이에게 맞지 않는 표현(음주·흡연·폭력 등)이 없는지입니다. 뜻이 맞는지, 예문이 그 뜻으로 쓰였는지는 검수 단계가 봅니다. 기능어나 민감한 단어처럼 4지선다 문제로 내기 어려운 단어는 문제에서 빼고 학습 카드에만 두었는데, Day마다 고르게 흩어 Day당 문제로 낼 수 있는 단어가 최소 18개가 되게 했습니다.
3. 음성: 왜 클립이었나, 그리고 edge-tts 403
앱은 Google Play와 토스 안에서 돌아갑니다. 토스 앱 안의 웹뷰에는 브라우저 음성 합성(speechSynthesis)이 없어서, 단어를 읽어 주려면 미리 녹음한 클립이 필요했습니다. 한글 몬스터에서 이미 쓰던 파이프라인을 그대로 가져왔습니다. Edge 신경망 TTS로 읽히고, 파일 이름은 텍스트의 md5로 정해서 단어가 바뀌어도 바뀐 것만 다시 만들고, 목록에 없는 클립은 지웁니다.
| 항목 | 값 |
|---|---|
| 목소리 | en-US-JennyNeural |
| 속도 | 단어 -10%, 예문 -5% |
| 동시 요청 | 8개, 실패하면 3번까지 재시도 |
11월 5일 첫 실측에서 edge-tts 7.2.8이 모든 요청에 403(웹소켓 핸드셰이크 거부)을 냈습니다. 코드를 의심하기 전에 패키지를 올려 보니(pip install -U edge-tts, 7.3.1) 바로 복구됐습니다. 서비스 쪽에서 토큰 검증 방식을 바꾸면 옛 버전 클라이언트가 한꺼번에 막히는 구조라, 지금은 스크립트 머리 주석에 “403이 나면 패키지부터 올린다”고 적어 두었습니다.
4. 클립 압축: 11.8KB에서 3.4KB로
단어 8개로 실측했을 때 Edge TTS가 내준 원본은 평균 11.8KB였고, 그중 앞뒤 무음이 0.6초가량 있었습니다. 단어 하나가 1초도 안 되는데 무음이 절반 넘게 붙어 있는 셈이었습니다. 앞뒤 무음을 자르고 모노 22.05kHz 32kbps로 다시 압축하니 평균 3.4KB가 됐습니다.
처음에는 ffmpeg silenceremove의 stop_periods로 뒤쪽 무음을 잘랐습니다. 그런데 이 방식은 단어 안에 있는 짧은 끊김도 끝으로 보고 잘라 버렸습니다. responsibility가 0.34초짜리 클립이 됐습니다. 여러 음절 단어는 음절 사이에 아주 짧은 무음이 있어서 그렇습니다.
그래서 앞쪽 무음만 자르는 필터를 두 번 쓰고, 그 사이에 소리를 뒤집었습니다. 뒤집은 소리의 앞쪽 무음은 원래 소리의 뒤쪽 무음이니, 단어 중간은 건드리지 않고 양 끝만 잘립니다. 실제 스크립트(games/english-monsters/tools/gen-tts.py)의 필터와 명령입니다.
1
2
3
4
5
6
AF = ("silenceremove=start_periods=1:start_threshold=-50dB:start_silence=0.06,areverse,"
"silenceremove=start_periods=1:start_threshold=-50dB:start_silence=0.06,areverse")
def compress(src, dst, bitrate):
subprocess.run(["ffmpeg", "-y", "-loglevel", "error", "-i", src, "-af", AF, "-ac", "1", "-ar", "22050",
"-b:a", bitrate, "-id3v2_version", "0", "-write_xing", "0", dst], check=True)
-50dB보다 작은 소리를 무음으로 보고, 끝에 60ms 여백을 남깁니다. ID3 태그와 Xing 헤더도 넣지 않습니다. 비트레이트는 단어 32kbps, 문장 24kbps로 나눴습니다. 예문을 넣기로 했을 때 문장 실측이 평균 1.8초·5.4KB였고, 24kbps로 3,000문장이면 16MB 안팎이라는 계산으로 정했습니다.
| 묶음 | 개수 | 비트레이트 | 용량 |
|---|---|---|---|
| 단어 | 3,000 | 32kbps | 8.8MB |
| 예문 | 2,985 | 24kbps | 16.4MB |
| 불규칙동사 변화형 | 161 | 32kbps | — |
| 합계 | 6,146 | 24.4MB |
예문이 3,000이 아니라 2,985인 이유는 두 단어가 같은 예문을 쓰는 경우를 하나로 합쳤기 때문입니다. 동사 변화형 161개는 불규칙동사 과정(127개)을 넣으면서 과거형·과거분사 중 새로 필요한 것만 더한 수입니다. 지금 폴더를 다시 세어도 mp3는 6,146개, 합계 24.4MB, 평균 약 4.2KB입니다(단어보다 긴 예문이 섞여 평균이 3.4KB보다 큽니다).
5. 개발 중 듣기가 무음이었던 이유
클립을 만드는 동안 앱에서 듣기 문제를 눌러 보면 소리가 안 났습니다. 원인은 생성 스크립트 구조였습니다. 클립 수천 개를 다 만든 뒤에 맨 마지막에 목록 파일(manifest.json, 텍스트 → 파일 이름)을 씁니다. 생성이 도는 동안에는 목록이 없으니 앱은 클립이 없다고 보고 브라우저 음성 합성으로 넘어갔는데, 앱 안 브라우저에는 그 기능이 없어서 결국 무음이었습니다.
임시 목록을 만들어 Day 1 클립 20개가 재생되는 것을 확인하고 넘어갔습니다. 생성이 끝나면 목록이 생기니 출시판에는 문제가 없었습니다. 다만 “소리가 안 난다”는 증상만 보면 재생 코드나 웹뷰 설정을 먼저 의심하기 쉬웠는데, 실제 원인은 파일 쓰는 순서였습니다.
6. 사이트 사고: 파일 6,147개가 배포를 멈췄다
11월 7일 오후 영어 몬스터 소개글을 올리면서, 설치 없이 해 볼 수 있는 웹판을 사이트(/play/english-monsters/)에 함께 넣었습니다. 모노레포 빌드 결과를 그대로 복사했고, 거기에 mp3 6,146개와 목록 파일이 들어 있었습니다.
| 시각(한국) | 일 | 결과 |
|---|---|---|
| 11/7 14:17 | 웹판 + 클립 커밋(추적 파일 9,448개) | 빌드 성공, 배포 단계 10분에 실패 |
| 같은 실행 재시도 | 배포만 다시 | 또 10분에 실패 |
| 11/7 15:09 | 클립을 빼고 다시 커밋(추적 파일 3,301개) | 빌드·배포 성공 |
빌드와 링크 검사는 2분 안에 끝났는데, Pages에 올리는 단계가 두 번 모두 정확히 10분을 채우고 실패했습니다. 기본 시간 제한에 걸린 것입니다. 당시 세션 기록으로는 사이트 아티팩트가 205MB까지 커져 있었습니다. 9월에 올린 한글 몬스터 웹판은 파일 1,085개짜리였고 문제가 없었습니다. 그 사이 라이브 사이트는 직전 배포 상태로 남아 있어서 새 소개글과 웹판 주소가 모두 404였습니다.
고친 방법은 클립을 사이트에서 빼는 것이었습니다. 웹판은 목록 파일이 404이면 기기 음성 합성으로 넘어가도록 이미 짜여 있었고, 일반 브라우저에는 그 기능이 있으니 사이트에서는 클립 없이도 단어를 읽어 줍니다. 로컬에서 Day 1 카드의 단어·예문이 기기 음성으로 읽히는 것과 콘솔 오류가 목록 404 두 건뿐인 것을 확인했습니다. 사이트 README에는 “웹판에 클립 수천 개를 커밋하지 말 것”을 운영 메모로 남겼고, 그 뒤로 사이트 파일 수는 3,300개 수준으로 유지하고 있습니다. 출시 사고 21건을 정리한 출시 사고 연대기의 빌드 항목 한 줄이 이 일입니다.
그 뒤 한 번 더 난 시간 초과
같은 날 자정 직전에 배포가 한 번 더 10분 시간 초과로 실패했고, 내용 없는 재시도 커밋이 두 개(11/8 00:11, 00:20) 들어갔습니다. 같은 원인이 남아 있었는지 Actions 실행 기록을 다시 봤습니다.
| 커밋(한국 시각) | 추적 파일 | 배포 결과 |
|---|---|---|
| 11/7 23:57 앱 아이콘 추가 | 3,304 | 배포 단계 10분 시간 초과로 실패 |
| 11/8 00:11 재시도 커밋 1 | — | 실행 기록이 없음 |
| 11/8 00:20 재시도 커밋 2 | — | 성공 |
이때는 클립이 이미 빠져 파일 수가 3,304개였으니 파일 수 문제는 아니었습니다. 증상은 똑같이 배포 단계가 10분을 채우고 끝난 것이었지만, 원인은 가르지 못했습니다. 첫 재시도 커밋에는 실행 기록이 남아 있지 않은데, 그 이유도 확인하지 못했습니다. 두 번째 재시도에서 성공한 뒤로는 같은 증상이 다시 나지 않았습니다.
남은 것과 배운 것
- 사이트 웹판은 기기 음성, 앱은 클립. 같은 앱이라도 웹판의 발음은 기기마다 다릅니다. 지금은 이 차이를 받아들이고 있습니다.
- 공식 목록이 있으면 목록은 그대로, 내용은 새로. 출처와 해시, 건수 대조를 데이터 파일 안에 남겨 두면 나중에 “이 단어가 왜 들어갔나”를 묻지 않아도 됩니다.
- 무음 제거는 앞쪽만 자르는 필터를 뒤집어 두 번. 뒤쪽을 직접 자르는 방식은 여러 음절 단어 중간을 끊습니다. 압축 뒤 가장 짧은 클립 몇 개를 들어 보면 바로 드러납니다.
- 목록 파일은 마지막에 쓰지 않거나, 없을 때 티가 나게. 생성 중 무음은 버그가 아니라 순서 문제였지만, 증상만으로는 알 수 없었습니다.
- 정적 사이트는 용량보다 파일 개수를 본다. 빌드가 성공해도 배포 단계가 시간 초과로 끝나면 사이트는 조용히 옛 판으로 남습니다. 푸시 뒤에는 실행 결과와 새 주소의 응답을 직접 확인합니다.
- 같은 증상이 두 번 났다고 같은 원인은 아니다. 두 번째 시간 초과는 파일 수로 설명되지 않았고, 확인하지 못한 것은 확인하지 못했다고 남겨 둡니다.
