# afaligner
## Overview
<b>afaligner</b> is a Python library for automatic text and audio synchronization (a.k.a. forced aligner). You give it a list of text files and a list of audio files that contain the narrated text, and it produces a mapping between text fragments and the corresponding audio fragments.
<b>afaligner</b> is used in the [syncabook](https://github.com/r4victor/syncabook) command-line tool to produce EPUB3 with Media Overlays ebooks and has been developed for this specific purpose. If you want to create an ebook with synchronized text and audio, consider using [syncabook](https://github.com/r4victor/syncabook) instead of using <b>afaligner</b> directly.
<b>afaligner</b> works by synthesizing text and then aligning synthesized and recorded audio using a variation of the [DTW](https://en.wikipedia.org/wiki/Dynamic_time_warping) (Dynamic Time Warping) algorithm. The main features of the algorithm are:
* It can handle structural differences in the beginning and in the end of files, which is often the case with audiobooks (e.g. disclaimers).
* It finds an approximation to an optimal warping path in linear time and space using the FastDTW approach. This and the fact that the algorithm is implemented in C make it pretty fast compared to other forced aligners.
* It can, with varying success, align differently split text and audio.
<b>afaligner</b> was inspired by [aeneas](https://github.com/readbeyond/aeneas) and works in a similar way. It uses <b>aeneas</b> as a dependency for text synthesis and MFCC extraction.
## Supported platforms
<b>afaligner</b> works on 64-bit Mac OS and Linux. Windows is not currently supported (you may try to use a VM).
## Requirements
* Python (>= 3.6)
* FFmpeg
* eSpeak
* Python packages: `aeneas`, `numpy`, `jinja2`
## Installation
1. Install [Python](https://www.python.org/) (>= 3.6)
2. Install [FFmpeg](https://www.ffmpeg.org/) and [eSpeak](http://espeak.sourceforge.net/)
3. Install <b>numpy</b>:
```
pip install numpy
```
4. Install <b>afaligner</b>:
```
pip install afaligner
```
Or if you want to modify the <b>afaligner</b>'s source code:
4. Get the repository:
```
git clone https://github.com/r4victor/afaligner/ && cd afaligner
```
5. Install <b>afaligner</b> in editable mode:
```
pip install -e .
```
## Running tests
1. Install `pytest`:
```
pip install pytest
```
2. Run tests:
```
python -m pytest tests/
```
## Installation via Docker
Installing all the <b>afaligner</b>'s dependencies can be tedious, so the library comes with Dockerfile. You can use it to build a Debian-based Docker image that contains <b>afaligner</b> itself and all its dependencies. Alternatively, you can use Dockerfile as a reference to install <b>afaligner</b> on your machine.
Installation via Docker:
1. Get the repository:
```
git clone https://github.com/r4victor/afaligner/ && cd afaligner
```
2. Build an image:
```
docker build -t afaligner .
```
3. Now you can run the container like so:
```
docker run -ti afaligner
```
It enters bash. You can run Python and `import afaligner`. To do something useful, you may need to mount your code that uses <b>afaligner</b> as a volume.
## Usage
<b>afaligner</b> provides only one function called `align()` that takes a text directory, an audio directory, and a set of output parameters and returns a sync map (a mapping from text fragments to their time positions in audio files). If the output directory is specified, it also writes the result in the JSON or SMIL format to that directory. The call may look like this:
```python
from afaligner import align
sync_map = align(
'ebooks/demoebook/text/',
'ebooks/demoebook/audio/',
output_dir='ebooks/demoebook/smil/',
output_format='smil',
sync_map_text_path_prefix='../text/',
sync_map_audio_path_prefix='../audio/'
)
```
and `sync_map` has the following structure:
```python
{
"p001.xhtml": {
"f001": {
"audio_file": "p001.mp3",
"begin_time": "0:00:00.000",
"end_time": "0:00:02.600",
},
"f002": {
"audio_file": "p001.mp3",
"begin_time": "0:00:02.600",
"end_time": "0:00:05.880",
},
# ...
},
"p002.xhtml": {
"f016": {
"audio_file": "p002.mp3",
"begin_time": "0:00:00.000",
"end_time": "0:00:03.040",
}
# ...
},
}
```
For more details, please refer to docstrings.
## Troubleshooting
`pip install afaligner` may not work on macOS if it tries to compile a [universal library](https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary). This seems to be because `aeneas` complies only on x86_64. I got an error when using Python 3.9. The following command fixes it:
```
ARCHFLAGS="-arch x86_64" pip install afaligner
```
Raw data
{
"_id": null,
"home_page": "https://github.com/r4victor/afaligner",
"name": "afaligner",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "forced-alignment",
"author": "Victor Skvortsov",
"author_email": "vds003@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a3/29/80acb288de1ff1bad87092ed2bd03a7b4e38b00c619a0ae0dccdb631d7fe/afaligner-0.2.0.tar.gz",
"platform": null,
"description": "# afaligner\n\n## Overview\n\n<b>afaligner</b> is a Python library for automatic text and audio synchronization (a.k.a. forced aligner). You give it a list of text files and a list of audio files that contain the narrated text, and it produces a mapping between text fragments and the corresponding audio fragments.\n\n\n<b>afaligner</b> is used in the [syncabook](https://github.com/r4victor/syncabook) command-line tool to produce EPUB3 with Media Overlays ebooks and has been developed for this specific purpose. If you want to create an ebook with synchronized text and audio, consider using [syncabook](https://github.com/r4victor/syncabook) instead of using <b>afaligner</b> directly.\n\n<b>afaligner</b> works by synthesizing text and then aligning synthesized and recorded audio using a variation of the [DTW](https://en.wikipedia.org/wiki/Dynamic_time_warping) (Dynamic Time Warping) algorithm. The main features of the algorithm are:\n\n* It can handle structural differences in the beginning and in the end of files, which is often the case with audiobooks (e.g. disclaimers).\n\n* It finds an approximation to an optimal warping path in linear time and space using the FastDTW approach. This and the fact that the algorithm is implemented in C make it pretty fast compared to other forced aligners.\n\n* It can, with varying success, align differently split text and audio. \n\n<b>afaligner</b> was inspired by [aeneas](https://github.com/readbeyond/aeneas) and works in a similar way. It uses <b>aeneas</b> as a dependency for text synthesis and MFCC extraction.\n\n## Supported platforms\n\n<b>afaligner</b> works on 64-bit Mac OS and Linux. Windows is not currently supported (you may try to use a VM).\n\n## Requirements\n\n* Python (>= 3.6)\n* FFmpeg\n* eSpeak\n* Python packages: `aeneas`, `numpy`, `jinja2`\n\n## Installation\n\n1. Install [Python](https://www.python.org/) (>= 3.6)\n\n2. Install [FFmpeg](https://www.ffmpeg.org/) and [eSpeak](http://espeak.sourceforge.net/)\n\n3. Install <b>numpy</b>:\n ```\n pip install numpy\n ```\n\n4. Install <b>afaligner</b>:\n ```\n pip install afaligner\n ```\n\nOr if you want to modify the <b>afaligner</b>'s source code:\n\n4. Get the repository:\n\n ```\n git clone https://github.com/r4victor/afaligner/ && cd afaligner\n ```\n\n5. Install <b>afaligner</b> in editable mode:\n ```\n pip install -e .\n ```\n\n## Running tests\n\n1. Install `pytest`:\n ```\n pip install pytest\n ```\n\n2. Run tests:\n ```\n python -m pytest tests/\n ```\n\n## Installation via Docker\n\nInstalling all the <b>afaligner</b>'s dependencies can be tedious, so the library comes with Dockerfile. You can use it to build a Debian-based Docker image that contains <b>afaligner</b> itself and all its dependencies. Alternatively, you can use Dockerfile as a reference to install <b>afaligner</b> on your machine.\n\nInstallation via Docker:\n\n1. Get the repository:\n\n ```\n git clone https://github.com/r4victor/afaligner/ && cd afaligner\n ```\n\n2. Build an image:\n ```\n docker build -t afaligner .\n ```\n\n3. Now you can run the container like so:\n ```\n docker run -ti afaligner\n ```\n It enters bash. You can run Python and `import afaligner`. To do something useful, you may need to mount your code that uses <b>afaligner</b> as a volume.\n\n## Usage\n\n<b>afaligner</b> provides only one function called `align()` that takes a text directory, an audio directory, and a set of output parameters and returns a sync map (a mapping from text fragments to their time positions in audio files). If the output directory is specified, it also writes the result in the JSON or SMIL format to that directory. The call may look like this:\n\n```python\nfrom afaligner import align\n\n\nsync_map = align(\n 'ebooks/demoebook/text/',\n 'ebooks/demoebook/audio/',\n output_dir='ebooks/demoebook/smil/',\n output_format='smil',\n sync_map_text_path_prefix='../text/',\n sync_map_audio_path_prefix='../audio/'\n)\n```\n\nand `sync_map` has the following structure:\n\n```python\n{\n \"p001.xhtml\": {\n \"f001\": {\n \"audio_file\": \"p001.mp3\",\n \"begin_time\": \"0:00:00.000\",\n \"end_time\": \"0:00:02.600\",\n },\n \"f002\": {\n \"audio_file\": \"p001.mp3\",\n \"begin_time\": \"0:00:02.600\",\n \"end_time\": \"0:00:05.880\",\n },\n # ...\n },\n \"p002.xhtml\": {\n \"f016\": {\n \"audio_file\": \"p002.mp3\",\n \"begin_time\": \"0:00:00.000\",\n \"end_time\": \"0:00:03.040\",\n }\n # ...\n },\n}\n```\n\nFor more details, please refer to docstrings.\n\n## Troubleshooting\n\n`pip install afaligner` may not work on macOS if it tries to compile a [universal library](https://developer.apple.com/documentation/apple-silicon/building-a-universal-macos-binary). This seems to be because `aeneas` complies only on x86_64. I got an error when using Python 3.9. The following command fixes it:\n\n```\nARCHFLAGS=\"-arch x86_64\" pip install afaligner\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A forced aligner intended for synchronization of narrated text",
"version": "0.2.0",
"split_keywords": [
"forced-alignment"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a32980acb288de1ff1bad87092ed2bd03a7b4e38b00c619a0ae0dccdb631d7fe",
"md5": "416c98e1cf92c40a8a2465b5fe25a211",
"sha256": "9457f624112b2fcb46118af001be89ba463aa0b43e8b9e95f71e0572e5705821"
},
"downloads": -1,
"filename": "afaligner-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "416c98e1cf92c40a8a2465b5fe25a211",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16550,
"upload_time": "2023-01-19T06:10:32",
"upload_time_iso_8601": "2023-01-19T06:10:32.003463Z",
"url": "https://files.pythonhosted.org/packages/a3/29/80acb288de1ff1bad87092ed2bd03a7b4e38b00c619a0ae0dccdb631d7fe/afaligner-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-19 06:10:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "r4victor",
"github_project": "afaligner",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "afaligner"
}
JSON
