feat(helpers): add helper class for tts pronunciation and pause controls #646
Conversation
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
…controls - Add TextBuilder fluent builder class with text(), pronunciation(), pause(), from_ssml(), and build() methods - Add standalone utility functions: add_pronunciation(), ssml_to_deepgram(), validate_ipa(), validate_pause() - Implement comprehensive input validation and API limit enforcement (500 pronunciations, 50 pauses, 2000 chars) - Support SSML parsing and conversion (phoneme and break tags) - Include proper JSON escaping and error handling
- Export TextBuilder, add_pronunciation, ssml_to_deepgram, validate_ipa, and validate_pause from deepgram package - Add to __all__ and _dynamic_imports for lazy loading - Enable usage: from deepgram import TextBuilder
- Add 50+ test cases covering all TextBuilder functionality - Test basic text, pronunciation, pause, and SSML conversion - Test validation functions and error handling - Test API limit enforcement (pronunciations, pauses, characters) - Test standalone functions (add_pronunciation, ssml_to_deepgram) - Include integration tests with real-world examples
- Add 25-text-builder-demo.py: interactive demonstration of all features (no API key required) - Add 25-text-builder-helper.py: live TTS generation examples with API integration - Include examples for basic usage, SSML migration, standalone functions, and real-world scenarios - Cover medical prescriptions, pharmacy instructions, and scientific terminology use cases
- Add TextBuilder demo and helper examples to Text-to-Speech section - Include both interactive demo (no API key) and live TTS generation examples
Renumber all examples to group by feature area, with each section starting at multiples of 10: - 01-09: Authentication - 10-19: Transcription (Listen) - 20-29: Text-to-Speech (Speak) - including new TextBuilder streaming example - 30-39: Voice Agent - 40-49: Text Intelligence (Read) - 50-59: Management API - 60-69: On-Premises - 70-79: Configuration & Advanced This makes the examples easier to navigate and leaves room for future additions in each section.
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
- Fix ssml_to_deepgram to handle SSML fragments (not just complete documents) - Fix validate_pause to check integer type before increment validation - Fix test case to use correct case-sensitive word matching
naomi-deepgram
approved these changes
Jan 9, 2026
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
This pull request adds three new comprehensive example scripts showcasing the usage of the
TextBuilderand related helper functions for Deepgram TTS. These examples cover interactive demonstrations, REST API integration, and real-time streaming via WebSocket, making it easier for developers to understand and utilize advanced TTS features such as custom pronunciations, pauses, SSML migration, validation, error handling, and API limits.New Example Scripts Added:
TextBuilder demonstration and usage:
examples/22-text-builder-demo.py, an interactive script demonstrating all features ofTextBuilder, including basic usage, helper functions, SSML conversion, validation, error handling, real-world scenarios, and a summary of API limits. No API key required; focuses on text formatting.REST API integration:
examples/23-text-builder-helper.py, which shows how to useTextBuilderwith the Deepgram REST API to generate audio files, including examples for basic usage, standalone helpers, SSML migration, mixed SSML/builder usage, and pharmacy instructions.Streaming/WebSocket integration:
examples/24-text-builder-streaming.py, demonstrating how to useTextBuilderfor real-time TTS audio generation via WebSocket, including streaming single and multiple messages and saving the resulting audio data.