sensory-audio-cli 0.1.2
Client library for Audio Processing API
Requires Python: >=3.8

# **Audio Processor Client**


Описание

**Audio Processor Client** – это асинхронная библиотека для взаимодействия с сервером транскрибатора. Клиент поддерживает различные сценарии обработки аудио:
 
    • Обработка аудиофайлов с использованием синхронного (HTTP POST) и асинхронного (задачи с polling) режимов  
    • Стриминговая обработка аудио через WebSocket (в том числе файлы и поток с микрофона)  
    • Обнаружение доступных микрофонов и реализацию предварительной проверки перед началом записи  
    • Возможность включить специальный режим обработки – emotional. Благодаря нему транскрибатор анализирует не только речь, но и эмоциональную окраску голоса

Эта документация демонстрирует лучшие практики для использования клиента и предлагает подробные примеры работы.

# **Требования и установка**

Для работы клиента понадобятся Python 3.7+ и следующие зависимости:
```
– asyncio  
– httpx  
– websockets  
– pydantic  
– numpy  
– sounddevice  
– pyaudio (для альтернативной реализации работы с микрофоном, если требуется)
```

Установка зависимостей (например, через pip):
```
pip install httpx websockets pydantic numpy sounddevice pyaudio
```
Убедитесь, что аудиодрайверы и библиотеки для работы с аудиоустройствами (PortAudio) настроены правильно.

# **Быстрый старт**

Базовая схема использования клиента выглядит так:

1. Импортируйте необходимые классы:
  
    • **AudioClient** – для подключения и обработки аудио  
    • **ProcessingSettings** – для задания режима транскрипции и настроек

2. Вызывайте методы для обработки аудио:
  
    – process_audio – для передачи аудиофайлов (синхронно или асинхронно)  
    – stream_audio – для потоковой обработки файла через вебсокет  
    – async_microphone_stream – для получения аудио с микрофона и передачи на сервер в режиме реального времени

### Ниже приведён упрощённый пример:

----------------------------------------------------------------
```
import asyncio
from audio_processor.client import AudioClient, ProcessingSettings

async def main():
    async with AudioClient(base_url="http://адрес_вашего_сервера:8000") as client:
        # Пример стриминговой обработки файла
        async for chunk in client.stream_audio(
            "path/to/your_file.opus",
            ProcessingSettings(
                mode="stt",
                format_output="json",
                transcription_settings={"task": "transcribe", "emotional": True, "language": "ru"}
            )
        ):
            print(chunk)

        # Синхронная обработка: результат возвращается полностью после завершения обработки
        result = await client.process_audio(
            "path/to/your_file.opus",
            ProcessingSettings(
                mode="stt",
                format_output="json",
                transcription_settings={"emotional": True}
            )
        )
        print(result)

        # Асинхронная обработка: клиент вернёт job_id, а затем будет регулярно опрашивать статус задачи
        async_result = await client.process_audio(
            "path/to/your_file.opus",
            ProcessingSettings(
                mode="stt",
                format_output="json",
                transcription_settings={"emotional": True},
                async_process=True
            )
        )
        print(async_result)

        # Пример работы с микрофоном (подробнее в разделе "Работа с микрофоном")
        for mic_chunk in client.async_microphone_stream(mic_index=2):
            print(mic_chunk)

asyncio.run(main())
```
----------------------------------------------------------------

# **Режимы обработки аудио**

## 1. Обработка файла (process_audio)
  
   • Клиент отправляет аудиофайл на сервер через HTTP запрос  
   • Параметры задаются через объект ProcessingSettings  
   • Если параметр async_process установлен в True, клиент будет опрашивать статус обработки до получения результата  
     
   ### Пример настроек:
```
ProcessingSettings(
    mode="stt",                   # Стандартный режим распознавания речи (stt | diarization | both)
    format_output="json",         # Формат возврата результата (json | text)
    async_process=False,          # False – синхронная обработка; True – асинхронная обработка
    transcription_settings={      # Дополнительные настройки транскрипции
        "emotional": True         # Включение режима эмоциональной обработки
    }
)
```

## 2. Потоковая обработка файла (stream_audio)
  
   • Используется WebSocket соединение для передачи аудио чанками  
   • Изначально в вебсокет отправляются настройки обработки, полученные через settings.json()  
   • Сервер в режиме стриминга возвращает промежуточные результаты, которые можно обрабатывать в режиме реального времени
     
#### Для включения режима emotional достаточно передать в transcription_settings параметр "emotional": True

