Class YandexSpeechKit

Класс отвечающий за преобразование текста в аудио файл. Преобразование осуществляется через сервис Yandex SpeechKit.

See

https://cloud.yandex.ru/docs/speechkit/tts/request

Example

import { YandexSpeechKit } from 'umbot/plugins';

// Создание экземпляра (appContext обязателен). Токен — API-ключ сервисного
// аккаунта (уйдёт как `Api-Key ...`) или IAM-токен `t1....` (уйдёт как `Bearer ...`).
// OAuth-токен Яндекс.Диалогов SpeechKit не принимает.
const speechKit = new YandexSpeechKit('your-api-key', appContext);

// Настройка параметров синтеза
speechKit.lang = YandexSpeechKit.L_RU;     // Русский язык
speechKit.voice = YandexSpeechKit.V_JANE;  // Голос Jane
speechKit.emotion = YandexSpeechKit.E_GOOD; // Доброжелательная интонация
speechKit.speed = 1.2;                     // Скорость речи
speechKit.format = YandexSpeechKit.F_OGGOPUS; // Формат OGG/OPUS

try {
  // Пример с омографами и паузами
  const text = 'Я гот+ов - начать работу';
  const audio = await speechKit.getTts(text);

  // Сохранение или воспроизведение аудио
  // audio содержит бинарные данные в выбранном формате
} catch (error) {
  console.error('Ошибка синтеза речи:', error);
}

Hierarchy (View Summary)

YandexRequest
- YandexSpeechKit

Index

Constructors

constructor

new YandexSpeechKit(
oauth?: string | null,
appContext: AppContext,
): YandexSpeechKit
Создает экземпляр YandexSpeechKit
Parameters
- oauth: string | null = null
  API-ключ сервисного аккаунта или IAM-токен (t1....) Yandex Cloud
- appContext: AppContext
  Контекст приложения
Returns YandexSpeechKit
Overrides YandexRequest.constructor
- Defined in plugins/platforms/API/YandexSpeechKit.ts:231

Properties

`Protected`_appContext

_appContext: AppContext

Контекст приложения.

`Protected`_request

_request: Request

Экземпляр класса для отправки HTTP-запросов

emotion

emotion: string

Эмоциональная окраска голоса Отправляется для всех русских голосов; платформа документирует поддержку эмоций только для jane/omazh — для остальных голосов поле может игнорироваться API good - доброжелательный evil - злой neutral (по умолчанию) - нейтральный

folderId

folderId: string | number | null

Идентификатор каталога для авторизации. Требуется только для пользовательского аккаунта Максимум 50 символов

format

format: string

Формат синтезируемого аудио lpcm - без WAV-заголовка oggopus (по умолчанию) - OGG контейнер с OPUS кодеком

lang

lang: string

Язык синтеза речи ru-RU (по умолчанию) - русский en-US - английский tr-TR - турецкий

sampleRateHertz

sampleRateHertz: number | undefined

Частота дискретизации для формата lpcm Поддерживаемые значения:

48000 - 48 кГц, высокое качество (значение по умолчанию на стороне API: класс не инициализирует поле, 48000 применяет сам API)
16000 - 16 кГц, среднее качество
8000 - 8 кГц, низкое качество, подходит для телефонии

Remarks

Параметр используется только при format = YandexSpeechKit.F_LPCM Для format = YandexSpeechKit.F_OGGOPUS игнорируется

speed

speed: number

Скорость синтеза речи От 0.1 до 3.0 3.0 - самый быстрый 1.0 (по умолчанию) - средняя скорость 0.1 - самый медленный При выходе за диапазон 0.1–3.0 значение молча сбрасывается к 1.0 Не поддерживается для премиум-голосов (alena, filipp, kirkorov, lera, madusa)

text

text: string | undefined

Текст для озвучивания в кодировке UTF-8 Для передачи слов-омографов используйте + перед ударной гласной Например: гот+ов или def+ect Для паузы между словами используйте - Максимальная длина: 5000 символов

voice

voice: string

Голос для синтеза речи По умолчанию: oksana

See

V_OKSANA, V_JANE, V_OMAZH и другие константы

`Static` `Readonly`E_EVIL

E_EVIL: "evil" = 'evil'

Отрицательная интонация

`Static` `Readonly`E_GOOD

E_GOOD: "good" = 'good'

Положительная интонация

`Static` `Readonly`E_NEUTRAL

E_NEUTRAL: "neutral" = 'neutral'

Нейтральная интонация

`Static` `Readonly`F_LPCM

F_LPCM: "lpcm" = 'lpcm'

Формат файла lpcm

See

format

`Static` `Readonly`F_OGGOPUS

F_OGGOPUS: "oggopus" = 'oggopus'

Формат файла oggopus

See

format

`Static` `Readonly`L_EN

L_EN: "en-US" = 'en-US'

Английский язык

`Static` `Readonly`L_RU

L_RU: "ru-RU" = 'ru-RU'

Русский язык

`Static` `Readonly`L_TR

L_TR: "tr-TR" = 'tr-TR'

Турецкий язык

`Static` `Readonly`TTS_API_URL

