EchoTale 🐢📖

AI가 읽어주는 단계별 영어 그림책 — 발음 부담 없이, 수준에 맞게, 누구나 무료로.

Read it. Hear it. Echo it. Speak it.

▶ 3분 시연영상 — https://youtu.be/ohUmbobhoEY (실제 배포본을 스크립트로 구동해 녹화했습니다. 녹화 파이프라인은 scripts/demo-video에 있습니다.)

EchoTale은 초등 영어 학습자를 위한 오픈소스 PWA입니다. AI가 생성한 그림책과 원어민 음성으로 Read → Hear → Echo → Speak(읽고 → 듣고 → 따라 하고 → 말하기) 셰도잉 루프를 제공합니다. 계정 없이 바로 실행되며, 학습 상태는 기기에 로컬 저장됩니다.

• 352권의 단계별 콘텐츠 — 그림책 140 · 생활영어 210 · 그리스로마신화 2
• preA1 ~ 단계(CEFR 기반)·연령대(ageBand)별 라이브러리, 학생이 스스로 수준을 선택
• 게이미피케이션 — 레벨 / XP / 도장(스탬프)으로 지속 학습 동기부여
• 단어 학습 — Leitner 기반 간격 반복(SRS)으로 어휘 훈련
• 완전 로컬 — 계정·로그인 없이 즉시 사용. 학습 기록은 기기에만 저장되며 서버로 전송하지 않습니다

---

⭐ 무엇이 다른가 — "검증된 학습"

대부분의 학습 앱은 재생 버튼만 눌러도 '완료' 가 됩니다. 기록은 쌓이지만 그 숫자가 실제 학습을 뜻하지 않아, 교사도 학부모도 신뢰할 수 없습니다. EchoTale은 학습이 실제로 일어났을 때만 기록이 쌓이도록 설계했습니다.

1. 지연 추적(Delayed-Track) 쉐도잉

"따라 읽기"는 보통 오디오를 두 번 틀어 주는 합창 낭독입니다. EchoTale은 오디오를 한 번만 흘리면서 하이라이트 트랙을 둘로 굴립니다 — 원어민 트랙과, 설정한 지연만큼 뒤처지는 내 차례 트랙. 원어민이 말하는 도중에 한 박자 뒤에서 겹쳐 말하는 실제 쉐도잉입니다.

단계	이름	지연	원어민 볼륨
1	듣기	—	1.0
2	같이 읽기	0ms	1.0
3	느린 쉐도잉	800ms	↓
4	표준 쉐도잉	450ms	↓
5	블라인드	300ms + 텍스트 가림	0.45

단계가 올라갈수록 원어민 목소리를 줄여 자기 목소리를 듣게 합니다. 불변식 echoWord ≤ activeWord 를 유닛 테스트로 고정했습니다.

2. 치팅이 통하지 않는 진도

• 청취 커버리지 — 오디오가 끝까지 재생된 문장만 '들음'으로 인정합니다. 페이지 점프·문장 탭·스킵으로는 절대 쌓이지 않습니다(마킹 지점을 onEnd 한 곳으로 단일화).
• 도장 게이트 — 커버리지 90% 미만이면 도장 버튼이 아예 나오지 않고 "아직 안 들은 문장이 N개 있어요"가 대신 뜹니다.
• 어디를 안 들었는지 보여줍니다 — 막기만 하고 위치를 안 알려 주면 책을 통째로 다시 듣게 됩니다. 문장마다 ✓ / "아직" 표시, 쪽 번호 옆 "안 들음 N", 도장 카드의 쪽 지도(3쪽 1개), 그리고 "안 들은 문장만 듣기" — 이미 들은 문장은 건너뛰고 빠진 문장만 이어서 재생합니다.
• 같은 탭 안에서는 들은 기록이 유지됩니다 — 홈에 다녀오거나 새로고침해도 커버리지가 0%로 돌아가지 않습니다(도장을 찍거나 "처음부터 다시 읽기"를 누르면 초기화).
• 마지막 도장 — 완독 왕관은 이해 퀴즈 80% 이상을 추가로 요구합니다.
• 응답속도 가드 — 700ms 미만의 단어 응답은 XP·퀘스트에 반영하지 않습니다(찍기 차단).
• 퀴즈 문항·보기는 매 시도마다 섞여 답 위치 암기가 통하지 않습니다.

