Irene-Voice-Assistant/docs/PLUGINS.md

# Список плагинов, встроенных в инсталляцию по умолчанию

## Активные плагины/скиллы (уже в папке plugins)

Для каждого плагина написано, требуется ли онлайн. 
Для отключения удалите из папки

**plugin_greetings.py** - приветствие (оффлайн). Пример команды: "ирина, привет"

**plugin_mediacmds.py** - команды управления медиа (оффлайн). Пример: "дальше, громче, тише, сильно громче, сильно тише, пауза".
Если установлено mpcIsUseHttpRemote, то сначала делается попытка вызвать команду MPC HC плейера, если не удается - используется эмуляция мультимедийных клавиш

**plugin_mpchcmult.py** - проигрывание медиа через MPC-HC из определенной папки (оффлайн). 
1. Пример "мультик <название_мультика>". 
Папка мультиков задается в конфиге (multPath). 
При вызове команды в папке ищется файл с соответствующим названием <название_мультика> и любым расширением. Если найден - запускается на проигрывание.
(Так что можно делать свою базу данных мультов, вместо ютуба с непонятными алгоритмами ранжирования). 

2. Пример "сериал <название сериала> <номер серии>".
Папка сериалов задается в конфиге (serialPath).
При вызове команды ищется
   * папка с таким названием
   * или (если неудобно переназывать папку) ищется в папке файл `_irenename.txt` в кодировке UTF-8. В нем считываются все строки, и каждая из них - это указатель имени данной папки сериала для Ирины.
   
Например: папка "Babylon 5" содержит файл "_irenename.txt" со строкой "вавилон". Сериал может быть запущен по фразе "сериал вавилон два" (вторая серия)

Последним параметром команды является номер серии. Варианты:
  * номер серии - один, два и т.д.
  * "последняя" - для последней доступной серии
  
_Доп инфа:_

1. Предполагается, что медиафайлы ["mkv","avi","mp4","mpg"], будучи отсортированы в алфавитном порядке дают серии по порядку.
2. Серии с субтитрами поддерживаются; файлы субтитров не будут учтены при поисках серии, не беспокойтесь о них.        

**plugin_timer.py** - таймер (оффлайн). Примеры: "таймер, таймер шесть минут, таймер десять секунд"

**plugin_random.py** - рандом (оффлайн). Примеры: "подбрось|брось кубик|монетку". Содержит примеры парсинга дерева команд (команды можно задавать деревом)

**plugin_datetime.py** - команды "дата, время"

**plugin_weatherowm.py** - погода (онлайн). Примеры: "погода, погода завтра, погода послезавтра, прогноз погоды". 
Требует установки в конфиге бесплатного API-ключа с https://openweathermap.org/ , а также местоположения

**plugin_yandex_rasp.py** - расписание ближайших электричек через Яндекс.Расписания. Пример: "электричка, электрички".
Требует установки в конфиге бесплатного API-ключа для личных нужд (до 500 запросов в сутки) с https://yandex.ru/dev/rasp/raspapi/ , а также станций отправления и назначения

**plugin_gamemoreless.py** - игра Больше-меньше. Команда "игра больше меньше". Является примером работы с контекстом в движке Ирины. 

---

**plugin_tts_pyttsx.py** -  (оффлайн) позволяет делать TTS (Text-To-Speech, озвучку текста) через pyttsx движок. Используется по умолчанию.

**plugin_tts_console.py** -  (оффлайн) заглушка для отладки. Вместо работы TTS просто выводит текст в консоль.

**plugin_tts_rhvoice_rest.py** - (оффлайн) TTS через RHVoice.
Использует докер-сервер https://github.com/Aculeasis/rhvoice-rest для
генерации голоса. Зайдите туда и запустите нужный вам докер.

Голос и адрес докера задается в конфиге.

_(По неизвестным причинам плохо генерирует WAV. 
Поэтому используется генерация MP3. Учтите, если будете использовать)_

Для работы укажите в core.json `"ttsEngineId": "rhvoice_rest",`

**plugin_tts_opentts.py** - (оффлайн) TTS через OpenTTS сервер.
Использует докер-сервер https://github.com/synesthesiam/opentts для
генерации голоса. Зайдите туда и запустите нужный вам докер.

OpenTTS не очень хорош в русской озвучке, но поддерживает большое число
других языков.

Для работы укажите в core.json `"ttsEngineId": "opentts",`

---

### PlayWav

**plugin_playwav_sounddevice.py** - проигрывание WAV через sounddevice. Ест окончания фраз, но работает почти везде.

**plugin_playwav_simpleaudio.py** - проигрывание WAV через simpleaudio. _Не заработало у автора, но должно работать._

