o
it' @ s d Z ddlZddlZddlmZ G dd dZdededed efd
d Zd ed efd
dZded ee ef fddZ
de d ee ef fddZ dS )z
TTS Text Builder and Utilities
Provides helper methods for constructing TTS text with pronunciation, pause,
and speed controls for Deepgram's Text-to-Speech API.
N)Tuplec @ s e Zd ZdZdd Zdedd fddZded edd fd
d Zd edd fd
dZ dedd fddZ
deddfddZ defddZ dS ) TextBuilderu
Fluent builder for constructing TTS text with pronunciation and pause controls.
Example:
text = TextBuilder() \
.text("Take ") \
.pronunciation("azathioprine", "ˌæzəˈθaɪəpriːn") \
.text(" twice daily with ") \
.pronunciation("dupilumab", "duːˈpɪljuːmæb") \
.text(" injections") \
.pause(500) \
.text(" Do not exceed prescribed dosage.") \
.build()
c C s g | _ d| _d| _d| _dS )z Initialize empty text builder.r N)_parts_pronunciation_count _pause_count _char_count)self r Q/home/ubuntu/.local/lib/python3.10/site-packages/deepgram/helpers/text_builder.py__init__ s
zTextBuilder.__init__contentreturnc C s& |r| j | | jt|7 _| S )z
Add plain text. Returns self for chaining.
Args:
content: Plain text to add
Returns:
Self for method chaining
)r appendr len)r r r r r
text$ s
zTextBuilder.textwordipac C sn t |\}}|s t|| jdkrtdtj||ddd}| j| | jd7 _| jt|7 _| S )a
Add a word with custom pronunciation.
Formats as: {"word": "word", "pronounce":"ipa"}
Returns self for chaining.
Args:
word: The word to be pronounced
ipa: IPA pronunciation string
Returns:
Self for method chaining
Raises:
ValueError: If pronunciation limit exceeded or validation fails
z/Maximum 500 pronunciations per request exceededr pronounceF ensure_ascii ) validate_ipa
ValueErrorr jsondumpsr r r r )r r r is_valid error_msgpronunciation_jsonr r r
pronunciation3 s
zTextBuilder.pronunciation duration_msc C sP t |\}}|s t|| jdkrtd| jd| d | jd7 _| S )a
Add a pause in milliseconds.
Formats as: {pause:duration_ms}
Valid range: 500-5000ms in 100ms increments.
Returns self for chaining.
Args:
duration_ms: Pause duration in milliseconds (500-5000, increments of 100)
Returns:
Self for method chaining
Raises:
ValueError: If pause limit exceeded or validation fails
2 z&Maximum 50 pauses per request exceeded{pause:}r )validate_pauser r r r )r r! r r r r r
pauseT s
zTextBuilder.pause ssml_textc C s& t |}|r| j| | | | S )u
Parse SSML and convert to Deepgram's inline format.
Supports:
- word → pronunciation()
- → pause()
- Plain text → text()
Returns self for chaining.
Args:
ssml_text: SSML-formatted text
Returns:
Self for method chaining
)ssml_to_deepgramr r _update_counts_from_text)r r' convertedr r r
from_ssmls s
zTextBuilder.from_ssmlr Nc C sv d}t ||}| jt|7 _d}t ||}| jt|7 _t |d|}t |d|}| jt|7 _dS )z*Update internal counters from parsed text.z/\{"word":\s*"[^"]*",\s*"pronounce":\s*"[^"]*"\}z
\{pause:\d+\} N)refindallr r r subr )r r pronunciation_patternpronunciations
pause_patternpauses
clean_textr r r
r) s z$TextBuilder._update_counts_from_textc C s, d | j}| jdkrtd| j d|S )z
Return the final formatted text string.
Returns:
The complete formatted text ready for TTS
Raises:
ValueError: If character limit exceeded
r, i z,Text exceeds 2000 character limit (current: z characters))joinr r r )r resultr r r
build s
zTextBuilder.build)
__name__
__module__ __qualname____doc__r strr r intr& r+ r) r7 r r r r
r
s ! r r r r r
c C sT t |\}}|s t|tj||ddd}dt| d }tj||| dd}|S )u
Replace word in text with pronunciation control.
Args:
text: Source text containing the word
word: Word to replace
ipa: IPA pronunciation string
Returns:
Text with word replaced by {"word": "word", "pronounce":"ipa"}
Example:
text = "Take azathioprine twice daily with dupilumab injections."
text = add_pronunciation(text, "azathioprine", "ˌæzəˈθaɪəpriːn")
text = add_pronunciation(text, "dupilumab", "duːˈpɪljuːmæb")
r Fr z\br )count)r r r r r- escaper/ )r r r r r r patternr6 r r r
add_pronunciation s rA r' c C st | } d}t|| tj}|r|d} d}dd }t||| } d}dd }t||| } td d
| } | S ) u0
Convert SSML markup to Deepgram's inline JSON format.
Supports:
- word
- or
- Strips wrapper tags
Args:
ssml_text: SSML-formatted text
Returns:
Deepgram-formatted text
Example:
ssml = '''
Take azathioprine
Do not exceed dosage.
'''
text = ssml_to_deepgram(ssml)
z]*>(.*?)r zI(.*?)c S s( | d}| d}tj||dddS )Nr r Fr )groupr r )matchr r r r r
replace_phoneme s
z)ssml_to_deepgram..replace_phonemez2c S sn t | d}| d}|dkrt|d }nt|}t|\}}|s1tdtdt|d d }d| d S )
Nr rB si r d r# r$ )floatrC r= r% maxminround)rD valueunitr! r r r r r
replace_break s
z'ssml_to_deepgram..replace_breakz<[^>]+>r, )stripr- searchDOTALLrC r/ )r'
speak_pattern speak_matchphoneme_patternrE
break_patternrO r r r
r( s
r( c C sZ | sdS t | ts dS g d}|D ]}|| v r"ddt| f S qt| dkr+dS dS ) z
Validate IPA string format.
Args:
ipa: IPA pronunciation string
Returns:
Tuple of (is_valid, error_message)
)Fz!IPA pronunciation cannot be empty)Fz"IPA pronunciation must be a string)"\
Fz.IPA pronunciation contains invalid character: rH )Fz-IPA pronunciation exceeds 100 character limitTr, )
isinstancer< reprr )r
invalid_charscharr r r
r s
r r! c C s: t | tsdS | dk r
dS | dkrdS | d dkrdS d S )
z
Validate pause duration (500-5000ms, 100ms increments).
Args:
duration_ms: Pause duration in milliseconds
Returns:
Tuple of (is_valid, error_message)
)Fz!Pause duration must be an integerr )Fz%Pause duration must be at least 500msrG )Fz%Pause duration must not exceed 5000msrH r )Fz*Pause duration must be in 100ms incrementsr\ )r] r= )r! r r r
r% 6 s
r% )
r; r r- typingr r r< rA r( boolr r= r% r r r r
s # J