DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

MykytaStel /

MykytaStel/ua-tts-text

Topic repository only

Український текст до озвучки: числа, дати, наголоси під конкретний TTS-рушій

★ 1 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: main@7e540292

ua-tts-text

Готує український текст до озвучки: числа й дати словами, скорочення, наголоси у форматі конкретного рушія TTS.

ci npm skills.sh

Проблема, яку розв'язує: більшість рушіїв читають «1675» якось собі, «ст.» — як «ст», а наголоси або не розуміють зовсім, або розуміють кожен по-своєму.

Стан

Блок Стан
normalize() — числа, діапазони, роки, дати, відсотки, одиниці, валюта, скорочення, пунктуація ✅ модульні кейси + 13 точних fixtures
stress() — наголоси бінарним словником (2,84 млн словоформ) ✅
render() — профілі рушіїв ✅
homographs() / decisions — омоніми з двома варіантами і вибір людини/LLM ✅
lint() — що лишилось небезпечним у тексті ✅
Лексикон власних назв (lexicon/names.tsv) ✅ 84 назви
Спільний токенізатор, построковий аудит і мультимножинна оцінка наголосів ✅ модульні й CLI перевірки
Перевірка TSV, походження лексиконного рядка й trace джерела наголосу ✅
Слова поза словником через LLM (resolveUnknown) ✅
SKILL.md для агентів ✅ skills/ua-voiceover-prep/
Публікація 🕒 0.15.0 підготовлено; npm publish очікує ручного 2FA-підтвердження
Перегляд омонімів і невідомих слів у CLI ✅ ручний вибір для кожного входження з перевіркою fingerprint

Встановлення

Потрібен Node.js 22 або новіший.

npm i ua-tts-text
npx ua-tts-text-fetch-dict    # 75 МБ словника, один раз → ~/.local/share/ua-tts-text/

Далі CLI сам знаходить словник: --dict → UA_TTS_DICT → ~/.local/share/ua-tts-text/dict.bin → data/dict.bin усередині пакета. Перекрити теку можна UA_TTS_HOME.

Для розробки — з репозиторію:

git clone https://github.com/MykytaStel/ua-tts-text.git
cd ua-tts-text && pnpm install && pnpm build && node scripts/fetch-dict.mjs

Скіл для агентів ставиться прямо з репозиторію:

npx skills add MykytaStel/ua-tts-text

Скіл уже в каталозі: skills.sh/mykytastel/ua-tts-text.

Використання

import { StressDictionary, prepare } from 'ua-tts-text';

const dictionary = StressDictionary.load('./data/dict.bin');

const result = prepare('У 1675 році на 5 км шляху — 22% вологи.', {
  dictionary,
  engine: 'tts-uk',
});
// result.text
// «у т+исяча шістс+от сімдес+ят п'+ятому р+оці на п'ять кілом+етрів шляху, дв+адцять два відс+отки вол+оги.»

Омоніми не вгадуються мовчки — вони повертаються списком із двома прочитаннями:

result.homographs;
// [{ word: 'Замок', key: 'замок', variants: ['За́мок', 'Замо́к'] }, ...]

const fixed = prepare(text, {
  dictionary,
  engine: 'tts-uk',
  stress: { decisions: { замок: 0 } }, // 0 — перший варіант, 1 — другий
});

Розв'язання омонімів через LLM

Короткий текст іде одним запитом; довгий ділиться на обмежені порції. Кожне входження має власний ID, а невідповідь лишається в черзі перевірки:

UA_TTS_LLM_KEY=... UA_TTS_LLM_BASE_URL=https://api.deepseek.com UA_TTS_LLM_MODEL=deepseek-chat \
  node scripts/cli.mjs --engine tts-uk --resolve < script.txt
import { createOpenAiAsker, prepareMany } from 'ua-tts-text';

const ask = createOpenAiAsker({ apiKey, model: 'deepseek-chat' });
const { results, decisions, promptLength } = await prepareMany(paragraphs, {
  dictionary, engine: 'tts-uk', ask, maxPromptChars: 12_000,
});

maxPromptChars обмежує кожен запит (типово 12 000 символів). За замовчуванням помилка провайдера зупиняє операцію. resolutionFailurePolicy: 'leave-unresolved' повертає часткові рішення, лишає проблемні порції у missing і додає warnings. Резолвер вимкнений, поки не задано ask (у CLI — --resolve).

