우리 한글 교실
70~80대 어르신을 위한 기초 한글 학습 웹앱입니다. 휴대폰에서 바로 열어 쓰실 수 있습니다.
바로가기: https://urihangul.vercel.app/
이 저장소에는 고급반도 함께 있습니다 — 바로가기 https://urihangul.vercel.app/go/ ,
소스는 go/, 인수인계는 go/MIGRATION.md.
현재 판 1.1 · 판 목록
처음 맡으시거나 다른 PC에서 이어서 하시려면 docs/MIGRATION.md 부터 읽어 주세요.
새 PC 설정 5단계, 전체 구성, 소리 다시 만들기, 판 되돌리기, 다음 작업 후보가 들어 있습니다.
진행 중인 작업은 가지 wip/voice-guide 에 있습니다 — 어디까지 됐는지는 그 문서 0-1절.
배우는 내용
- 기초 학습 — 1단계 자음, 2단계 모음, 3단계 소리 합치기(그+아=가), 4단계 받침 읽기
- 글씨 쓰기 연습 — 자음·모음 24자의 쓰는 순서를 움직이는 그림으로
- 글자 한눈에 보기 — 자음·모음을 골라서 소리로 익히기
- 낱말 배우기 — 생활 낱말 761개, 15개 갈래
- 낱말 맞히기 놀이 — 그림과 소리를 듣고 낱말 고르기
모든 글자와 낱말은 성우 음성으로 들려 드립니다.
나눠 드릴 자료
- QR 코드: qr.png — 휴대폰 카메라로 찍으면 바로 열립니다
- 인쇄용 안내문(A4): poster.pdf — 경로당·복지관 벽에 붙이기 좋습니다
인터넷 없이 쓰기
홈 화면 맨 아래 「소리 모두 받기」를 한 번 누르면 음성 1,226개를 휴대폰에
저장해, 인터넷이 없는 곳에서도 그대로 쓸 수 있습니다. 홈 화면에 추가하면
앱처럼 열립니다.
소리는 audio/audio.bin 한 덩어리로 받습니다. 예전에는 1,226개 파일로
따로 저장했는데, 파일마다 붙는 관리 정보 때문에 10.18MB가 실제로는 12.43MB를
차지해 저장공간이 빠듯한 기기에서 일부가 조용히 빠졌습니다. 한 덩어리로 묶어
10.18MB에 들어가고, 받을 때 요청도 1,226번에서 1번이 되었습니다. 원본 mp3를
그대로 이어 붙인 것이라 음질 손실은 없습니다.
재생할 때는 blob.slice(시작, 끝, 'audio/mpeg') 으로 필요한 자리만 잘라 씁니다.
묶음을 아직 받지 않았으면 예전처럼 낱개 주소(audio/aN.mp3)로 재생합니다.
구성
정적 파일만으로 동작합니다. 서버도 빌드 도구도 프레임워크도 없습니다.
모든 경로가 상대경로라 /hangul/ 아래든 도메인 루트든 그대로 동작합니다.
index.html 앱 전체 (HTML+CSS+JS+데이터 인라인)
sw.js 서비스 워커 (오프라인)
manifest.webmanifest 홈 화면 앱 설정
audio/a0.mp3 … a1225.mp3 성우 음성 1,226개 (인터넷 재생용)
audio/audio.bin 위 1,226개를 이어 붙인 묶음 (내려받기용)
vercel.json 캐시 머리말 설정
tools/ 관리용 스크립트
⚠️ window.AUDIO 와 window.AUDIO_BIN 은 index.html 안에서 메인 스크립트보다
뒤에 삽입됩니다. 스크립트 로드 시점에 읽으면 비어 있으니, 반드시 쓸 때마다
새로 읽어야 합니다.
관리용 스크립트
python tools/clips.py # 대본 1,226개 확인 (index.html 이 원본)
pip install -r tools/requirements.txt # 도구가 쓰는 패키지 (한 번만)
python tools/sample_edge.py # 음질 비교용 시험 음성 (무료)
python tools/regen_audio_edge.py --all --yes # edge-tts 로 전체 재생성 (무료)
python tools/regen_audio_azure.py --sample # 같은 것을 Azure 로 (키 필요)
python tools/build_audio_bundle.py # audio/*.mp3 -> audio/audio.bin (+ index.html 색인)
python tools/stamp_sw.py # index.html 을 고친 뒤 sw.js 캐시 이름 갱신
python tools/regen_qr_poster.py https://주소/ # 주소가 바뀌면 QR·안내문 재발급
python tools/verify.py https://주소/ # 배포된 소리 1,226개 전수 확인
index.html 을 고쳤다면 stamp_sw.py 를 꼭 돌려 주세요. 캐시 이름이 그대로면
휴대폰이 옛 화면을 계속 씁니다.
음성을 다시 만들 때
대본은 index.html 안의 자료(JAUM/MOUM/BATCHIM/WORDS_DATA)가 원본이고,
tools/clips.py 가 그것을 읽어 조각 1,226개(3,872자)를 만듭니다. 낱말을
추가하려면 index.html 의 자료를 고치세요. 대본 파일은 따로 없습니다.
말하기 속도는 교육 설계의 일부입니다. 어르신 배려로 조각마다 다릅니다.
| 속도 | 쓰는 곳 |
|---|
| -10% | 퀴즈 칭찬·점수 (문장이라 너무 느리면 답답합니다) |
| -15% | 낱말, 글자 설명 |
| -20% | 한 글자 또렷이 읽기 |
| -25% | 소리를 이어 붙여 읽기 (귀로 합쳐지는 과정을 들려주는 대목) |
Azure Speech (정식)
$env:AZURE_SPEECH_KEY = "..." # PowerShell. 창을 닫으면 사라집니다
$env:AZURE_SPEECH_REGION = "koreacentral"
python tools/regen_audio_azure.py --voices # 쓸 수 있는 한국어 목소리 보기
python tools/regen_audio_azure.py --sample # 12조각을 설정별로 만들어 비교
python tools/regen_audio_azure.py --all --preset hifi-keep --yes
python tools/build_audio_bundle.py
python tools/stamp_sw.py
요금 — 단가가 100만 자당 $15이고 이 앱 전체가 3,872자이므로 한 번에 약 $0.06(80원)
입니다. 만들 때 한 번만 내고, 어르신이 아무리 많이 눌러도 더 나가지 않습니다.
소리는 mp3로 저장돼 앱에 함께 배포되기 때문입니다.
속도 제한 — 무료(F0) 등급은 60초에 20건입니다. 1,226개를 만들려면 최소 1시간이
걸리니 --free 를 붙이세요. 유료(S0)는 초당 30건이라 5~15분이면 끝납니다.
🔑 키는 환경변수로만 넘깁니다. 저장소에도, 웹앱에도 절대 넣지 마세요.
index.html 은 공개된 정적 파일이라, 키를 넣으면 누구나 꺼내 씁니다.
설정별 용량입니다. 48kHz 로 요청하면 Azure가 48kHz 고음질 모델을 부르므로,
받아서 줄이더라도 처음부터 24kHz 로 받는 것보다 또렷합니다.
| 설정 | 전체 용량 | 비고 |
|---|
hifi-keep | 10.2MB | 지금과 같은 용량, 원본만 고음질 |
hifi-plus | 15.3MB | 뚜렷하게 좋아짐. 기기 저장공간 16MB 이상 |
hifi-raw | 26MB | 다시 담지 않아 손실 0. 어르신 휴대폰엔 부담 |
⚠️ HD(:DragonHDLatestNeural)·MAI 계열 목소리는 말 속도 지정을 무시하는
경우가 있습니다. 바꾸기 전에 --sample 로 느리게 읽히는지 꼭 확인하세요.
edge-tts (지금 쓰는 방식, 무료·비공식)
python tools/regen_audio_edge.py --all --yes (지금과 같은 32kbps) 또는 --raw (재압축 없이,
15.1MB). 공짜지만 비공식 경로라 예고 없이 막힐 수 있습니다. 지금 배포된 소리가 이 방식으로
만들어졌습니다. 자세한 것은 docs/MIGRATION.md 4절.
판 되돌리기
판마다 git 태그가 붙어 있습니다. 첫 화면 맨 아래에 나오는 번호가 지금 그 휴대폰에
깔린 판입니다. "고쳤는데 그대로인데요" 할 때 먼저 볼 곳입니다.
git tag -n1 # 어떤 판들이 있나
git show v1.1 # 그 판에 무엇이 들어갔나
git checkout v1.1 # 들여다보기만 (작업하려면 아래로)
git switch -c fix-1.1 v1.1 # 1.1 에서 가지 쳐서 작업
main 을 되돌려야 한다면 git reset --hard 대신 git revert 를 쓰세요.
이미 푸시된 이력을 지우면 Vercel 배포 기록과 어긋납니다.
git revert <되돌릴커밋>
git push
운영 주소만 급히 이전 판으로 돌리려면, Vercel → 프로젝트 hangul → Deployments
에서 그 판의 배포를 찾아 Promote to Production 하면 됩니다. 저장소는 그대로 둔 채
주소만 바뀌므로, 원인을 찾는 동안 어르신은 멀쩡한 앱을 쓸 수 있습니다.
판을 새로 낼 때
# 1) index.html 의 APP_VERSION 을 올린다
# 2) 캐시 지문을 새로 찍는다
python tools/stamp_sw.py
git add -A && git commit -m "..." && git push
# 3) 태그를 붙인다
git tag -a v1.2 -m "무엇이 바뀌었는지"
git push origin v1.2
APP_VERSION 만 올리고 stamp_sw.py 를 빠뜨리면, 휴대폰이 옛 화면을 계속 써서
판 번호도 옛것으로 보입니다. 꼭 같이 하세요.