직접 확인해 보세요 — 아무 책이나 열어 듣지 않고 마지막 쪽으로 넘기면 도장이 찍히지 않습니다.

2-1. 학교 기기에서 흰 화면이 되지 않게

배포할 때마다 정적 청크의 해시 파일명이 바뀌고 이전 배포분은 더 이상 서빙되지 않습니다. 학교 공용 기기가 낡은 HTML을 오래 들고 있으면(탭을 며칠씩 열어 둠·회선이 끊긴 순간의 캐시 응답) 사라진 청크를 요청해 예외 하나 없이 리액트가 통째로 죽고 흰 화면이 됩니다. 그래서 리액트 바깥에서 도는 인라인 복구 스크립트를 넣었습니다.

• 정적 자산 로드 실패(캡처 단계 error)·ChunkLoadError 감지 → 캐시를 버리고 1회 자동 재적재
• 아무 신호 없이 죽는 경우 대비 — load 완료 후에도 리액트가 안 붙었으면 재적재(느린 회선 오탐 없음)
• 재적재로도 안 되면 흰 화면 대신 "새로 열기" 안내 카드를 직접 그립니다
• 안전장치: 60초 쿨다운(새로고침 루프 금지)·오프라인이면 시도 안 함·localStorage(학습 기록)는 건드리지 않음

3. 자가신고 없는 어휘 학습

"알아요" 버튼을 폐지하고, 보유한 1,000단어로 5가지 문제 유형(듣고 고르기 · 뜻 고르기 · 영어로 고르기 · 예문 빈칸 · 철자 조립)을 자동 생성합니다. Leitner 박스가 올라갈수록 인식형에서 산출형으로 난이도가 오르고, 마스터 단계도 60일 뒤 망각 재검을 거칩니다.

4. 런타임 AI 호출 0

AI는 콘텐츠를 만들 때만 씁니다. 배포된 앱은 생성이 끝난 정적 자산만 재생하므로 API 키가 필요 없고 사용자당 추론 비용이 0 입니다. 352권 규모의 AI 생성 콘텐츠를 무료로 영구 공개할 수 있는 이유입니다.

---

🎯 이 프로젝트가 풀려는 사회 문제

한국 초등 영어 교육과정은 스피킹을 강조하지만, 교실 현장에는 구조적 병목이 있습니다.

1. 교사 1인의 발음 시범 부담 — 교사가 원어민 수준 발음이 아닌 경우가 많은데도 매 수업 발음 모델을 직접 제공해야 합니다.
2. 수준별 개별 지도의 물리적 한계 — 25~30명 한 학급에서 학생마다 다른 영어 수준을 1:1로 봐주는 것은 사실상 불가능합니다.
3. 사교육 접근성 격차 — 도농 간·소득 간 스피킹 학습 기회의 차이가 큽니다.

EchoTale은 이 문제를 다음과 같이 해소합니다.

• AI 음성이 정확한 발음 모델을 대신 제공 → 교사의 발음 시범 부담 해소
• preA1~ 단계별 콘텐츠 + 자기선택 학습 → 학생 개인 수준에 맞춘 자율 학습(메타인지·자기주도성 훈련)
• 계정 없이 무료 배포 → 방과후·자율학습·가정에서 교사 개입 없이도 스피킹 훈련, 사교육 여건과 무관하게 동일 품질의 콘텐츠 접근

이 설계는 현직 초등교사가 교실에서 직접 겪은 어려움에서 출발했습니다.

---

🧱 기술 스택

영역	사용 기술
프레임워크	Next.js 16 (App Router) · React 19 · TypeScript 5
스타일	Tailwind CSS 4
배포	Cloudflare Workers (OpenNext) · Wrangler
데이터	정적 시드 JSON(data/seed/) + 로컬 우선 학습 상태
AI 에셋	일러스트 = OpenAI Codex CLI $imagegen (3,114장) + Meta AI (782장) · 음성(TTS) = OpenAI gpt-4o-mini-tts (nova)

AI는 콘텐츠를 만들 때(빌드·시드 타임)만 사용합니다. 배포된 앱은 생성이 끝난 정적 자산만 재생하므로 런타임에 AI 모델을 호출하지 않습니다(API 키 불필요).

---

📁 저장소 구조