Розв'язання омонімів агентом

import { applyDecisions, parseDecisions, prepare, reviewPrompt } from 'ua-tts-text';

const first = prepare(text, { dictionary, engine: 'tts-uk' });
const prompt = reviewPrompt(first.homographs); // готовий запит для LLM
// …модель відповідає {"замок": 0, "горі": 1}
const { decisions, missing } = applyDecisions(first.homographs, parseDecisions(answer));
const final = prepare(text, { dictionary, engine: 'tts-uk', stress: { decisions } });

Слова поза словником

Три рівні, від найдешевшого:

  1. Дефісні слова — кожна частина наголошується окремо: пів-України → пів-Укра+їни.
  2. Морфологічний фолбек — форма успадковує наголос від спільного стема (ковбасити → ковб+асити). На held-out вибірці словника: 98% точності, 14,5% покриття.
  3. Суфіксна модель — останні 5 літер і найчастіша відстань до кінця, але лише з упевненістю ≥70% (діджиталізація → діджиталіз+ація).
  4. LLM — prepareMany розв’язує омоніми по входженнях; вгадування невідомих слів потребує resolveUnknown: true.

Разом це закриває близько половини невідомих слів автоматично з точністю ~87%, решту — LLM або людина.

План мовлення

planSpeech() каже, як читати: межі речень і підрядних частин, паузи під них, тип речення й оцінку тривалості.

const plan = planSpeech('Раз, два. Хто це?');
// segments: [ {text:'Раз,', pauseAfterMs:220}, {text:'два.', pauseAfterMs:480}, {text:'Хто це?', pauseAfterMs:0} ]
renderPlan(plan, 'ssml'); // <speak>Раз,<break time="220ms"/> два.<break time="480ms"/> Хто це?</speak>

Темп (125 слів/хв) виміряно на реальному аудіо tts-uk, а не взято з голови; перевірити свій рушій можна scripts/calibrate-pace.mjs --wav out.wav --text "…". Емфаза ставиться на запереченнях і контрасті («не», «але», «однак») та на окликах.

Свідоме обмеження: це детермінована розмітка, а не модель інтонації. Природну інтонацію дає лише тренована акустика; план керує тим, що реально передається рушіям — паузами й межами фраз.

Контекстні правила

Словник знає, що слово має два наголоси, але не знає, який стоїть у реченні. Сусіднє слово часто вирішує це детерміновано — і тоді LLM не потрібен:

роки     ро́ки   prev:@few        # три ро́ки
тому     тому́   next:що          # тому́ що
горі     горі́   prev:на          # на горі́
дорога   доро́га next:веде        # дорога веде

Правила лежать у lexicon/context.tsv (умови prev:, next:, prev2:, next2:, prev~, next~, first, last, *, набори @gen) і не потребують коду, щоб доповнити. prev2/next2 потрібні, коли між числівником і словом стоїть прикметник: «два великі міста́». Що правило не покрило — лишається омонімом для людини або LLM.

Профілі рушіїв

Рушій Формат Перевірено
tts-uk, holos-voice + перед голосною ✅ модель навчена на такому записі
silero, rhvoice + перед голосною за документацією
styletts2 + після складу за документацією
piper-medium акут U+0301 ✅ phoneme_type: text, акут — окремий токен
piper-high — ❌ espeak-ng ставить наголос сам; U+0301 відкидається, + читається як «плюс»
elevenlabs-v4 IPA ⏳ профіль у роботі (для неанглійської IPA лише на v4/v4_turbo)
edge-tts, azure — наголоси не приймають; для uk-UA SSML IPA не заявлено

Baseline на golden corpus

31 сценарій, 319 слів, 174 багатоскладових. Покриття — частка слів, що потребують наголосу і справді його отримали; решта — омоніми й невідомі слова.

варіант наголошено омоніми невідомі покриття
без обробки 0 — — 0%
словник 211 23 1 89,8%
словник + рішення для омонімів 297 0 2 99,3%

Тобто сам словник дає ~90%, а останні 10% — це робота, яку досі ніхто не автоматизував: вибір прочитання за контекстом. Це і є причина існування скіла.

Лексикон власних назв

Словник lang-uk містить і помилкові варіанти («Киї́в» поруч із «Ки́їв»), і не знає брендів. Лексикон — шар поверх нього, який має пріоритет:

