Book Play

삽화가 있는 영어 책(고전과 그림책)으로 영어를 배우는 텍스트 어드벤처입니다. 서재는 입문(Starter)·초급(Beginner)·중급(Intermediate) 책장으로 나뉩니다. 첫 화면(서재)에서 책을 고르면, 1980년대 일본 PC 어드벤처처럼 위에는 삽화, 아래에는 메시지 창이 나오고, 상황에 맞는 영어 대사를 말하면 다음 장면으로 넘어갑니다.

실행

./start.sh          # 로컬 서버(기본 8765)를 띄우고 브라우저를 엽니다. 포트: ./start.sh 9000

index.html을 브라우저(Chrome 권장)에서 직접 열어도 동작합니다. 빌드 과정은 없습니다.

공개 사이트: https://book-play.benelog.net/ (GitHub Pages, main 브랜치 루트에서 배포. 커스텀 도메인은 저장소의 CNAME 파일, DNS는 Netlify DNS의 book-play CNAME → benelog.github.io. 옛 주소 https://benelog.github.io/book-play/ 는 여기로 넘어옵니다). GitHub Pages에는 URL 재작성이 없어서 404.html이 요청 경로를 기억했다가 index.html로 넘기는 방식으로 /books/<id>/... 경로를 처리합니다. 서비스 워커(sw.js)가 설치된 뒤에는 워커가 그 경로에 바로 index.html을 내려 주므로 이 우회가 필요 없어집니다. start.sh는 실행 전에 tools/embed-text.py를 돌려 각 책의 text/*.txt를 text/book.js로 변환한 뒤 tools/serve.py를 띄웁니다.

구성

• 서재(Library) — 난이도별 책장(js/library.js의 difficulty: starter · beginner · intermediate) 위에 책 표지가 놓여 있습니다. 표지 그림은 images/cover.jpg가 있으면 그것을, 없으면 chapter-01.jpg를 씁니다. 책을 꺼내면 펼친 책(왼쪽 삽화, 오른쪽 본문) 화면으로 넘어가고, 화면 전환 때 오른쪽 페이지가 넘어가는 애니메이션이 있습니다.

• 출처와 라이선스 — 책마다 제목 페이지 아래 "Sources & licences"에 원문과 삽화의 출처·라이선스를 표시합니다. 내용은 js/library.js의 credits 항목입니다.

• URL — 경로 방식입니다: /books/<id> (책 제목 화면), /books/<id>/chapters/<n> (읽기), /books/<id>/chapters/<n>/play (대화 장면), /books/<id>/listen (오디오북). start.sh의 서버(tools/serve.py)가 이 경로를 index.html로 연결합니다. GitHub Pages에서는 404.html이 요청한 경로를 기억해 두고 앱으로 넘깁니다. index.html을 file://로 직접 열면 같은 경로를 # 뒤에 붙입니다: index.html#/books/<id>/chapters/3.

• 원문 읽기(Read) — 장별 영어 원문과 TTS(브라우저 내장 음성 합성). 문장 단위로 강조됩니다. Gutenberg 텍스트의 _밑줄_ 이탤릭 표기는 기울임체로 표시하고 음성에서는 뺍니다. 본문의 [Picture 01-1: 설명] 문단은 images/pictures/01-1.jpg 그림으로 표시합니다(파일이 없으면 생략).

• 오디오북(Listen) — 제목 페이지의 "🎧 Listen to the whole book"(읽기 화면에서는 "🎧 Audiobook", 그 장부터). 제목부터 마지막 줄까지 책 전체를 이어서 읽어 줍니다. 미리 녹음한 줄은 MP3(books/<id>/audio/<key>.mp3, 어린 왕자는 영화의 film/audio/)로, 나머지는 브라우저 음성으로 읽습니다. 속도는 0.6×~2×(lp.v1.settings의 listenRate), 듣던 위치는 lp.v1.<id>.listen에 저장됩니다. 화면을 꺼도 책 끝까지 재생됩니다. <audio> 하나가 녹음과, 브라우저 음성이 말하는 동안·줄 사이의 들리지 않는 20Hz 음을 이어서 재생해 휴대폰이 페이지를 미디어 재생 중으로 유지하고, 잠금 화면·이어폰 버튼(Media Session: 재생/정지, 이전·다음 장, 앞뒤 줄)으로 조작합니다. 다만 브라우저 음성은 화면이 꺼지면 멈추는 기기가 있어(iPhone Safari 등) 녹음된 책이 확실합니다. 녹음은 tools/book-voices.py(skill book-voices)로 만듭니다. 대본은 js/narration.js, 재생은 js/listen.js.