data/seed/         # 책 원문(JSON): 제목·레벨·페이지·문장·단어·퀴즈
public/seed/       # 생성된 미디어 에셋(그림 PNG, 낭독·단어 MP3)
  ├─ <book-slug>/  #   책별 일러스트 + 문장 낭독 음성
  └─ _words/       #   전 권 공용 단어 발음(dedup)
scripts/           # 콘텐츠 생성 파이프라인(텍스트→음성→그림→QA)
src/               # 앱 소스(Next.js)

참고 — 에셋 배포 방식: 이 저장소는 352권 전권의 삽화(WebP 3,896장)와 낭독·단어 음성(MP3)을 모두 포함합니다. 별도 내려받기 없이 클론 즉시 전체 콘텐츠가 동작합니다. 다만 그만큼 저장소가 큽니다(약 1.8GB) — 코드만 빠르게 보시려면 git clone --filter=blob:none 을 권합니다.

용량 절감을 위해 원본 PNG는 커밋하지 않고 WebP만 배포합니다(PNG 11.4GB → WebP 0.73GB, -93.6%). 원본이 필요하면 scripts/ 의 생성 스크립트로 재생성할 수 있습니다.

---

🚀 실행 방법

# 1) 의존성 설치
pnpm install

# 2) 개발 서버
pnpm dev            # http://localhost:3000

# 3) (선택) 에셋 재생성 — OpenAI API 키 필요
#    .env.local 에 OPENAI_API_KEY 설정 후:
pnpm seed:audio     # 문장 낭독 음성 생성 (OpenAI nova)
pnpm seed:words     # 단어 발음 생성     (OpenAI nova, dedup)
#    이미지 생성은 scripts/gen-storybook-images.mjs (Codex CLI $imagegen) 참고

샘플 도서만으로는 API 키 없이도 바로 열람·재생됩니다.

---

🔐 라이선스

• 소스 코드: MIT License — 의존성 전 항목이 MIT/ISC로 라이선스 충돌이 없습니다.
• 생성 미디어 에셋(그림·음성): 코드가 아닌 AI 생성 에셋이며 생성 엔진이 두 갈래입니다. 삽화는 OpenAI Codex CLI $imagegen 3,114장 + Meta AI 782장(86권), 음성은 전량 OpenAI gpt-4o-mini-tts. OpenAI 생성분은 약관상 출력물 소유권이 생성자에게 귀속되어 MIT로 재배포하며, Meta AI 생성분은 대상 파일을 scripts/.meta-manifest.json 에 전건 기록해 두었으니 재사용 시 Meta AI 약관을 직접 확인하세요.
• 개인정보: 앱은 계정·개인정보 없이 로컬 저장만으로 완전히 동작하며, 학습 기록을 서버로 전송하는 경로가 없습니다. 저장소·에셋 어디에도 학생 개인정보나 외부 저작물이 포함되어 있지 않습니다.

출처·라이선스 전체 고지는 NOTICE.md 를 참고하세요.

---

🗺️ 로드맵

• 오프라인 책 팩(Service Worker) — "비행기에서도" 사용
• 학생 발화를 분석해 적정 난이도를 추천하는 자동 매칭(현재는 자기선택 방식)
• 발음 정확도 피드백(선택적 온디바이스 평가)
• 콘텐츠 다국어 확장 · 쉐도잉 엔진의 독립 라이브러리 분리

마이크 발음 평가를 왜 지금 넣지 않았나 — 슬로건이 Speak 로 끝나는데 마이크를 쓰지 않는 것은 의도적 선택입니다. ① 발음 채점은 상용 영어앱의 레드오션이라 변별력이 없고, ② 기기별 에코 제거 편차와 iOS Safari의 음성 인식 불안정으로 현장 시연이 깨질 위험이 가장 큰 기능이며, ③ "검증된 학습"은 청취 커버리지 + 객관식 어휘 + 이해 퀴즈만으로 성립하기 때문입니다. 절약한 몫은 쉐도잉 엔진 정교화에 넣었고, 나중에 음성 지표를 붙일 수 있도록 ReadSession 스키마에 자리를 비워 두었습니다. 자세한 판단 근거는 docs/UPGRADE-PLAN.md 1절 참고.

---

현직 초등교사가 만든, 교실에서 출발한 오픈소스 영어 학습 도구입니다.