Київ	Ки́їв	власна назва	manual: словник має помилковий варіант «Киї́в»

На 84 назвах (міста, історичні постаті, бренди):

джерело омоніми невідомі
лише словник 7 4
+ лексикон 0 0

Скіл для агентів

skills/ua-voiceover-prep/SKILL.md — тонка обгортка: коли застосовувати, який профіль рушія вибрати, як розв'язувати омоніми через decisions і чого не робити (наприклад, не намагатися полагодити piper-high позначками).

Перевірено встановленням у чистому середовищі:

npx skills add MykytaStel/ua-tts-text
# ✓ ./.agents/skills/ua-voiceover-prep
#   universal: Amp, Antigravity, Cline, Codex +19 more
#   symlinked: Claude Code, Eve

Тобто один файл справді працює в трьох агентах — це не припущення, а результат установки.

Інтеграція у Content Factory

Content Factory споживає пакет як npm-залежність. Після публікації нової версії оновлюються версія залежності й lockfile у Studio; runtime-підготовка користується спільним API пакета та відбитком ресурсів для ідентичності кешу синтезу.

Словник і лексикон для рантайму лежать у ~/.local/share/ua-tts-text/ (шляхи перекриваються UA_TTS_DICT, UA_TTS_LEXICON і UA_TTS_HOME). Пакет можна використовувати окремо від Studio через CLI або програмний API.

CLI

npx ua-tts-text --engine tts-uk < script.txt
node scripts/cli.mjs --engine tts-uk < script.txt
node scripts/cli.mjs --engine tts-uk --decisions corpus/decisions.json < script.txt
node scripts/cli.mjs --engine piper-high --json < script.txt

Ручний перегляд омонімів і невідомих слів (CLI у 0.15.0)

Експортуй review-файл без LLM. Для омонімів вибери 0 або 1 у полі choice. Для невідомого слова вибери одну з позицій у масиві vowels і запиши її в stressPosition. Індекси — позиції Unicode-символів у слові; для однакових слів у різних місцях можна вибрати різні голосні:

ua-tts-text --engine tts-uk --review-out review.json < script.txt
# у review.json заповнити choice / stressPosition для потрібних входжень
ua-tts-text --engine tts-uk --apply-review review.json < script.txt > prepared.txt

Запис невідомого слова містить контекст і перелік голосних, наприклад:

{
  "kind": "unknown",
  "id": "0:14",
  "word": "Краудфандинг",
  "vowels": [
    { "position": 2, "letter": "а" }, { "position": 3, "letter": "у" },
    { "position": 6, "letter": "а" }, { "position": 9, "letter": "и" }
  ],
  "stressPosition": null
}

Файл прив'язаний до нормалізованого тексту, рушія та fingerprint ресурсів. Якщо змінилися текст, словник чи лексикон, CLI відхилить файл і попросить створити новий. Невибрані омоніми й невідомі слова лишаються у звіті.

У програмному API ті самі ручні наголоси задаються через prepareMany():

const { results } = await prepareMany(['Краудфандинг. Краудфандинг.'], {
  dictionary,
  engine: 'tts-uk',
  occurrenceOverrides: { '0:0': 2, '0:14': 9 },
});

Словник

npx ua-tts-text-fetch-dict          # у ~/.local/share/ua-tts-text/dict.bin
node scripts/fetch-dict.mjs --local # у ./data/dict.bin (репозиторій)

Словник наголосів — lang-uk/ukrainian-word-stress-dictionary (пакет MIT; у самому репозиторії словника файл LICENSE відсутній).