TTS_API_URL: "https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize" = 'https://tts.api.cloud.yandex.net/speech/v1/tts:synthesize'

Адрес, на который будет отправляться запрос

`Static` `Readonly`V_ALENA

V_ALENA: "alena" = 'alena'

Голос для синтеза речи Алена (ru)

`Static` `Readonly`V_ALYSS

V_ALYSS: "alyss" = 'alyss'

Голос для синтеза речи Элис (en)

`Static` `Readonly`V_ERKANYAVAS

V_ERKANYAVAS: "erkanyavas" = 'erkanyavas'

Голос для синтеза речи Эркан Яваш (tr)

`Static` `Readonly`V_ERMIL

V_ERMIL: "ermil" = 'ermil'

Голос для синтеза речи Ермил (ru)

`Static` `Readonly`V_FILIPP

V_FILIPP: "filipp" = 'filipp'

Голос для синтеза речи Филипп (ru)

`Static` `Readonly`V_JANE

V_JANE: "jane" = 'jane'

Голос для синтеза речи Джейн (ru)

`Static` `Readonly`V_KIRKOROV

V_KIRKOROV: "kirkorov" = 'kirkorov'

Голос для синтеза речи Киркоров (ru)

`Static` `Readonly`V_LERA

V_LERA: "lera" = 'lera'

Голос для синтеза речи Лера (ru)

`Static` `Readonly`V_MADUSA

V_MADUSA: "madusa" = 'madusa'

Голос для синтеза речи Мадуса (ru)

`Static` `Readonly`V_NICK

V_NICK: "nick" = 'nick'

Голос для синтеза речи Ник (en)

`Static` `Readonly`V_OKSANA

V_OKSANA: "oksana" = 'oksana'

Голос для синтеза речи Оксана (ru)

`Static` `Readonly`V_OMAZH

V_OMAZH: "omazh" = 'omazh'

Голос для синтеза речи Омаж (ru)

`Static` `Readonly`V_SILAERKAN

V_SILAERKAN: "silaerkan" = 'silaerkan'

Голос для синтеза речи Сила Эркан (tr)

`Static` `Readonly`V_ZAHAR

V_ZAHAR: "zahar" = 'zahar'

Голос для синтеза речи Захар (ru)

Accessors

oauth

get oauth(): string | null | undefined
Возвращает установленный OAuth-токен (или null, если авторизация отключена).

Returns string | null | undefined
Inherited from YandexRequest.oauth
- Defined in plugins/platforms/API/YandexRequest.ts:96

Methods

`Protected`_getAuthorizationHeader

_getAuthorizationHeader(token: string): string
Формирует заголовок Authorization по контракту Yandex Cloud.

SpeechKit не принимает схему OAuth (её понимает только API Диалогов): допустимы Api-Key <ключ> для API-ключа сервисного аккаунта и Bearer <IAM-токен>. IAM-токен узнаётся по префиксу t1., остальное считается API-ключом. Уже заданную схему (Api-Key .../Bearer ...) передаём как есть — так можно явно указать нужную.
Parameters
- token: string
  Токен из speech_kit_token / SPEECH_KIT_TOKEN
Returns string
Значение заголовка Authorization
Overrides YandexRequest._getAuthorizationHeader
- Defined in plugins/platforms/API/YandexSpeechKit.ts:253

`Protected`_log

_log(error?: string | Error): void
Пишет информацию об ошибках через AppContext.logError (структурированный логгер)

Логирует детальную информацию об ошибке, включая URL запроса и текст ошибки.
Parameters
- Optionalerror: string | Error = ''
  Текст ошибки или объект ошибки
Returns void
Inherited from YandexRequest._log
- Defined in plugins/platforms/API/YandexRequest.ts:215

call

call<T extends IYandexApi>(url?: string | null): Promise<T | null>

Выполняет HTTP-запрос к API Яндекса

Отправляет запрос к указанному эндпоинту API и обрабатывает полученный ответ.

Type Parameters

T extends IYandexApi
Тип ожидаемого ответа, наследующий интерфейс IYandexApi

Parameters

Optionalurl: string | null = null
URL-адрес эндпоинта API

Returns Promise<T | null>

Результат запроса или null в случае ошибки сети/Request

Example

interface MyApiResponse extends IYandexApi {
  data: {
    id: string;
    name: string;
  };
}

const api = new YandexRequest('token', appContext);

// Выполнение запроса (метод не выбрасывает исключений).
// При ошибке API ответ содержит поле error — проверяйте его явно;
// null возвращается только при ошибке сети/Request.
const response = await api.call<MyApiResponse>('...');

if (response) {
  if ('error' in response) {
    // Обработка ошибки API
    console.error('Ошибка API:', response.error);
  } else {
    // Обработка успешного ответа
    console.log('ID:', response.data.id);
    console.log('Name:', response.data.name);
  }
} else {
  // Обработка ошибки сети/Request
  console.error('Ошибка запроса к API Яндекса');
}

getTts

getTts(text?: string | null): Promise<ITTSResult | null>
Получение голосового текста
Parameters
- text: string | null = null
  Текст для преобразования в речь
