The theoretical foundation of the project is compiled in the main concept ["uchitsya-legko.rf — learning to read as decoding a written code"](/concepts/uchitsya-legko-rf-obuchenie-chteniyu-kak-deshifrovke-pismennogo-koda). It is the central point of the project: it describes the general model, current state, and connects specific concepts.

The project is currently at the **Idea** stage. The basic theory of reading as information reconstruction from a written code has been formed. The information entities on which learning is built have been recorded: object and situation, concept, image, spoken word, sound, written word, letters, and larger structural parts of a word.

Key components of the theory:

- [Reading is word recognition and meaning reconstruction, not sequential letter sounding](/concepts/chtenie-eto-raspoznavanie-slova-i-vosstanovlenie-smysla).
- [A written word connects several representations of the same content](/concepts/pismennoe-slovo-svyazyvaet-neskolko-predstavleniy).
- [Learning to read should go from known supports to the unknown code](/concepts/obuchenie-chteniyu-ot-izvestnyh-opor-k-neizvestnomu-kodu).
- [The oral vocabulary is the recognition base when learning to read](/concepts/ustnyy-slovar-baza-raspoznavaniya-pri-obuchenii-chteniyu).
- [A long word must be revealed through familiar structural parts](/concepts/dlinnoe-slovo-cherez-znakomye-strukturnye-chasti).
- [Hints must gradually disappear as connections are mastered](/concepts/podskazki-dolzhny-postepenno-ischezat).

The practical direction is an interactive system where the child starts with recognizable objects and words, confirms their sound, gets acquainted with the spelling, discovers repeating elements of the written code, and then applies the discovered correspondences to decode new words.

Critical principle: the system must not simultaneously require the mastery of several unknown levels. If the child does not know the concept, the spoken word, its sound, and the letters, such a word is poorly suited as starting material. The next task must rely on the already confirmed knowledge of the specific child.

The next stage of the project is to turn the theory into minimal interactive mechanics and test the main criterion: is the child able to transfer mastered correspondences to previously unseen words, rather than just memorizing shown examples.

An interactive project for teaching reading as the gradual decoding of a written code through meanings, images, and spoken words already familiar to the child.

uchitsya-legko.rf

It is necessary to describe and implement a minimal scenario that tests the core idea of the project without building a full-scale course.

Theoretical basis: [the main project concept](/concepts/uchitsya-legko-rf-obuchenie-chteniyu-kak-deshifrovke-pismennogo-koda) and [learning to read from known supports to unknown code](/concepts/obuchenie-chteniyu-ot-izvestnyh-opor-k-neizvestnomu-kodu).

The minimal cycle must include:

1. showing several images familiar to the child;
2. the child selecting a known object;
3. playing the spoken word and confirming recognition;
4. showing the written word;
5. repeating this cycle for several words with overlapping letter elements;
6. an exercise where some supports are removed and the child must restore the word or select the matching image;
7. a final exercise with a previously unseen word that can be decoded using the already mastered correspondences.

Do not include sentences, long texts, morphology, or complex gamification in the MVP. The main objective is to test the decoding mechanism itself.

Establish one short interactive cycle from a familiar image and sound to the recognition of a new spelling.

Design a minimal MVP learning cycle

What is needed is not a large vocabulary, but a specially selected minimal set of examples to test the hypothesis.

Foundation: [oral vocabulary as a recognition base](/concepts/ustnyy-slovar-baza-raspoznavaniya-pri-obuchenii-chteniyu) and [a network of representations of the same content](/concepts/pismennoe-slovo-svyazyvaet-neskolko-predstavleniy).

For each word, you need:

- a meaning that a child can understand;
- an unambiguously recognizable image;
- natural pronunciation;
- spelling;
- marking of the letter/sound correspondences it allows to demonstrate;
- an indication of which new words can then be attempted to be decoded based on already studied examples.

The set should be small—sufficient for a single MVP scenario. Words should be familiar to children and overlap in letters so that new decoding can be performed from several known pairs. Do not use rare or complex words just for the sake of a convenient letter set.

Put together a compact learning set to test the transfer of letter correspondences to new words.

Select a minimal set of words, images, and sounds for the MVP

The MVP must distinguish what the child specifically knows already, rather than just storing the overall lesson progress.

Basis: [the written word connects multiple representations of the same content](/concepts/pismennoe-slovo-svyazyvaet-neskolko-predstavleniy) and [prompts must gradually fade out](/concepts/podskazki-dolzhny-postepenno-ischezat).

For the MVP, a minimum state model for each learning word/element is sufficient, for example:

- recognizes the image;
- recognizes the spoken word;
- connects image and sound;
- recognizes the written word;
- knows a specific letter-sound correspondence;
- was able to apply it in a new word.

