File size: 5,774 Bytes
6b43fdd
 
 
 
 
98a43a7
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
6b43fdd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
---
license: cc-by-nc-sa-4.0
language:
- ru
---



# Omogre

## Russian Accentuator and IPA Transcriptor

A library for [`Python 3`](https://www.python.org/). Automatic stress placement and [IPA transcription](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet) for the Russian language.

## Dependencies

Installing the library will also install [`Pytorch`](https://pytorch.org/) and [`Numpy`](https://numpy.org/). Additionally, for model downloading, [`tqdm`](https://tqdm.github.io/) and [`requests`](https://pypi.org/project/requests/) will be installed.

## Installation

### Using GIT

```bash
pip install git+https://github.com/omogr/omogre.git
```

### Using pip

Download the code from [GitHub](https://github.com/omogr/omogre). In the directory containing [`setup.py`](https://github.com/omogr/omogre/blob/main/setup.py), run:

```bash
pip install -e .
```

### Manually

Download the code from [GitHub](https://github.com/omogr/omogre). Install [`Pytorch`](https://pytorch.org/), [`Numpy`](https://numpy.org/), [`tqdm`](https://tqdm.github.io/), and [`requests`](https://pypi.org/project/requests/). Run [`test.py`](https://github.com/omogr/omogre/blob/main/test.py).

## Model downloading

By default, data for models will be downloaded on the first run of the library. The script [`download_data.py`](https://github.com/omogr/omogre/blob/main/download_data.py) can also be used to download this data.

You can specify a path where the model data should be stored. If data already exists in this directory, it won't be downloaded again.

## Example

Script [`test.py`](https://github.com/omogr/omogre/blob/main/test.py).

```python
from omogre import Accentuator, Transcriptor

# Data will be downloaded to the 'omogre_data' directory
transcriptor = Transcriptor(data_path='omogre_data')
accentuator = Accentuator(data_path='omogre_data')

sentence_list = ['стены замка']

print('transcriptor', transcriptor(sentence_list))
print('accentuator', accentuator(sentence_list))

# Alternative call methods, differing only in notation
print('transcriptor.transcribe', transcriptor.transcribe(sentence_list))
print('accentuator.accentuate', accentuator.accentuate(sentence_list))

print('transcriptor.accentuate', transcriptor.accentuate(sentence_list))
```

## Class Parameters

### Transcriptor

All initialization parameters for the class are optional.

```python
class Transcriptor(data_path: str = None,
                   download: bool = True,
                   device_name: str = None,
                   punct: str = '.,!?')
```

- `data_path`: Directory where the model should be located.
- `device_name`: Parameter defining GPU usage. Corresponds to the initialization parameter of [torch.device](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device). Valid values include `"cpu"`, `"cuda"`, `"cuda:0"`, etc. Defaults to `"cuda"` if GPU is available, otherwise `"cpu"`.
- `punct`: List of non-letter characters to be carried over from the source text to the transcription. Default is `'.,!?'`.
- `download`: Whether to download the model from the internet if not found in `data_path`. Default is `True`.

Class methods:

```python
accentuate(sentence_list: list) -> list
transcribe(sentence_list: list) -> list
```

`accentuate` places stresses, `transcribe` performs transcription. Both inputs take a list of strings and return a list of strings.

### Accentuator

The `Accentuator` class for stress placement is identical to the `Transcriptor` in terms of stress functionality, except it doesn't load transcription data, reducing initialization time and memory usage.

All initialization parameters are optional, with the same meanings as for `Transcriptor`.

```python
class Accentuator(data_path: str = None,
                  download: bool = True,
                  device_name: str = None)
```

- `data_path`: Directory where the model should be located.
- `device_name`: Parameter for GPU usage. See above for details.
- `download`: Whether to download the model if not found. Default is `True`.

Class method:

```python
accentuate(sentence_list: list) -> list
```

## Usage Example

The script [`ruslan_markup.py`](https://github.com/omogr/omogre/blob/main/ruslan_markup.py) places stresses and generates transcriptions for markup files of the acoustic corpora [`ruslan`](http://dataset.sova.ai/SOVA-TTS/ruslan/ruslan_dataset.tar) and [`natasha`](http://dataset.sova.ai/SOVA-TTS/natasha/natasha_dataset.tar).

These markup files already contain manually placed stresses, which were [done manually](https://habr.com/ru/companies/ashmanov_net/articles/528296/).

The script [`ruslan_markup.py`](https://github.com/omogr/omogre/blob/main/ruslan_markup.py) generates its own stress placement for these files, allowing for an evaluation of the accuracy of stress placement.

## Context Awareness and Other Features

### Stresses

Stresses are placed considering context. If very long strings are encountered (for the current model, more than 510 tokens), context won't be considered for these. Stresses in these strings will be placed only where possible without context.

Stresses are also placed in one-syllable words, which might look unusual but simplifies subsequent transcription determination.

### Transcription

During transcription generation, extraneous characters are filtered out. Non-letter characters that are not filtered can be specified by a parameter. By default, four punctuation marks (`.,!?`) are not filtered. Transcription is determined word by word, without context. The following symbols are used for transcription:

```
ʲ`ɪətrsɐnjvmapkɨʊleɫdizofʂɕbɡxːuʐæɵʉɛ
```

## Feedback
Email for questions, comments and suggestions - `omogrus@ya.ru`.

---
license: cc-by-nc-sa-4.0
---