• 단어 사전 — 본문의 단어를 클릭하면 팝오버에 영어 뜻(English Wiktionary), 한국어 뜻(한국어 위키낱말사전이 있으면 그것, 없으면 MyMemory 기계 번역), 발음(Free Dictionary API 녹음 또는 TTS)이 나옵니다. 팝오버의 "▶ Read from here"로 그 문장부터 읽기를 시작할 수 있고, Naver·Daum 사전 링크도 있습니다. cyclones·carried처럼 활용형은 원형을 찾아 함께 보여 줍니다. 찾은 결과는 localStorage(lp.v1.dict)에 캐시되어 오프라인에서도 다시 볼 수 있습니다. 코드는 js/dict.js. readOnly: true인 책은 Play 탭이 없고, 읽기 화면의 "Finished" 버튼으로 장을 완료합니다. Chrome의 Google 네트워크 음성은 일시 정지가 바로 반영되지 않을 수 있습니다. 정지 버튼과 문장 클릭은 항상 동작합니다.

• 대화 장면(Play) — 상황 설명과 상대의 대사가 영어로 나오면 알맞은 대사를 답합니다.

  • Type(주관식): 영어로 직접 입력. 핵심 단어 기반으로 판정하며 오타 한 글자는 허용합니다. 두 번 틀리면 힌트, 세 번 틀리면 정답 예시를 보여 주고 따라 입력하게 합니다.
  • Choose(객관식): 네 개의 대사 중 하나를 고릅니다. 장면마다 손으로 쓴 오답 세 개가 섞여 있습니다.
  • 답 방식은 책 제목 화면과 장면 화면에서 언제든 바꿀 수 있고, 설정은 브라우저에 저장됩니다.

• 안내 언어 — 게임 안내(상황, 지시문, 힌트, 버튼)는 모두 영어입니다. "Show Korean help"를 켜면 영어 아래에 한국어 도움말이 함께 표시됩니다.

• 진행 저장 — 책별로 현재 장, 완료한 장, 장면 위치, 시도 횟수를 브라우저 localStorage에 저장합니다.

• 최근 학습(Recent study) — 서재 화면의 종이 메모에 최근 활동이 나옵니다. 마지막으로 읽던 장으로 가는 "Continue" 버튼, 이번 주 통계(완료한 장·끝까지 들은 장·찾아본 단어·연속 학습일), 최근 찾아본 단어 칩(클릭하면 다시 사전), "Show all activity"로 날짜별 전체 목록. 기록되는 활동은 장 열기(read/play), TTS로 장 끝까지 듣기, 장 완료, 단어 검색이며 전역 키 lp.v1.history에 최대 400개를 보관합니다. 같은 장을 다시 열거나 같은 단어를 다시 찾으면 새 항목 대신 기존 항목이 위로 올라옵니다.

• PWA — manifest.webmanifest와 sw.js가 있어 Chrome·Edge·Android에서 앱으로 설치할 수 있습니다(서재 하단 "Install app" 버튼, iOS는 공유 → 홈 화면에 추가). 서비스 워커는 앱 껍데기를 미리 캐시하고, 열어 본 책 파일을 방문할 때마다 캐시하므로 한 번 본 장은 오프라인에서도 열립니다. 책 제목 페이지의 "Save for offline"은 그 책의 scenes.js·본문·장별 삽화를 한 번에 저장합니다. 새 버전을 배포하면 "A new version of Book Play is ready" 토스트가 뜨고 Reload로 갱신합니다. file://에서는 서비스 워커가 없으므로 이 기능만 빠지고 나머지는 그대로 동작합니다.

• 어린 왕자 영화(Film) books/little-prince/film/index.html — 어린 왕자 제목 페이지의 "▶ Watch the whole book as a film". 헌사부터 27장 끝까지 번역문 전체를 자막으로 보여 주고 미리 녹음한 음성으로 읽습니다. 화자(조종사)의 서술과 등장인물의 대사를 나눠, 인물마다 한 가지 목소리와 자막 색을 씁니다. 녹음은 OpenAI gpt-4o-mini-tts로 만든 film/audio/<key>.mp3이고(tools/book-voices.py little-prince, 오디오북도 같은 녹음을 씀), 녹음이 없는 줄은 브라우저 음성(음색·높낮이로 인물 구분)으로 읽습니다. 장 삽화와 본문 속 그림(images/pictures/)이 별이 뜬 공간에 판처럼 떠 있고, 카메라가 판 사이를 날아가며 말하는 인물 쪽으로 다가갑니다. CSS 3D로 만들었습니다. file://에서는 WebGL이 로컬 이미지를 텍스처로 쓸 수 없기 때문입니다. 자막은 지금 읽는 단어를 밝혀 줍니다(film/timing.js의 단어 시각, 브라우저 음성은 단어 경계). 층을 나눈 그림(98장)은 하늘이 땅·인물보다 덜 움직여 깊이가 생기고, 인물이 눈을 깜빡이며 말하는 인물의 입이 녹음 음량에 맞춰 열립니다. 혼자 선 인물은 숨을 쉬고 목도리 끝이 흔들리며, 밤하늘의 별이 반짝입니다(film/motion.js). ?motion=0이면 전처럼 정지 그림, 동작 줄이기 설정이면 단어 강조만 남습니다. 녹음도 브라우저 음성도 없으면 자막만으로 진행합니다. 스페이스 재생/정지, ← → 문장, [ ] 장, f 전체 화면. 이어 보기 위치는 lp.v1.little-prince.film에 저장합니다.

icons/ 앱 아이콘 (icon.svg 원본, PNG는 ImageMagick으로 변환) books/README.md 책 추가 가이드 books/_template/ scenes.js 템플릿 books/little-prince/ 어린 왕자: scenes.js, art.js(대체 SVG 삽화), text/, images/(pictures/ 본문 속 그림), film/(낭독 영화: index.html, film.js 재생(대본은 js/narration.js), film.css, cast.js 인용마다 화자·인물별 목소리, shots.js 그림 속 인물 위치, audio/ 녹음 음성 MP3, audio.js 녹음 목록·길이, timing.js 입 모양·단어 시각, motion.js 층 시차·깜빡임·입·자막 단어 강조, layers.js 층·얼굴 조각 위치), images/layers/<그림>/ (far.jpg 먼 층, mid.webp 땅·인물, <인물>-face.webp 눈 감음|입 반|입 열림, fig-.webp 숨 쉬는 인물·목도리 끝, stars-.webp 반짝이는 별) books/wizard-of-oz/ 오즈의 마법사: scenes.js, text/, images/ (원문·삽화 내려받기 안내는 각 README) books/alice-in-wonderland/, books/peter-rabbit/, books/grimms-fairy-tales/, books/peter-pan/, books/red-raincoat/, books/efficiency-expert/, books/sherlock-holmes/ 같은 구조 tools/serve.py 경로 방식 URL을 지원하는 로컬 서버 tools/embed-text.py text/*.txt → text/book.js 변환 (start.sh가 자동 실행) tools/test.js node tools/test.js — 파서·판정·모든 책의 장면 데이터·오디오북 대본·어린 왕자 영화 검사 tools/load-book.js node 도구들이 책(장면·본문·cast·녹음 목록)을 앱과 같은 방식으로 읽어 들이는 공용 모듈 tools/book-quotes.js node tools/book-quotes.js [from] [to] — 책의 인용문과 cast.js의 화자를 나란히 출력 tools/book-voices.py 책 녹음: 오디오북·어린 왕자 영화의 줄마다 OpenAI TTS 또는 로컬 Kokoro (녹음이 없는 줄만; .js 목록을 다시 씀; --sample 목소리 샘플) tools/book-audio.js node tools/book-audio.js [out] — 녹음을 오디오북 순서·쉼대로 이어 책 한 파일(장 표시)과 장별 파일(앨범 태그) .m4a로 tools/kokoro-tts.py book-voices.py가 uv로 돌리는 로컬 Kokoro-82M 음성 생성기 tools/film-timing.py 녹음마다 입 모양 곡선(50ms)과 단어 시각(faster-whisper) → film/timing.js (없는 것만) tools/film-layers.py 그림을 먼 층·땅 층으로 나누고 얼굴 조각을 만듦 (Codex 편집 + rembg) → images/layers/, film/layers.js tools/film-motion-check.py headless Chrome으로 층·얼굴을 원본과 대조한 contact sheet tools/gallery.html 삽화 미리보기 (?book=; images/ 파일 우선, 없으면 art.js)