Returns Promise<ITTSResult | null>
Возвращает путь к сохраненному файлу и его бинарное содержимое
Remarks
Поддерживаемые форматы:
- F_LPCM: RAW PCM без WAV-заголовка
- F_OGGOPUS: OGG контейнер с OPUS кодеком (рекомендуется)
Особенности текста:
- Для омографов используйте + перед ударной гласной: гот+ов, з+амок
- Для паузы между словами используйте -: слово - слово
- Максимальная длина текста: 5000 символов
Ограничения:
- Эмоции (emotion) отправляются для всех русских голосов; платформа документирует поддержку только для jane/omazh — для остальных голосов поле может игнорироваться API
- Скорость (speed) не поддерживается для премиум-голосов (alena, filipp, kirkorov, lera, madusa)
Важно! после выполнения запроса, не забудьте удалить файл с результатом. Файл всегда получает расширение .ogg, даже при format = F_LPCM (содержимое файла — raw PCM).
Example
```
// Пример с LPCM форматом
speechKit.format = YandexSpeechKit.F_LPCM;
speechKit.sampleRateHertz = 16000;
const pcmAudio = await speechKit.getTts('Текст для синтеза');

// Пример с OGG/OPUS
speechKit.format = YandexSpeechKit.F_OGGOPUS;
const oggAudio = await speechKit.getTts('Текст для синтеза');
```
See
https://cloud.yandex.ru/docs/speechkit/tts/request
- Defined in plugins/platforms/API/YandexSpeechKit.ts:348

setOAuth

setOAuth(oauth: string | null): void
Устанавливает OAuth-токен для авторизации

Обновляет токен авторизации и заголовки запросов. При установке токена автоматически добавляется заголовок 'Authorization: OAuth {token}' ко всем последующим запросам.
Parameters
- oauth: string | null
  OAuth-токен для авторизации
Returns void
Remarks
- Если передать null, авторизация будет отключена
- Заголовок авторизации добавляется автоматически
- Токен сохраняется для всех последующих запросов
Example
```
const api = new YandexRequest(null, appContext);

// Установка нового токена
api.setOAuth('new-token');
// Теперь все запросы будут с заголовком:
// Authorization: OAuth new-token

// Сброс токена
api.setOAuth(null);
// Запросы будут без авторизации
```
Inherited from YandexRequest.setOAuth
- Defined in plugins/platforms/API/YandexRequest.ts:128

Class YandexSpeechKit

See

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns YandexSpeechKit

Properties

Protected_appContext

Protected_request

emotion

folderId

format

lang

sampleRateHertz

Remarks

speed

text

voice

See

Static ReadonlyE_EVIL

Static ReadonlyE_GOOD

Static ReadonlyE_NEUTRAL

Static ReadonlyF_LPCM

See

Static ReadonlyF_OGGOPUS

See

Static ReadonlyL_EN

Static ReadonlyL_RU

Static ReadonlyL_TR

Static ReadonlyTTS_API_URL

Static ReadonlyV_ALENA

Static ReadonlyV_ALYSS

Static ReadonlyV_ERKANYAVAS

Static ReadonlyV_ERMIL

Static ReadonlyV_FILIPP

Static ReadonlyV_JANE

Static ReadonlyV_KIRKOROV

Static ReadonlyV_LERA

Static ReadonlyV_MADUSA

Static ReadonlyV_NICK

Static ReadonlyV_OKSANA

Static ReadonlyV_OMAZH

Static ReadonlyV_SILAERKAN

Static ReadonlyV_ZAHAR

Accessors

oauth

Returns string | null | undefined

Methods

Protected_getAuthorizationHeader

Parameters

Returns string

Protected_log

Parameters

Returns void

call

Type Parameters

Parameters

Returns Promise<T | null>

Example

getTts

Parameters

Returns Promise<ITTSResult | null>

Remarks

Example

See

setOAuth

Parameters

Returns void

Remarks

Example

Settings

On This Page

`Protected`_appContext

`Protected`_request

`Static` `Readonly`E_EVIL

`Static` `Readonly`E_GOOD

`Static` `Readonly`E_NEUTRAL

`Static` `Readonly`F_LPCM

`Static` `Readonly`F_OGGOPUS

`Static` `Readonly`L_EN

`Static` `Readonly`L_RU

`Static` `Readonly`L_TR

`Static` `Readonly`TTS_API_URL

`Static` `Readonly`V_ALENA

`Static` `Readonly`V_ALYSS

`Static` `Readonly`V_ERKANYAVAS

`Static` `Readonly`V_ERMIL

`Static` `Readonly`V_FILIPP

`Static` `Readonly`V_JANE

`Static` `Readonly`V_KIRKOROV

`Static` `Readonly`V_LERA

`Static` `Readonly`V_MADUSA

`Static` `Readonly`V_NICK

`Static` `Readonly`V_OKSANA

`Static` `Readonly`V_OMAZH

`Static` `Readonly`V_SILAERKAN

`Static` `Readonly`V_ZAHAR

`Protected`_getAuthorizationHeader

`Protected`_log