Ертегім
Интерактивная голосовая сказка: ребёнок 3–7 лет отвечает голосом и влияет на сюжет, реплики на казахском с русским подстрочником. Подробнее об идее — IDEA.md.
Структура
| Каталог | Назначение |
|---|
public/ | детское приложение (статика), деплоится Vercel: index.html — библиотека (главный экран), story.html — сказка/урок |
api/ | Vercel Edge functions (transcribe.js, classify.js) |
server/ | локальный Bun-сервер: server.js, bins.js |
lib/ | модули без DOM/Bun-зависимостей (blocklist, STT-подсказки, выбор транскрипта, классификатор, Origin-guard) |
tools/ | prerender.py, dump-story.js, requirements.txt |
tests/ | bun test |
docs/ | сценарий, статус-отчёты, спеки |
Быстрый старт
cp .env.example .env # вписать GROQ_API_KEY
bun server/server.js
Открыть http://localhost:3000 — это библиотека (выбор сказки или урока); сама сказка —
http://localhost:3000/story.html. Панель оператора (скрыта от ребёнка) — клавиша `,
значок ⚙ в шапке, либо параметр ?op=1 в URL (/story.html?op=1).
Без GROQ_API_KEY и/или без ffmpeg/whisper/piper приложение всё ещё работает: живой STT и
live-TTS отключаются, но заранее пре-рендеренные .wav в public/audio/ и ручные кнопки
оператора (✅/🔁/⏭) позволяют пройти историю без микрофона.
Переменные окружения
Порядок разрешения бинарей: явный env → PATH → tools/.venv (для PIPER_BIN — сначала
tools/.venv, затем PATH) (см. server/bins.js).
| Переменная | По умолчанию | Если не задана/не найдена |
|---|
GROQ_API_KEY | — | нет STT (Whisper) и LLM-классификатора ответов |
GROQ_STT_MODEL | whisper-large-v3 | — |
STT_LANGS | auto,ru | — |
ALLOWED_ORIGIN_EXTRA | — | API на Vercel принимает только *.vercel.app / localhost; свой домен нужно перечислить здесь через запятую (ertegim.kz,*.ertegim.kz), иначе все запросы получат 403 (см. lib/origin-guard.js) |
GROQ_TIMEOUT_MS | 8000 локально, 12000 на Vercel | — |
PORT | 3000 | сервер слушает 3000 |
FFMPEG_BIN | ffmpeg из PATH, иначе бинарь imageio-ffmpeg из tools/.venv | нет loudnorm-препроцессинга и pitch-shift для TTS, локальный Whisper недоступен |
WHISPER_BIN | whisper-cli из PATH | только Groq STT |
WHISPER_MODEL | tools/models/ggml-small.bin, если существует | только Groq STT |
PIPER_BIN | tools/.venv/bin/piper (Windows: tools/.venv/Scripts/piper.exe), иначе piper из PATH | /api/speak отвечает 503, клиент переключается на пре-рендеренные .wav |
PIPER_VOICE_KK | tools/voices/kk_KZ-issai-high.onnx, если существует | как выше |
Озвучка (пререндер)
python3 -m venv tools/.venv
tools/.venv/bin/pip install -r tools/requirements.txt
tools/.venv/bin/python tools/prerender.py
Скачает голос Piper в tools/voices/ (с HuggingFace; если он недоступен в вашей сети — тот же
голос берётся из GitHub-релиза rhasspy/piper v0.0.2) и озвучит все реплики истории и уроков
в public/audio/. --force — переозвучить всё заново; --only id1,id2 — только перечисленные
реплики. Реплики уроков (a_*, q_a_*) рендерятся медленнее (LESSON_LENGTH_SCALE), как
просит docs/lesson-letter-a.md.
Тесты
bun test
Лаборатория STT
Распознавание идёт в два прохода: один и тот же клип отправляется в Groq Whisper
дважды параллельно — по одному вызову на каждый элемент STT_LANGS
(по умолчанию auto,ru), — а lib/stt-pick.js выбирает тот
результат, который лучше отвечает на вопрос узла (счёт, развилка, рифма,
поддержка), отбрасывая галлюцинации Whisper («Субтитры сделал DimaTorzok») и
помечая тихие/неуверенные записи как lowConfidence — тогда сказка мягко
переспрашивает, не дёргая LLM.
Почему auto,ru и whisper-large-v3
Раньше проходы были kk,ru на whisper-large-v3-turbo. На живом тесте с
телефона реальные казахские ответы возвращались либо пустыми, либо уверенной
казахоподобной бессмыслицей («үңі ғыңңқ») — turbo с принудительным
language=kk заставляет модель «договорить» фонетику низкоресурсного языка
вместо честного низкого confidence. Это известный режим отказа, и он хуже
пустого ответа: галлюцинация выглядит как уверенное распознавание и идёт
дальше по пайплайну.
Поэтому по умолчанию: полная модель whisper-large-v3 (точнее turbo на
низкоресурсных языках; задержка не критична — TTS/микрофон и так занимают
8-12 с под анимацией «думаю») и auto вместо kk — язык определяет сам
Whisper, а словарная подсказка (lib/stt-hints-core.js) и
isMostlyCyrillic() остаются. Каждый вопрос в story.js и так принимает
ответ на казахском или русском, так что заставлять модель выбирать
более сложный язык незачем.
STT_LANGS=kk,ru возвращает прежнее поведение (принудительный казахский),
STT_LANGS=auto — один проход. Порядок важен: при равном счёте
lib/stt-pick.js выбирает первый в списке.
Цена: два прохода — это два вызова Groq STT на каждый ответ ребёнка (вдвое
больше запросов и стоимости, чем при одном проходе); пороги noSpeechProb 0.6 и
avgLogprob −1.2 в lib/stt-pick.js взяты «на глаз» и не настроены — их и надо
откалибровать прогоном лаборатории на реальных детских записях.
Чтобы настроить это на реальных детских записях, есть локальная страница
(только bun server/server.js, на Vercel её нет):
GROQ_API_KEY=... bun server/server.js
# открыть http://localhost:3000/lab.html
Выбрать записи детей, узел (q_tracks / q_fork / q_courage / q_echo), для
счёта — trackCount, при необходимости поправить langs (подставляется из
STT_LANGS сервера — так и сравнивают kk,ru против auto,ru против auto),
вписать ожидаемый ответ напротив каждого файла и нажать «Run turbo» / «Run v3».
Таблица покажет оба транскрипта (с пометкой «запрошено→распознано», чтобы было
видно, что именно определил auto), выбранный, score, confidence и совпадение
с ожидаемым; внизу — точность и среднее время на файл для каждой модели.
Деплой
Vercel zero-config: public/ как статика, api/ как Edge functions. В настройках проекта
на Vercel задать переменную GROQ_API_KEY. Live TTS (/api/speak) на Vercel недоступен —
используются только пре-рендеренные .wav. На Vercel также нет ни живого TTS, ни
LLM-классификатора (/api/classify есть только у локального сервера) — ответ ребёнка
оценивает локальный классификатор в браузере (classify-local.js).
public/voices.html — dev-страница для подбора голоса Piper, работает только с локальным
сервером.
Что проверять на реальном устройстве
- STT и LLM-классификацию живьём (Groq): распознавание и разбор детских ответов.
- Pre-roll (обрезание первого согласного в записи).
- VAD-пороги записи на реальных детях, а не на взрослом голосе:
VAD_START_RMS
(0.035) измерен на телефоне до появления ограничений
noiseSuppression/autoGainControl, их надо перемерить в /lab.html.
STT_LANGS: auto,ru против kk,ru на детских записях — по одному вызову
Groq на проход, так что сравнение стоит денег.- Казахские реплики (
q_fork, q_courage, echo_reveal, thanks) — носителем языка.
База сказок
Кроме первой сказки «Түлкі інісін іздейді», на главной есть ещё три, каждая на 4–5 минут и с пятью
речевыми играми:
- «Аю мен бал» (
?lesson=bear-honey): согласиться помочь медведю, пожужжать «ж-ж-ж», посчитать
пчёл, найти мёд среди картинок, сказать «рақмет».
- «Үкі жұлдыз іздейді» (
?lesson=owl-star): поздороваться «сәлем», позвать по-совиному
«у-у-у», посчитать звёзды, найти звёздочку, загадать желание.
- «Түлкінің туған күні» (
?lesson=fox-birthday): поздравить лисёнка, посчитать шарики, найти
красный, задуть свечки «ф-ф-фу» (упражнение на выдох), придумать подарок.
Сказки — это данные в реестре TALES (public/story.js): полка, наклейки, отчёт, кабинет,
серверное распознавание (lib/tale-forms.js, генерируется node tools/tale-forms.js) и озвучка
подхватывают новую сказку сами. Как добавить сказку и все реплики для вычитки —
docs/tales.md.
Голоса героям
У каждого героя может быть свой голос: tools/prerender_voicestudio.py озвучивает лисёнка, сову и
медведя разными голосами локальной моделью VoiceStudio (OmniVoice), выравнивает громкость под Piper и
перерисовывает только изменённые реплики. Пошагово для Windows — docs/voice/voicestudio.md.
Сказка играет готовый файл реплики раньше живого синтеза, поэтому выбранные голоса звучат и на сайте,
и на локальном сервере. Лицензия OmniVoice некоммерческая: для пилота можно, для платного продукта — Piper.
Уроки для особых детей и мягкий режим
Кроме сказки, та же страница story.html запускает короткие уроки букв для детей с
задержкой речи, дизартрией, РАС: story.html?lesson=letter-a (карточка «А әрпі — түлкімен» на
главном экране index.html). Урок «Буква А» (3–5 минут) описан в docs/lesson-letter-a.md
и реализован как LESSON_A + ACTIVITIES в public/story.js:
mode: "imitate" — ребёнок повторяет звук/слово за героем; принимаются детские искажения
(accept), любое слово на нужный звук (acceptPrefix), заикание и растяжка схлопываются
(destutter — одинаково в public/classify-local.js и lib/stt-pick.js, тест на паритет);mode: "pick" — две крупные картинки на сцене; ответить можно голосом или нажатием
(для неговорящих детей). Нажатие не на ту картинку — не ошибка: герой мягко поправляет и
спрашивает снова, не тратя переспрос;- крупная буква всегда в одном углу сцены, картинки — простые SVG (
public/images/lesson-a/);
- в отчёте родителю — свои четыре навыка и строка «👆 N жауап — суретті көрсетіп».
Ещё два урока по той же схеме — «О әрпі» (?lesson=letter-o: звук «о», слово «от», выбор от/мысық,
любимая игрушка) и «Ұ әрпі» (?lesson=letter-u: звук «у» по-казахски, слово «ұшақ», выбор
ұшақ/алма, «что тебе нравится?»). Реплики, принимаемые ответы и почему «Ұ», а не «У» —
docs/lesson-letters-o-u.md. Все буквенные уроки собраны в
LETTER_LESSONS (public/story.js); общий тест — tests/letter-lessons.test.js.
Мягкий режим (🕊 в панели оператора, ?mode=gentle, уроки включают его сами): тишина до
конца фразы 3,5 с вместо 1,7, ожидание ответа 15 с вместо 8, два переспроса вместо одного,
без искр, тряски и дрейфа фона (body.gentle). Пороги VAD_* в public/app.js остаются
полевыми значениями по умолчанию; профиль лежит рядом в GENTLE_VAD. Выбор оператора
сохраняется на устройстве (ertegim.gentle).
Кабинет логопеда / родителя — /cabinet.html (ссылка внизу главной и в панели оператора),
за PIN-экраном. Несколько детей на одном устройстве (public/profiles.js): у каждого своя история,
память повторов и наклейки (ключи localStorage получают суффикс :<id>; первый профиль остаётся на
старых ключах, так что существующие данные не теряются). На ребёнка задаются: мягкий режим
(всегда/никогда/как у занятия), число переспросов, пауза в конце фразы и ожидание ответа, «задание
на сегодня» (выделяется на главной) и сохранение транскриптов попыток — по умолчанию выключено,
как и обещает приватная заметка в отчёте. В кабинете: динамика (доля ответов с первого раза и время
реакции по занятиям), список занятий с попытками, наклейки, печать/PDF и экспорт JSON.
Наклейки (public/stickers.js): за пройденную сказку — «Түлкі досы», за героя на выбранном
пути — сова или медведь, за урок — его буква, за все ответы с первого раза — «Жұлдыз». Новые
показываются на финальном экране, вся коллекция (полученные и ещё нет, с подсказкой как получить) —
на главном. Хранятся в localStorage (ertegim.stickers), повторно не выдаются.
Реплики урока входят в tools/dump-story.js, поэтому tools/prerender.py озвучит их в
public/audio/. Пока .wav нет, текст реплики держится на экране примерно столько, сколько
её говорил бы герой (readingTimeMs), а не пролетает за полсекунды.
Домашнее задание: логопед ↔ дом
Данные живут в браузере одного устройства, поэтому кабинет логопеда и телефон родителей связаны
без сервера и аккаунтов (public/homework.js):
- Логопед → дом. В кабинете, раздел «📝 Домашнее задание»: отметить занятия, сколько раз в
неделю, заметку для родителей → «🔗 Ссылка для родителей». Задание упаковано в хэш ссылки
(
/#hw=…), он не уходит на сервер. Ссылку отправляют в WhatsApp/Telegram.
- Дома. Родитель открывает ссылку, главный экран показывает задание и просит «Қабылдау».
Дальше на главной виден прогресс недели («А әрпі — 2/2 ✅»), на карточках — бейджи.
- Дом → логопед. В кабинете на телефоне — «📤 Отправить логопеду (файл)» (через «Поделиться»
или скачиванием). Логопед жмёт «📥 Загрузить результаты из дома» — занятия добавляются в историю
того же ребёнка (по id из ссылки, затем по имени), повторная загрузка не дублирует.
История хранит до 100 занятий на ребёнка.
Пилот: работа без интернета, оценка взрослым, сохранность данных
- Без интернета (
public/offline.js, public/sw.js). Service worker держит страницы и скрипты
(сначала сеть, потом кэш) и всю озвучку, картинки и ролики лисёнка (сначала кэш; для Safari
отдаёт куски файла по Range). /api/* не кэшируется никогда. Список файлов с хэшами —
public/offline-manifest.json, его пишет node tools/offline-manifest.js; тест падает, если
список устарел, поэтому после новой озвучки или картинок перезапустите генератор. В кабинете,
раздел «📱 Это устройство», — «Скачать для работы без интернета» с прогрессом.
- «Ата-ана бағалайды» (
app.js, adultJudgeReason). Без сети, без микрофона или после двух
сбоев распознавания подряд лисёнок всё равно спрашивает, а взрослый жмёт «✅ Айтты» или
«🔁 Тағы бір рет» на большой полосе под репликой (на развилке — «Өзен» / «Орман»). Картинки
по-прежнему можно нажимать. В настройках ребёнка можно выбрать «Кто оценивает ответ: всегда
взрослый» — для тяжёлых нарушений речи, микрофон тогда не включается. Такие ответы идут в отчёт
отдельной строкой и не считаются «сказанными словами» или временем реакции.
- Резервная копия устройства (
public/backup.js): все дети, история, задания, наклейки — один
файл и восстановление из него. Через 7 дней без копии кабинет напоминает баннером. Кабинет просит
браузер не очищать данные (navigator.storage.persist) и подсказывает на iPhone добавить сайт на
экран «Домой» — иначе Safari стирает данные через 7 дней без посещений.
- Сводка «Все дети» в кабинете (при двух и более детях): последнее занятие, занятия за 7 дней,
задание недели, доля ответов с первого раза и её динамика; первыми идут дети с пометками «не
занимался неделю», «задание отстаёт», «ответов с первого раза меньше».
- Памятка и согласие:
/help.html — как заниматься дома и как логопеду вести пилот (каз./рус.,
печатается), /consent.html — бланк согласия родителей на один лист A4. Бланк — шаблон: перед
пилотом его нужно согласовать с юристом организации; казахский текст стоит вычитать носителю.
- Журнал ошибок (
public/errlog.js): последние 30 ошибок устройства (необработанные исключения,
сбои распознавания, микрофона, озвучки) — кнопка «Скопировать журнал» в кабинете. Ответов детей там
нет. Рядом версия сборки из /api/version (коммит на Vercel, git rev-parse локально).
Документы