Свідомі обмеження

  • Числа узгоджуються з поширеними контекстами (до/від, одиниці виміру й діапазони); це не повний морфологічний коректор довільних речень.
  • Складені назви з дефісом («Кам'янка-Бузька») отримують лише один наголос — це робота лексикону.
  • Абревіатури — невелика таблиця; решта лишається як є.
  • Латинські назви не транслітеруються, а лише потрапляють у звіт.

Аудит своїх текстів

node scripts/audit.mjs --dir ~/шлях/до/сценаріїв

Показує частку наголошених слів по файлах і найчастіші слова, які лишились без наголосу — це готовий список для lexicon/ і context.tsv.

Оцінка якості

npm run eval

Золотий набір — evaluation/gold.tsv: 28 регресійних речень, не незалежний holdout. Останній локальний прогін: точність 100,0%, повнота 97,0%, F1 98,5%; 28/28 рядків зі збереженою послідовністю слів. Тепер scorer вимагає всі очікувані наголоси й карає зайві, зокрема неповний багатонаголосний варіант. Чотири пропуски: невирішений омонім «замок», «доєднатися» поза словником і два речення, де в gold дозволено обидва наголоси, а пакет видав лише один. Це не оцінка згенерованого аудіо й не незалежний holdout. Перевірки нормалізації: 13 точних fixtures.

Спірні місця для перевірки людиною — evaluation/review.md.

Ліцензія

MIT.

0.13 integration contract

import { loadResources, prepareMany } from 'ua-tts-text';
const resources = loadResources({ required: true });
const batch = await prepareMany(paragraphs, {
  resources,
  engine: 'tts-uk',
});
// Include resources.manifest.fingerprint in generated-audio cache identity.
// Reuse batch.decisionFingerprint to reject stale per-occurrence choices.

Bundled common/names are loaded first, then local common/names override them. Project context rules are evaluated before bundled rules. Explicit lexicon rows are protected from broad context rules. UA_TTS_HOME, UA_TTS_DICT, and UA_TTS_LEXICON are shared by CLI and the API loader. No local files are modified by loading resources. Explicit missing lexicons fail.

Migration: prepareMany().decisions is keyed by paragraph:offset (UTF-16 offsets in normalized input). prepareMany() also returns a decisionFingerprint; pass it back as expectedDecisionFingerprint with saved manual choices to reject stale offsets after normalized text or resource changes. For multiple paragraphs, use occurrenceDecisions keys such as 0:12; legacy stress.occurrenceDecisions is accepted only for one paragraph. Do not pass prepareMany().decisions to stress.decisions, which remains a global word override. homographs() returns unresolved occurrences and offsets. Unknown-word LLM guessing is disabled unless resolveUnknown: true. Such guesses remain unverified and should not be persisted as normative dictionary entries.

The dictionary fetcher uses scripts/dictionary-source.json; it checks the source hash before building. An existing different binary is retained as dict.<sha256>.bin. For rollback, select that file with UA_TTS_DICT; keep the matching npm version and local TSV snapshot. The resource manifest identifies what was actually loaded. The package prepares speech text; it does not correct arbitrary grammar. Accuracy on the regression corpus is not an independent held-out or listening assessment.

Проєктні назви й власні словоформи

Пакет спершу бере вбудовані загальні форми, потім вбудовані назви, і нарешті локальний лексикон із UA_TTS_LEXICON або --lexicon. Для конкретного проєкту створи окремий names.tsv; повний шаблон із колонками для категорії, джерела, проєкту, основної назви й статусу є в lexicon/project-template.tsv. Старі чотириколонкові рядки сумісні. Кожну потрібну відмінкову форму додавай явно: лексикон не вигадує граматичне відмінювання власних назв. Рядки draft і rejected видно через lexicon.inactiveEntries, але вони не впливають на вимову. TSV-помилки (неправильний наголос, дубль у файлі, невідповідне слово чи невідомий статус) зупиняють завантаження з конкретним повідомленням.

Налаштуй шлях один раз для середовища: UA_TTS_LEXICON=/path/to/project/names.tsv. API prepare() приймає lexicon без базового словника для вузьких проєктних override-ів, але попереджає, що загальне покриття наголосів буде неповним. Ресурсний fingerprint охоплює версію пакета, runtime-модулі бібліотеки, словник, лексикони й контекстні правила — зміни коду також скидають кеш генерації. Його можна додати до журналу синтезу.

Оцінювання

pnpm test запускає модульні тести зі словником і без нього, перевірки TSV, оцінювача, рецензування входжень, побудови словника й точні fixtures нормалізації. node scripts/package-smoke.mjs пакує npm-архів, встановлює його в тимчасовий каталог і перевіряє API та CLI. pnpm eval оцінює регресійний gold-набір; pnpm eval:normalization повторно перевіряє очікувані виходи нормалізатора. Метрика наголосів вимагає точного набору позначок у кожному входженні; окремо фіксується збереження послідовності слів. Див. evaluation/README.md: ці fixtures не є незалежним holdout і не замінюють сліпе аудіювання.

—/ 5

No ratings yet

Manifest verification required

Commit 7e540292834e

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout