Document UpliftAI engine in README #64
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| """Example usage of the UpliftAI engine.""" | ||
|
|
||
| import os | ||
|
|
||
| from tts_wrapper import UpliftAIClient | ||
|
|
||
|
|
||
| def main() -> None: | ||
| api_key = os.getenv("UPLIFTAI_KEY") | ||
| if not api_key: | ||
| raise RuntimeError("UPLIFTAI_KEY environment variable is not set") | ||
|
|
||
| client = UpliftAIClient(api_key=api_key) | ||
| text = "Testing the UpliftAI text to speech engine" | ||
| client.speak_streamed(text) | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| main() |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| """UpliftAI TTS engine for tts-wrapper.""" | ||
|
|
||
| from .client import UpliftAIClient | ||
|
|
||
| __all__ = ["UpliftAIClient"] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,183 @@ | ||||||||
| from __future__ import annotations | ||||||||
|
|
||||||||
| import logging | ||||||||
| import os | ||||||||
| from pathlib import Path | ||||||||
| from typing import TYPE_CHECKING, Any, Callable | ||||||||
|
|
||||||||
| import requests | ||||||||
|
|
||||||||
| from tts_wrapper.tts import AbstractTTS | ||||||||
|
|
||||||||
| if TYPE_CHECKING: | ||||||||
| from collections.abc import Generator | ||||||||
|
|
||||||||
|
|
||||||||
| logger = logging.getLogger(__name__) | ||||||||
| RIFF_HEADER = b"RIFF" | ||||||||
|
|
||||||||
|
|
||||||||
| class UpliftAIClient(AbstractTTS): | ||||||||
| """Client for the UpliftAI text-to-speech API.""" | ||||||||
|
|
||||||||
| BASE_URL = "https://api.upliftai.org/v1/synthesis/text-to-speech" | ||||||||
| STREAM_URL = f"{BASE_URL}/stream" | ||||||||
| DEFAULT_VOICE = "v_8eelc901" # Info/Education Urdu | ||||||||
|
|
||||||||
| def __init__(self, api_key: str | None = None) -> None: | ||||||||
| super().__init__() | ||||||||
| self.api_key = api_key or os.getenv("UPLIFTAI_KEY") | ||||||||
| if not self.api_key: | ||||||||
| msg = "UpliftAI API key is required. Set UPLIFTAI_KEY or pass api_key." | ||||||||
| raise ValueError(msg) | ||||||||
|
|
||||||||
| self.headers = {"Authorization": self.api_key, "Content-Type": "application/json"} | ||||||||
| self.audio_rate = 22050 | ||||||||
| self.voice_id = self.DEFAULT_VOICE | ||||||||
|
|
||||||||
| def set_voice(self, voice_id: str, lang: str | None = None) -> None: | ||||||||
| """Set the voice for synthesis.""" | ||||||||
| self.voice_id = voice_id | ||||||||
| if lang: | ||||||||
| self.lang = lang | ||||||||
|
|
||||||||
| def synth_to_bytes(self, text: Any, voice_id: str | None = None) -> bytes: | ||||||||
| """Synthesize text to audio bytes using the non-streaming endpoint.""" | ||||||||
| voice = voice_id or self.voice_id or self.DEFAULT_VOICE | ||||||||
| payload = { | ||||||||
| "voiceId": voice, | ||||||||
| "text": str(text), | ||||||||
| "outputFormat": "WAV_22050_16", | ||||||||
| } | ||||||||
| response = requests.post(self.BASE_URL, json=payload, headers=self.headers, timeout=30) | ||||||||
|
There was a problem hiding this comment. P0 | Confidence: High The code attempts to call self._strip_wav_header() which is not defined anywhere in the class. This will cause an AttributeError at runtime when processing WAV audio from UpliftAI. The related test test_synth_to_bytes explicitly checks for RIFF header stripping, confirming this is required functionality. Without this method, all UpliftAI audio synthesis will fail.
Suggested change
|
||||||||
| response.raise_for_status() | ||||||||
| audio_bytes = response.content | ||||||||
| if audio_bytes[:4] == RIFF_HEADER: | ||||||||
| audio_bytes = self._strip_wav_header(audio_bytes) | ||||||||
| return audio_bytes | ||||||||
|
|
||||||||
| def synth_to_bytestream( | ||||||||
| self, text: Any, voice_id: str | None = None | ||||||||
| ) -> Generator[bytes, None, None]: | ||||||||
| """Stream synthesized audio chunks from the API.""" | ||||||||
| voice = voice_id or self.voice_id or self.DEFAULT_VOICE | ||||||||
| payload = { | ||||||||
| "voiceId": voice, | ||||||||
| "text": str(text), | ||||||||
| "outputFormat": "WAV_22050_16", | ||||||||
| } | ||||||||
| with requests.post( | ||||||||
| self.STREAM_URL, json=payload, headers=self.headers, stream=True, timeout=30 | ||||||||
| ) as response: | ||||||||
| response.raise_for_status() | ||||||||
| header_buffer = b"" | ||||||||
|
There was a problem hiding this comment. P1 | Confidence: Medium The WAV header stripping logic assumes a fixed 44-byte header, which is fragile. While this matches the current UpliftAI API, WAV headers can vary in length. The related test test_upliftai_streaming_strips_wav_header validates this assumption but doesn't guarantee future compatibility. A more robust approach would parse the WAV header structure to find the actual data start position. |
||||||||
| header_skipped = False | ||||||||
| for chunk in response.iter_content(chunk_size=4096): | ||||||||
| if not chunk: | ||||||||
| continue | ||||||||
| if not header_skipped: | ||||||||
| header_buffer += chunk | ||||||||
| if len(header_buffer) <= 44: | ||||||||
| continue | ||||||||
| data = header_buffer[44:] | ||||||||
| header_skipped = True | ||||||||
| if not data: | ||||||||
| continue | ||||||||
| yield data | ||||||||
| continue | ||||||||
| yield chunk | ||||||||
|
|
||||||||
| def synth( | ||||||||
| self, | ||||||||
| text: Any, | ||||||||
| output_file: str | Path, | ||||||||
| output_format: str = "wav", | ||||||||
| voice_id: str | None = None, | ||||||||
| ) -> None: | ||||||||
| """Synthesize text to a file.""" | ||||||||
| audio_bytes = self.synth_to_bytes(text, voice_id) | ||||||||
| with Path(output_file).open("wb") as f: | ||||||||
| f.write(audio_bytes) | ||||||||
|
|
||||||||
| def _get_voices(self) -> list[dict[str, Any]]: | ||||||||
|
There was a problem hiding this comment. P2 | Confidence: High Hardcoding voice metadata creates a maintenance burden and potential synchronization issues if UpliftAI updates their voice offerings. The related test context shows this data is critical for voice selection functionality. Consider implementing a periodic background update mechanism or providing a clear way to update these values without code changes. |
||||||||
| """Return the list of available voices. | ||||||||
|
|
||||||||
| The UpliftAI service does not provide a voices endpoint, | ||||||||
| so the voices are hardcoded. | ||||||||
| """ | ||||||||
| return [ | ||||||||
| { | ||||||||
| "id": "v_meklc281", | ||||||||
| "name": "Info/Education V2", | ||||||||
| "gender": "neutral", | ||||||||
| "language_codes": ["ur"], | ||||||||
| }, | ||||||||
| { | ||||||||
| "id": "v_8eelc901", | ||||||||
| "name": "Info/Education", | ||||||||
| "gender": "neutral", | ||||||||
| "language_codes": ["ur"], | ||||||||
| }, | ||||||||
| { | ||||||||
| "id": "v_30s70t3a", | ||||||||
| "name": "Nostalgic News", | ||||||||
| "gender": "neutral", | ||||||||
| "language_codes": ["ur"], | ||||||||
| }, | ||||||||
| { | ||||||||
| "id": "v_yypgzenx", | ||||||||
| "name": "Dada Jee", | ||||||||
| "gender": "male", | ||||||||
| "language_codes": ["ur"], | ||||||||
| }, | ||||||||
| { | ||||||||
| "id": "v_kwmp7zxt", | ||||||||
| "name": "Gen Z", | ||||||||
| "gender": "neutral", | ||||||||
| "language_codes": ["ur"], | ||||||||
| }, | ||||||||
| {"id": "v_sd0kl3m9", "name": "Female", "gender": "female", "language_codes": ["sd"]}, | ||||||||
| { | ||||||||
| "id": "v_sd6mn4p2", | ||||||||
| "name": "Male Calm", | ||||||||
| "gender": "male", | ||||||||
| "language_codes": ["sd"], | ||||||||
| }, | ||||||||
| { | ||||||||
| "id": "v_sd9qr7x5", | ||||||||
| "name": "Male News", | ||||||||
| "gender": "male", | ||||||||
| "language_codes": ["sd"], | ||||||||
| }, | ||||||||
| { | ||||||||
| "id": "v_bl0ab8c4", | ||||||||
| "name": "Balochi Male", | ||||||||
| "gender": "male", | ||||||||
| "language_codes": ["bal"], | ||||||||
| }, | ||||||||
| { | ||||||||
| "id": "v_bl1de2f7", | ||||||||
| "name": "Balochi Female", | ||||||||
| "gender": "female", | ||||||||
| "language_codes": ["bal"], | ||||||||
| }, | ||||||||
| ] | ||||||||
|
|
||||||||
| def check_credentials(self) -> bool: # pragma: no cover - network call | ||||||||
| """Verify that the API key works by making a small request.""" | ||||||||
| try: | ||||||||
| payload = { | ||||||||
| "voiceId": self.voice_id or self.DEFAULT_VOICE, | ||||||||
| "text": "ping", | ||||||||
| "outputFormat": "WAV_22050_16", | ||||||||
| } | ||||||||
| response = requests.post(self.BASE_URL, json=payload, headers=self.headers, timeout=10) | ||||||||
| response.raise_for_status() | ||||||||
| return True | ||||||||
| except Exception: | ||||||||
| logger.debug("UpliftAI credential check failed", exc_info=True) | ||||||||
| return False | ||||||||
|
|
||||||||
| def connect(self, event_name: str, callback: Callable) -> None: | ||||||||
| """Connect a callback function to an event.""" | ||||||||
| super().connect(event_name, callback) | ||||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2 | Confidence: High
The feature matrix accurately represents UpliftAI's capabilities based on the implementation. However, the notes about SSML and word boundary handling should be verified against the actual UpliftAI API documentation to ensure accuracy, as these are important differentiation points for users.