## 3. Обработка аудио с микрофона (async_microphone_stream)
  
   • Позволяет передавать аудио с микрофонного входа в режиме реального времени  
   • Перед началом записи рекомендуется выполнить предварительную проверку подключения микрофона:
        
```
mics = AudioClient.list_microphones()
# Вывод списка доступных устройств и выбор нужного индекса
```
     
   • Внутри метода используется sounddevice.InputStream для чтения аудио с выбранного устройства  
   • Полученные аудио чанк преобразуются в формат PCM 16-bit и отправляются через вебсокет на сервер
  
   ### Пример предварительной проверки:
```
import numpy as np
import sounddevice as sd
data_received = False
def callback(indata, frames, time, status):
    if np.max(np.abs(indata)) > 0.01:
        data_received = True

with sd.InputStream(callback=callback, samplerate=16000, channels=1):
    await asyncio.sleep(2)
if not data_received:
    print("Данные не получены. Проверьте микрофон.")
```

# **Конфигурация и настройки**

Объект ProcessingSettings позволяет гибко настраивать режим работы. Ключевые параметры:

• mode – режим обработки (например, "stt" – распознавание речи).  
• format_output – формат возвращаемых данных ("json", "text").  
• async_process – параметр, определяющий синхронную (False) или асинхронную (True) обработку аудио.  
• transcription_settings – словарь дополнительных настроек, в который можно передать:
   – "task" – задача, например "transcribe"  
   – "language" – код языка (например, "ru")  
   – "emotional" – если True, сервер активирует режим эмоционального анализа (рекомендуется для задач, где важна интонация и эмоциональная окраска речи)

### Пример включения эмоционального режима:
```
transcription_settings = {
    "task": "transcribe",
    "emotional": True,
    "language": "ru"
}
```

# Примеры использования

## A. Стриминговая обработка аудиофайла

  • Клиент открывает вебсокет соединение с сервером  
  • Отправляет настройки и затем передает аудиофайл чанками  
  • Результаты возвращаются в режиме реального времени
```
async for chunk in client.stream_audio("audio.opus", settings):
    print(chunk)
```

## B. Синхронная обработка файла

  • Клиент отправляет запрос с файлом и ждёт полного ответа от сервера
``` 
result = await client.process_audio("audio.opus", settings)
print(result)
```

## C. Асинхронная обработка файла (job polling)

  • При async_process=True клиент получает job_id и периодически опрашивает статус обработки
```
async_result = await client.process_audio("audio.opus", settings_with_async)
print(async_result)
```

## D. Обработка аудио с микрофона

  • Используйте метод list_microphones() для отображения списка доступных устройств  
  • Выберите нужный индекс микрофона и запустите потоковую передачу аудио с микрофона
```  
async for chunk in client.async_microphone_stream(chosen_mic):
    print(chunk)
```

# **Логи и отладка**

Клиент использует стандартный модуль logging для вывода служебной информации. Рекомендуется:

• Настроить логгеры для отладки ошибок подключения (например, к PortAudio)
• Проверять корректность работы предварительных callback’ов и обработку уровня сигнала с микрофона

Пример настройки логгера:
```
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
```

# **Заключение**

**Audio Processor Client** представляет собой универсальное решение для интеграции с сервером транскрипции. Библиотека позволяет:

– Обрабатывать как готовые аудиофайлы, так и потоки аудио  
– Включать режим эмоциональной транскрипции посредством передачи параметра transcription_settings: {"emotional": True}  
– Обеспечивать гибкий выбор между синхронной и асинхронной обработкой  
– Легко работать с аудиоустройствами (микрофонами) и получать список доступных устройств

Придерживайтесь описанных выше примеров и лучших практик для интеграции с вашим сервером, а также проведите предварительные тесты подключения микрофонов, чтобы обеспечить корректное получение аудиоданных.

Для любых вопросов или предложений по улучшению, пожалуйста, обращайтесь к разработчику.

# **Пример файловой структуры проекта**

```
project/
├── src/
│   └── audio_processor/
│       ├── __init__.py       
│       ├── client.py         # Основной код клиента
│       ├── exceptions.py     # Пользовательские исключения
│       ├── models.py         # Pydantic модели
│       └── utils.py          # Вспомогательный код (MicrophoneStream)
├── examples/                # Папка с примерами НЕ входит в пакет
│   └── test.py              # Пример использования
└── README.md

```

# **Вывод**

В этой документации подробно раскрыты все режимы работы с вашим клиентом транскрибатора. Особое внимание уделено режиму эмоциональной обработки, позволяющему учитывать эмоциональную окраску речи при транскрипции. Используйте предоставленные примеры в качестве основы для интеграции и дальнейшего развития функционала.

Удачной разработки!