enderturing 0.11.0
Python SDK for EnderTuring speech toolkit
License: MIT
Requires Python: >=3.9
Keywords: ASR, speech, enderturing

# Ender Turing

Ender Turing is a solution for voice content understanding, analytics and business insights.
Check [enderturing.com](https://enderturing.com/) for details.

## Installation

```shell
$ pip install enderturing
```

For using streaming speech recognition functions, you'll also need FFmpeg installed.

Ubuntu:
```shell
$ sudo apt install ffmpeg
```

MacOS homebrew:
```shell
$ brew install ffmpeg
```

For other OS, please follow FFmpeg installation guides.

## Quick Start

```python
import asyncio
from enderturing import Config, EnderTuring, RecognitionResultFormat

# create configuration
config = Config.from_url("https://admin%40local.enderturing.com:your_password@enterturing.yourcompany.com")
et = EnderTuring(config)

# access sessions list
sessions = et.sessions.list()
print(sessions)

# get recognizer for one of configured languages
recognizer = et.get_speech_recognizer(language='en')

async def run_stream_recog(f, r, result_format):
    async with r.stream_recognize(f, result_format=result_format) as rec:
        text = await rec.read()
    return text

# recognize specified file
loop = asyncio.get_event_loop()
task = loop.create_task(run_stream_recog("my_audio.mp3", recognizer, result_format=RecognitionResultFormat.text))
loop.run_until_complete(task)
print(task.result())
```

## Usage

SDK contains two major parts:

- Using Ender Turing REST API
- Speech recognition

## Using Ender Turing API

All API calls are accessible via an instance or `EnderTuring`. API methods are grouped, and each
group is a property of `EnderTuring`. Examples:
```python
from enderturing import Config, EnderTuring, RecognitionResultFormat

et = EnderTuring(Config.from_env())

# access sessions list
sessions = et.sessions.list()

# working with ASR
et.asr.get_instances(active_only=True)

# accessing raw json
et.raw.create_event(caller_id='1234', event_data={"type": "hold"})
```

## Access Configuration

To access API, you need to know an authentication key (login), authentication secret (password), and
installation URL (e.g. https://enderturing.yourcompany.com/)

There are multiple ways to pass config options:

- from environmental variables (`Config.from_env()`).
- creating `Config` with parameters (e.g. `Config(auth_key="my_login", auth_secret="my_secret"")`)
- using Enter Turing configuration URL (`Config.from_url()`)

## Creating Speech Recognizer

There two options to create a speech recognizer:

### If you have access to API configured:
```python
recognizer = et.get_speech_recognizer(language='en')
```

### If you know URL and sample rate of desired ASR instance:
```python
from enderturing import AsrConfig, SpeechRecognizer

config = AsrConfig(url="wss://enderturing", sample_rate=8000)
recognizer = SpeechRecognizer(config)
```

## Recognizing a File

`SpeechRecognizer.recognize_file` method returns an async text stream. Depending on parameters,
each line contains either a text of utterance or serialized JSON.

If you are only interested in results after recognition is complete, you can use the `read()` method. E.g.

```python
async with recognizer.recognize_file("my_audio.wav", result_format=RecognitionResultFormat.text) as rec:
    text = await rec.read()
```

If you prefer getting words and phrases as soon as they are recognized - you can
use the `readline()` method instead. E.g.

```python
async with recognizer.recognize_file(src, result_format=RecognitionResultFormat.jsonl) as rec:
    line = await rec.readline()
    while line:
        # Now line contains a json string, you can save it or do something else with it
        line = await rec.readline()

```

## Working With Multichannel Audio

If an audio file has more than one channel - by default system will recognize each channel and
return a transcript for each channel. To change the default behavior - you can use `channels`
parameter of `SpeechRecognizer.recognize_file`. Please check method documentation for details.

Sometimes an audio is stored as a file per channel, e.g., contact center call generates two files:
one for a client and one for a support agent. But for analysis, it's preferable to see transcripts
of the files merged as a dialog. In this scenario, you can use
`recognizer.recognize_joined_file([audio1, audio2])`.

## License

Released under the MIT license.