It is necessary to define simple rules for when the next prompt is removed and what task is shown next. Do not build a complex adaptive system: a few transparent transitions required to test the core hypothesis are enough.

Determine which connections the system considers mastered and when it can hide the image, sound, or spelling.

Define minimum child knowledge model and prompt fading rules

Build a simple web version of the MVP based on the [main concept of the project](/concepts/uchitsya-legko-rf-obuchenie-chteniyu-kak-deshifrovke-pismennogo-koda).

The prototype should be able to:

- display images;
- play recorded pronunciation;
- show the spelling of a word and its individual elements;
- accept the child's choice;
- switch tasks based on a simple mastery state;
- hide individual hints;
- provide at least one control new word to test transfer;
- record answers and the time/order of attempts in sufficient volume for subsequent analysis.

No accounts, payments, complex CMS, large design system layer, or full-fledged game mechanics are needed. The value of the MVP is a working experiment, not a finished product.

Implement a working interactive prototype that goes through a single complete learning cycle without unnecessary platform infrastructure.

Build a browser-based prototype of a minimal MVP

After creating a working prototype, conduct a small initial test with real children.

The main criterion stems from the [concept of reading as recognition and meaning reconstruction](/concepts/chtenie-eto-raspoznavanie-slova-i-vosstanovlenie-smysla): the child must not simply repeat familiar answers, but use the mastered code.

Minimum items to record:

- which images and spoken words the child knew before the session;
- which letter-sound connections were introduced;
- how quickly the child began to recognize already shown spellings;
- whether they were able to decode a control word they had not seen before in the system;
- whether they were able to connect the result with the correct picture/meaning;
- where exactly errors occurred: meaning, sound, letter, word assembly, or recognition.

Do not try to statistically prove the effectiveness of the entire methodology on the first test. The goal is to understand whether the observed transfer effect exists and where the intended chain breaks down.

Check whether the mechanism helps the child recover a previously unseen word, rather than just memorizing studied examples.

Conduct an initial MVP test with children and record the transfer effect

## Objective

Add a simple child voice response scenario to picture exercises.

Example:

1. A picture of a dog is shown on the screen.
2. The child presses the microphone button.
3. Says: "Dog".
4. The browser recognizes what was said.
5. The app receives the text and compares it with the expected answer.

Similarly for short answers like "fish", "cat", "house", etc.

## Technical Foundation

Use the browser's Web Speech API:

- `SpeechRecognition` or `webkitSpeechRecognition`;
- `recognition.lang = 'ru-RU'`;
- for a single answer, `continuous = false`;
- `interimResults = false` can be used for the simplest initial version;
- get the result from `event.results` / `transcript`.

## What to Support

- recording start button;
- "listening" visual state;
- stopping after a short answer;
- receiving the final recognized text;
- text normalization before comparison: lowercase, trim, and punctuation removal if necessary;
- comparison with the expected word;
- states: correct / not recognized / microphone access error / API unavailable;
- ability to retry.

## Limitations

`SpeechRecognition` has inconsistent browser support and may use the browser's/platform's external speech-recognition service. This is acceptable for this scenario: the task is not about local phonetic recognition or LLMs, but about a child's short, practical single-word response.

At the first stage, do not attempt to recognize free speech, sentences, or evaluate phoneme pronunciation.

Recognize short spoken answers from a child using the Web Speech API in "What is shown in the picture?" tasks.

Add browser-based single-word speech recognition for child responses

## Context

Related task to browser text-to-speech `cmu326hnm0bbpqw0qh5fgsv2f`.

Experiments have shown that `SpeechSynthesisUtterance` pronounces many whole words adequately, but performs poorly and unpredictably with individual letters, short syllables, and artificially cropped parts of words.

Observed examples:

- `Собака` (Dog) — normal;
- `Со` (So) — sounds roughly like `С`;
- `Р` (R) — closer to `Э`;
- `Ры` (Ry) — normal;
- `Свинь` (Svin') — may break down into spelling out letter names;
- `Пель` (Pel') — normal;
- `Ковь` (Kov'), `Солн` (Soln) — may be spelled out letter by letter;
- `Ко` (Ko) → roughly `Ка`;
- `Ар` (Ar) → roughly `А`;
- `Ре` (Re) → roughly `Э`;
- `Де` (De) → `Дэ`.

Conclusion: browser TTS cannot be considered a reliable source of pedagogically correct pronunciation for the `letter → syllable → word` mechanic.

---

## Objective

Build a custom managed TTS pipeline to pre-generate and verify educational audio.

Main idea:

```text
card content
↓
letters / syllables / words
↓
controlled TTS
↓
manual/automated review
↓
ready audio files
↓
app only plays pre-prepared sound
```

Do not rely on the user's system voice for critical pronunciation at runtime in the educational app.

---

## What needs to be generated

Minimum:

- individual letters where pedagogically appropriate;
- educational syllables;
- individual words for picture cards;
- short character instructions/lines if necessary.

It is especially important to pre-generate all syllables and words actually used in static educational content.

A universal generator for all possible Russian language combinations is not needed. We only generate the vocabulary actually included in the app.

---

## TTS Requirements

We need an engine/service where pronunciation can be controlled better than in browser `SpeechSynthesis`.

Desired capabilities:

- stable voice across generations;
- `ru-RU` language control;
- `rate` control;
- `pitch` control if supported;
- SSML or similar pronunciation control mechanism;
- ability to set pauses;
- ability to influence the reading of individual letters/syllables;
- export results to WAV/MP3/OGG;
- reproducible results during batch generation.

If a specific TTS reads a particular syllable poorly, it should be possible to specify a special TTS string separately from the displayed text.

For example:

```ts
type PronunciationAsset = {
  text: string
  ttsText?: string
  audioSrc: string
}
```

where:

```ts
{
  text: 'КО',
  ttsText: '<special string/SSML for correct pronunciation>',
  audioSrc: '/audio/syllables/ko.mp3',
}
```

---

## Content Pipeline

Provide a registry of generated units:

```ts
type TtsSourceItem = {
  id: string
  text: string
  kind: 'letter' | 'syllable' | 'word'
  ttsText?: string
  voiceId?: string
  rate?: number
  pitch?: number
}
```

Example:

```ts
const items: TtsSourceItem[] = [
  {
    id: 'word-dog',
    text: 'СОБАКА',
    kind: 'word',
  },
  {
    id: 'syllable-so',
    text: 'СО',
    kind: 'syllable',
    ttsText: '...',
  },
  {
    id: 'letter-r',
    text: 'Р',
    kind: 'letter',
    ttsText: '...',
  },
]
```

Then a separate script/build-step:

```text
items
→ TTS API
→ audio files
→ manifest
```

---

## Ready Audio Manifest

After generation, the app should work with ready assets rather than TTS.

For example:

```ts
type AudioAsset = {
  id: string
  text: string
  kind: 'letter' | 'syllable' | 'word'
  src: string
}
```

```ts
export const audioAssets: AudioAsset[] = [
  {
    id: 'word-dog',
    text: 'СОБАКА',
    kind: 'word',
    src: '/audio/words/sobaka.mp3',
  },
  {
    id: 'syllable-so',
    text: 'СО',
    kind: 'syllable',
    src: '/audio/syllables/so.mp3',
  },
]
```

In UI:

```ts
const audio = new Audio(asset.src)
audio.play()
```

---

## Important Architectural Idea

Separate three layers:

```text
Display text
≠
TTS input
≠
Generated audio asset
```

This will allow showing `СО` to the child, but sending a different technical string/SSML to the TTS if that is the only way to get the correct pronunciation.

That is, do not assume:

```text
what is written on the screen
=
what needs to be literally passed to TTS
```

---

## Quality Assurance

Each unit needs a simple review status:

```ts
type AudioReviewStatus =
  | 'generated'
  | 'approved'
  | 'rejected'
```

Minimum workflow:

1. generate a batch;
2. listen;
3. mark bad variants;
4. adjust `ttsText` / voice / parameters;
5. re-generate only rejected ones;
6. use the asset in the app after `approved`.

Check especially carefully:

- individual consonants;
- two-letter syllables;
- syllables with `ь`/`ъ` (soft/hard signs);
- cropped word parts;
- combinations that TTS might mistake for abbreviations.

---

## Character Integration

The voice character system can use the same pipeline.

If characters need to differ in voice/tempo/pitch, for each character you can either:

- generate a separate set of assets;
- or use characters only for non-critical lines, and keep educational letters/syllables in a single reference voice.

This needs to be decided separately after estimating the volume of generated assets.

---

## First Practical Stage

Do not choose the final TTS immediately.

First, compare several candidates on a short test set of problematic strings:

```text
Р
СО
РЫ
РЕ
ДЕ
КО
АР
СВИНЬ
ПЕЛЬ
КОВЬ
СОЛН
СОБАКА
СВИНЬЯ
```

Evaluate for each candidate:

- pronunciation correctness;
- stability;
- presence of SSML/phoneme hints;
- Russian voice quality;
- batch generation capability;
- cost;
- licensing restrictions;
- convenience of saving results to audio files.

After that, select the main TTS and build the production pipeline.

## Definition of Done

There is a reproducible process that takes a static list of educational letters/syllables/words, generates verified audio files, saves them as application assets, and allows separately overriding the technical TTS string for edge cases.

Set up a custom controlled TTS process to pre-generate audio for letters, syllables, and words instead of relying on unpredictable browser SpeechSynthesis.