`pip install simpleaudio`

https://simpleaudio.readthedocs.io/en/latest/installation.html#linux-dependencies

**plugin_playwav_aplay.py** - проигрывание WAV через aplay (рекомендуется под Linux)

**plugin_playwav_audioplayer.py** - проигрывание WAV через библиотеку audioplayer. Дефолтовый вариант, но иногда плохо ставится под Linux.

**plugin_playwav_consolewav.py** - заглушка. Ничего не проигрывает; используется в Докере и когда не нужно проигрывание на сервере.


## Неактивные скиллы (plugins_inactive)

Для работы перенесите в папку plugins

**plugin_urlopener.py** - Крайне полезный плагин, если вы планируете 
открывать ссылки в браузере по голосовым командам.

Позволяет задать в конфиге набор команд, и URL, которые будут по ним открываться.

Конфиг настраивается в ```options/plugin_urlopener.json```

Пример:
```
"cmds": {
    "главная яндекс": "https://yandex.ru/",
    "ютуб|юту": "https://www.youtube.com/results?search_query={}",
    "яндекс": "https://yandex.ru/search/?text={}"
},
```

Если в URL содержится {}, то он будет заменен на оставшуюся часть 
произнесенной фразы. Так, фраза "яндекс погода" запустит поиск в Яндексе по слову "погода".

**plugin_simpleyandexmusic.py** - открывает страницу Яндекс.Музыки и запускает её. Пример: "запусти радио, запусти музыку"

**plugin_wikipediasearch.py** - поиск в Википедии. Пример: "википедия кошка, вики собака". Читает первые два абзаца, если найдено. (Inspired by @EnjiRouz)

**plugin_youtubesearch.py** - поиск на Ютубе. Пример: "ютуб остров сокровищ". Открывает страницу в браузере с поиском. (Inspired by @EnjiRouz)

**plugin_finstockmoex.py** - курс акций на Московской бирже.
В конфиге можно задать:
* список акций для озвучки, несколько наборов при желании
* собрать портфель - тогда будет озвучиваться стоимость портфеля

Примеры команд: "ирина акции", "ирина акции сбер", ирина портфель тест"

**plugin_gamemoreless_alt.py** - альтернативная реализация игры Больше-меньше. Команда "игра меньше больше". 
Является примером работы с контекстом альтернативным способом (**рекомендуется**) в движке Ирины.

**plugin_voiceover.py** - озвучка текстов.
Озвучивает тексты через новую функцию say2, которая использует второй TTS-движок (который может отличаться от первого, качеством, например).
Также второй движок всегда проигрывает всё через колонки, т.е. не отсылает ответ через WEBAPI.

Примеры команд:
"ирина скажи раз два три"
"ирина буфер" (озвучит содержимое буфера обмена)

**plugin_tts_silero.py** - (оффлайн) TTS через Silero V2. При первом запуске требует онлайна, чтобы скачать файл с нейросетью. 
Требует pytorch 1.9+. На мой взгляд, работает немного медленно + не озвучивает числа, требуя их перевода в числительные + шипит. Тем не менее, очень крут!
Голос задается в конфиге.

**plugin_tts_silero_v3.py** - (оффлайн) TTS через Silero V3. При первом запуске требует онлайна, чтобы скачать файл с нейросетью. 
Требует pytorch 1.9+. Работает очень прилично.

Для работы укажите в core.json `"ttsEngineId": "silero_v3",`

Список голосов: https://github.com/snakers4/silero-models#text-to-speech

В конфиге можно задать:

```json
{
    "sample_rate": 24000, # частота рендера
    "speaker": "xenia", # голос
    "threads": 4, # потоков процессора для рендера
}
```

Конфиг подходит для удобной генерации на относительно быстрой машине.
При sample_rate=48000 генерация качественней, но задержка при ответе больше, т.к. больше 
времени уходит на генерацию.

По мотивам [статьи на Хабре](https://habr.com/ru/post/660565/)

**plugin_tts_rhvoice.py** - (оффлайн) TTS через RHVoice.
Использует rhvoice-wrapper.
Голос задается в конфиге.
Рекомендуемые команды для установки:
```
pip install rhvoice-wrapper
pip install rhvoice-wrapper-bin --only-binary rhvoice-wrapper-bin
```
Для Linux, и если не работает rhvoice-wrapper-bin - посмотрите источник https://github.com/Aculeasis/rhvoice-wrapper-bin

Доп информация по установке rhvoice-wrapper: https://libraries.io/pypi/rhvoice-wrapper

**Важно:** если соберетесь использовать, переключите настройку в core.json:
`"playWavEngineId": "sounddevice",`
потому что через audioplayer не проигрывает WAV по неизвестным причинам.