# YarnGPT Python Wrapper Library

## Description
YarnGPT is a Python wrapper for the YarnGPT text-to-speech model, designed to synthesize natural Nigerian-accented English speech using a pure language modeling approach. This library provides a simple API to convert text into audio output, allowing users to select from various preset voices and adjust generation parameters.

## Features
- Supports 12 preset voices (e.g., idera, jude, regina, chinenye, joke, remi, tayo, umar, osagie, onye, emma, and zainab).
- Utilizes Hugging Face's model caching for efficient model loading.
- Exposes a straightforward API function: generate_speech(text, speaker, temperature, repetition_penalty, max_length).
- Allows customization of generation parameters such as temperature, repetition penalty, and maximum token length.
- Includes unit tests to ensure core functionality.

## Installation
1. Create and activate a virtual environment:
   - On Linux/MacOS:
   ```bash
   python3 -m venv env
   source env/bin/activate
   ```
   - On Windows:
   ```bash
   python -m venv env
   env\Scripts\activate
   ```

2. Install the package in editable mode (for development):
   ```bash
   pip install -e .
   ```

3. Alternatively, build and install the distribution:
   ```bash
   python -m build
   pip install dist/yarngpt-0.1.0-py3-none-any.whl
   ```

## Usage
Import the generate_speech function and use it to generate audio:
```python
from yarngpt.core import generate_speech

# Generate speech with the default speaker and settings
audio = generate_speech("Hello, this is a test.", speaker="idera")

# To save the generated audio to a file (requires torchaudio)
import torchaudio
torchaudio.save("output.wav", audio, sample_rate=24000)
```

## Parameter Options
- `text`: The input string to convert to speech.
- `speaker`: Choose one from the available speakers (e.g., idera, jude, regina, chinenye, joke, remi, tayo, umar, osagie, onye, emma, zainab).
- `temperature`: Controls the randomness of generation (default is 0.1). For sampling-based generation, set do_sample=True if needed.
- `repetition_penalty`: A factor to reduce repetitive output (default is 1.1).
- `max_length`: The maximum length of the generated output tokens (default is 4000).

## Testing
Run the unit tests to verify functionality:
```bash
python -m unittest discover -s tests
```

## Contributing
Contributions are welcome! To contribute:
1. Fork the repository on GitHub.
2. Create a new branch for your changes (e.g., python-wrapper).
3. Commit your changes with clear messages.
4. Open a pull request with a detailed description of your changes.

Once merged, your contributions will be credited in the project's contributors list.

## License
This project is licensed under the MIT License.

## Acknowledgments
- Built with inspiration from YarnGPT and similar TTS projects.
- Utilizes Hugging Face's model caching and the transformers library.
- Special thanks to the open-source community for their ongoing support.

For more details and documentation, visit the GitHub repository: https://github.com/jerryola1
