우리 한글 교실

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 를 빠뜨리면, 휴대폰이 옛 화면을 계속 써서 판 번호도 옛것으로 보입니다. 꼭 같이 하세요.