Metadata-Version: 2.1
Name: tts-joinery
Version: 1.0.2
Summary: Automate chunking long texts to produce a single audio file from text-to-speech APIs
Author-email: Adrien Delessert <adrien@delessert.com>
License: MIT License
        
        Copyright (c) 2024 Adrien Delessert
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/drien/tts-joinery
Keywords: openai,tts,ai,cli
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: nltk
Requires-Dist: openai
Requires-Dist: pip-tools
Requires-Dist: platformdirs
Requires-Dist: pydub
Requires-Dist: python-dotenv

# tts-joinery

tts-joinery is a Python library and CLI tool to work around length limitations in text-to-speech APIs.

Since currently-popular APIs are limited to 4096 characters, this library will:

-   Chunk the input text into sentences using the [NLTK Punkt module](https://www.nltk.org/api/nltk.tokenize.punkt.html)
-   Run each chunk through the TTS API
-   Join together the resulting output to produce a single MP3 file

Currently only the OpenAI API is supported, with the intent to add more in the future.

## Installation

```bash
pip install tts-joinery
```

or use `pipx` to install as a standalone tool.

**Requires ffmpeg** for the audio file processing.

Installation may vary depending on your system. On Linux you can use your system package manager. On Mac `brew install ffmpeg` should work.

## Usage

### Command-Line Interface (CLI)

The CLI expects to find an OpenAI API Key in a `OPENAI_API_KEY` environment variable, or in a .env file.

#### Syntax

```
ttsjoin [OPTIONS]
```

#### Options

```
--input-file FILENAME   Plaintext file to process into speech, otherwise stdin
--output-file FILENAME  MP3 result, otherwise stdout
--model TEXT            Slug of the text-to-speech model to be used
--service TEXT          API service (currently only supports openai)
--voice TEXT            Slug of the voice to be used
--no-cache BOOLEAN      Disable caching
--help                  Show this message and exit.
```

#### Examples

1. Using an input file and specifying an output file:

```bash
ttsjoin --input-file input.txt --output-file output.mp3 --model tts-1 --service openai --voice onyx
```

2. Using stdin and stdout with default options:

```bash
echo "Your text to be processed" | ttsjoin > output.mp3
```

3. Each chunk of text is cached for performance when the same text multiple times, this can be disabled:

```bash
ttsjoin --input-file input.txt --output-file output.mp3 --no-cache
```

### Python Library

You can also use tts-joinery as part of your Python project:

```python
from joinery.op import JoinOp
from joinery.api.openai import OpenAIApi

tts = JoinOp(
    text='This is only a test!',
    api=OpenAIApi(
        model='tts-1-hd',
        voice='onyx',
        api_key=OPENAI_API_KEY,
    ),
)

tts.process_to_file('output.mp3')
```

## Changelog

#### v1.0.2 (2024-10-03)

-   Fixed crash when running with caching disabled (#3)

## Contributing

Contributions welcome, particularly other TTS APIs, check the issues beforehand and feel free to open a PR. Code is formatted with Black.

## Contributors

Special thanks to:

-   [Mayank Vishwakarma](mailto:mayank@mynk.me) (@mayankwebbing)

## License

This project is licensed under the MIT License.

Copyright 2024, Adrien Delessert
