Настройка

echo-words настраивается в двух местах: TOML-таблица исходных языков и переменные окружения для всего остального.

Исходные языки

languages.toml — источник истины для языков, слова которых вы разбираете. Файл лежит в ECHOWORDS_DATA_DIR и переезжает вместе с ним; путь можно переопределить через ECHOWORDS_LANGUAGES_CONFIG. Добавление языка — это изменение настроек, а не кода.

[languages.en]
name       = "English"
deck       = "EchoWords: English"
recordings = "En-us"           # префикс записей на Wikimedia Commons, вместе с акцентом;
                               # опустите, если записей этого языка там нет
tts        = "piper"           # piper | edge
tts_voice  = "en_US-lessac-medium"
script     = "latin"           # latin | cyrillic | latin+cyrillic

[languages.sr]
name           = "Српски"
deck           = "EchoWords: Serbian"
tts            = "edge"
edge_tts_voice = "sr-RS-SophieNeural"
script         = "latin+cyrillic"
prompt_hints   = "for nouns give gender and plural, for verbs give aspect"

Каждая запись задаёт отображаемое имя, собственную колоду Anki (deck), допустимую письменность ввода (script), префикс, под которым живые записи этого языка лежат на Wikimedia Commons, если они там есть, а также движок и голос произношения. В репозитории лежит languages.example.toml с готовыми записями для английского, немецкого и сербского.

Note

Сербский намеренно озвучивается кириллицей: голоса sr-RS неправильно произносят латинское написание.

Переменные окружения

Все переменные начинаются с ECHOWORDS_. Закоммиченный .deploy.example/.env документирует каждую; ниже те, что меняют чаще всего.

Переменная	Значение	По умолчанию
`ECHOWORDS_DATA_DIR`	коллекция Anki, модели голосов, состояние брокера, кэш аудио — своей базы данных нет	`~/.echo-words`
`ECHOWORDS_TARGET_LANG`	язык, на котором пишутся все объяснения и переводы	`ru`
`ECHOWORDS_LANGUAGES_CONFIG`	путь к таблице языков	`<data dir>/languages.toml`
`ECHOWORDS_LLMBROKER_HOME`	где llmbroker хранит свой список моделей и журнал вызовов	`<data dir>/llmbroker`
`ECHOWORDS_API_MODEL`	алиас платной модели, на которую переключается каскад; пустое значение полностью отключает платные вызовы	`gpt-fast`
`ECHOWORDS_API_DAILY_CAP`	платных вызовов в сутки, `0` — без ограничения	`100`
`ECHOWORDS_DETAIL_MODEL`	алиас платной модели для «Подробнее»; пустое значение отключает эту кнопку	`gpt`
`ECHOWORDS_DETAIL_PARAMS`	параметры запроса для «Подробнее» — один JSON-объект в словаре самого провайдера	`{"reasoning_effort": "none", "service_tier": "priority"}`
`ECHOWORDS_ANKI_SYNC`	синхронизировать коллекцию с AnkiWeb после добавления	`true`
`ECHOWORDS_ANKIWEB_USER` / `_PASSWORD`	учётные данные AnkiWeb	обязательны при включённой синхронизации
`ECHOWORDS_SYNC_ENDPOINT`	свой сервер синхронизации Anki вместо AnkiWeb	пусто
`ECHOWORDS_ACCENT`	`us` или `uk` для английского аудио	`us`
`ECHOWORDS_AUDIO_TIMEOUT`	общий лимит ожидания произношения после генерации, прежде чем отправить без него	`10`
`ECHOWORDS_HOST` / `ECHOWORDS_PORT`	адрес привязки; оставьте на loopback, входной дверью служит Tailscale	`127.0.0.1:8080`

Все варианты произношения делят это одно окно ожидания после генерации. Значение меньше десяти секунд сокращает его, а значение больше десяти не расширяет жёсткий лимит. Ожидание заканчивается, как только аудио готово, поэтому целиком оно тратится только тогда, когда озвучки не будет вовсе.

Язык интерфейса переменной окружения не является. Это выбор для конкретного устройства, который делается в шапке (EN/RU) и запоминается в браузере. Он не меняет ECHOWORDS_TARGET_LANG — язык, на котором написаны ваши карточки.

Ключи LLM и подробная статья

Какие ключи получить и куда их записать — на странице Ключи.

Модель для «Подробнее» и её параметры — один выбор. По умолчанию OpenAI просят не рассуждать и обработать запрос в приоритетной очереди — поэтому текст начинает появляться меньше чем через секунду. Если указать в ECHOWORDS_DETAIL_MODEL модель другого провайдера, в ECHOWORDS_DETAIL_PARAMS нужно записать параметры уже этого провайдера или {} для его значений по умолчанию.

AnkiWeb

Задайте ECHOWORDS_ANKIWEB_USER и ECHOWORDS_ANKIWEB_PASSWORD и оставьте ECHOWORDS_ANKI_SYNC=true. При первом запуске headless-коллекция полностью скачивает существующую коллекцию аккаунта, прежде чем добавить хоть одну локальную карточку. Пароль используется один раз — для получения ключа синхронизации, который затем хранится в ECHOWORDS_DATA_DIR и переиспользуется.

Оставьте исходящий HTTPS открытым для *.ankiweb.net: AnkiWeb перенаправляет синхронизацию на пронумерованные шарды, поэтому разрешение только sync.ankiweb.net будет периодически ломаться.

Свой сервер синхронизации Anki выбирается через ECHOWORDS_SYNC_ENDPOINT.