| Name | tts-joinery JSON |
| Version |
1.0.4
JSON |
| download |
| home_page | None |
| Summary | Automate chunking long texts to produce a single audio file from text-to-speech APIs |
| upload_time | 2024-10-11 18:04:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| 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. |
| keywords |
openai
tts
ai
cli
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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) (for better audio by avoiding segments split in the middle of a word or sentence).
- 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] [COMMAND]
```
#### 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.
Commands:
cache [clear, show]
```
#### 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 running the same text multiple times, this can be disabled:
```bash
ttsjoin --input-file input.txt --output-file output.mp3 --no-cache
```
5. Clear cache directory
```bash
ttsjoin cache clear
```
### Python Library
You can also use tts-joinery as part of your Python project:
```python
import nltk
from joinery.op import JoinOp
from joinery.api.openai import OpenAIApi
# Only need to download once, handled for you automatically in the CLI
nltk.download('punkt_tab', quiet=True)
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.4 (2024-10-11)
- Fixed issue with nltk dependency [#4](https://github.com/drien/tts-joinery/issues/5)
- Model, voice, and service CLI params are now case-insensitive
#### v1.0.3 (2024-10-05)
- Added cache management commands to cli
- Fixed a bug when running
- Added end-to-end tests
#### 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.
Test can be run manually. Suite includes end-to-end tests with live API calls, ensure you have an OPENAI_API_KEY set in `.env.test`, and run `pytest`. You can install development dependencies with `pip install -e .[test]`
## Contributors
Special thanks to:
- [Mayank Vishwakarma](mailto:mayank@mynk.me) (@mayankwebbing)
## License
This project is licensed under the MIT License.
Copyright 2024, Adrien Delessert
Raw data
{
"_id": null,
"home_page": null,
"name": "tts-joinery",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "openai, tts, ai, cli",
"author": null,
"author_email": "Adrien Delessert <adrien@delessert.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/b9/bd74ca4dfc9872430d71d44d66032b9dc04cde3ed625e0654090957c1c40/tts_joinery-1.0.4.tar.gz",
"platform": null,
"description": "# tts-joinery\n\ntts-joinery is a Python library and CLI tool to work around length limitations in text-to-speech APIs.\n\nSince currently-popular APIs are limited to 4096 characters, this library will:\n\n- Chunk the input text into sentences using the [NLTK Punkt module](https://www.nltk.org/api/nltk.tokenize.punkt.html) (for better audio by avoiding segments split in the middle of a word or sentence).\n- Run each chunk through the TTS API\n- Join together the resulting output to produce a single MP3 file\n\nCurrently only the OpenAI API is supported, with the intent to add more in the future.\n\n## Installation\n\n```bash\npip install tts-joinery\n```\n\nor use `pipx` to install as a standalone tool.\n\n**Requires ffmpeg** for the audio file processing.\n\nInstallation may vary depending on your system. On Linux you can use your system package manager. On Mac `brew install ffmpeg` should work.\n\n## Usage\n\n### Command-Line Interface (CLI)\n\nThe CLI expects to find an OpenAI API Key in a `OPENAI_API_KEY` environment variable, or in a .env file.\n\n#### Syntax\n\n```\nttsjoin [OPTIONS] [COMMAND]\n```\n\n#### Options\n\n```\nOptions:\n--input-file FILENAME Plaintext file to process into speech, otherwise stdin\n--output-file FILENAME MP3 result, otherwise stdout\n--model TEXT Slug of the text-to-speech model to be used\n--service TEXT API service (currently only supports openai)\n--voice TEXT Slug of the voice to be used\n--no-cache BOOLEAN Disable caching\n--help Show this message and exit.\n\nCommands:\n cache [clear, show]\n```\n\n#### Examples\n\n1. Using an input file and specifying an output file:\n\n```bash\nttsjoin --input-file input.txt --output-file output.mp3 --model tts-1 --service openai --voice onyx\n```\n\n2. Using stdin and stdout with default options:\n\n```bash\necho \"Your text to be processed\" | ttsjoin > output.mp3\n```\n\n3. Each chunk of text is cached for performance when running the same text multiple times, this can be disabled:\n\n```bash\nttsjoin --input-file input.txt --output-file output.mp3 --no-cache\n```\n\n5. Clear cache directory\n\n```bash\nttsjoin cache clear\n```\n\n### Python Library\n\nYou can also use tts-joinery as part of your Python project:\n\n```python\nimport nltk\n\nfrom joinery.op import JoinOp\nfrom joinery.api.openai import OpenAIApi\n\n# Only need to download once, handled for you automatically in the CLI\nnltk.download('punkt_tab', quiet=True)\n\ntts = JoinOp(\n text='This is only a test!',\n api=OpenAIApi(\n model='tts-1-hd',\n voice='onyx',\n api_key=OPENAI_API_KEY,\n ),\n)\n\ntts.process_to_file('output.mp3')\n```\n\n## Changelog\n\n#### v1.0.4 (2024-10-11)\n\n- Fixed issue with nltk dependency [#4](https://github.com/drien/tts-joinery/issues/5)\n- Model, voice, and service CLI params are now case-insensitive\n\n#### v1.0.3 (2024-10-05)\n\n- Added cache management commands to cli\n- Fixed a bug when running\n- Added end-to-end tests\n\n#### v1.0.2 (2024-10-03)\n\n- Fixed crash when running with caching disabled (#3)\n\n## Contributing\n\nContributions welcome, particularly other TTS APIs, check the issues beforehand and feel free to open a PR. Code is formatted with Black.\n\nTest can be run manually. Suite includes end-to-end tests with live API calls, ensure you have an OPENAI_API_KEY set in `.env.test`, and run `pytest`. You can install development dependencies with `pip install -e .[test]`\n\n## Contributors\n\nSpecial thanks to:\n\n- [Mayank Vishwakarma](mailto:mayank@mynk.me) (@mayankwebbing)\n\n## License\n\nThis project is licensed under the MIT License.\n\nCopyright 2024, Adrien Delessert\n",
"bugtrack_url": null,
"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.",
"summary": "Automate chunking long texts to produce a single audio file from text-to-speech APIs",
"version": "1.0.4",
"project_urls": {
"Homepage": "https://github.com/drien/tts-joinery"
},
"split_keywords": [
"openai",
" tts",
" ai",
" cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e28708566df9f1d307fec994cbeaa8db59108b8d8ab3b1e09dc0cfde742b0b88",
"md5": "6ef7cdeaa7689334ceb3a6d9439f122c",
"sha256": "2f3c64d2eb2f12e94e039219973fe47ec54b1749c77b6b91bf1a1a3b460207c9"
},
"downloads": -1,
"filename": "tts_joinery-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6ef7cdeaa7689334ceb3a6d9439f122c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 10485,
"upload_time": "2024-10-11T18:04:46",
"upload_time_iso_8601": "2024-10-11T18:04:46.391597Z",
"url": "https://files.pythonhosted.org/packages/e2/87/08566df9f1d307fec994cbeaa8db59108b8d8ab3b1e09dc0cfde742b0b88/tts_joinery-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c2b9bd74ca4dfc9872430d71d44d66032b9dc04cde3ed625e0654090957c1c40",
"md5": "a04ca5125711f7d86cfb918bafa26c9f",
"sha256": "8fc29a93c6f3ee3439f1a5efe3d3b77c52044a2f477aac2f8c6f34c2283aa778"
},
"downloads": -1,
"filename": "tts_joinery-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "a04ca5125711f7d86cfb918bafa26c9f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10366,
"upload_time": "2024-10-11T18:04:47",
"upload_time_iso_8601": "2024-10-11T18:04:47.447442Z",
"url": "https://files.pythonhosted.org/packages/c2/b9/bd74ca4dfc9872430d71d44d66032b9dc04cde3ed625e0654090957c1c40/tts_joinery-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-11 18:04:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "drien",
"github_project": "tts-joinery",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tts-joinery"
}
