docs: improve TTS extension guide with WebSocket patterns and config passthrough#314
Open
docs: improve TTS extension guide with WebSocket patterns and config passthrough#314
Conversation
…sthrough, graph wiring
add complete serial WebSocket client and extension examples based on
production deepgram_tts implementation. add critical patterns section
covering finish_request(), _finalize_request(), TTFB measurement,
invalid text handling, cancel/reconnect, and audio_start ordering.
add params passthrough pattern showing update_params() convention used
by all TTS extensions. add voice-assistant graph wiring section.
fix config examples to use Field(default_factory=dict) and dict[str, Any].
replace fictional test config filenames with real property_*.json layout.
add InvalidStatus handling to WebSocket _connect() example.
fix graph schema to use "graph": {"nodes": ..., "connections": ...}.
replace generic RuntimeError with VendorTTSConnectionException that preserves HTTP status code, enabling the extension to distinguish 401 (FATAL_ERROR) from transient failures (NON_FATAL_ERROR). add connection error handling in request_tts() showing the mapping. remove fictional property.json from test configs tree — the guarder tests use property_basic_audio_setting1.json as their default config. add inline descriptions showing which guarder tests use each file.
4 tasks
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
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.
Summary
finish_request(),_finalize_request(), TTFB measurement, invalid text handling, cancel/reconnect, audio_start orderingupdate_params()convention used by all TTS extensions)Fixes
params = {}defaults withField(default_factory=dict)Dict[str, Optional[str]]todict[str, Any]property_*.jsonlayoutInvalidStatushandling to WebSocket_connect()example"graph": {"nodes": ..., "connections": ...}Context
These gaps were identified while building the deepgram_tts extension (TEN-framework/ten-framework#2131). The existing guide covered HTTP mode well but left significant blind spots for WebSocket implementations — particularly around
finish_request()(forgetting it hangs the queue), TTFB measurement, invalid text handling for guarder tests, and config params forwarding.Test plan
ten_ai_baseAPI