PyRadio Text-to-Speech Support

Overview

PyRadio features comprehensive Text-to-Speech (TTS) support, providing intelligent auditory feedback for an enhanced radio streaming experience. This advanced system delivers contextual information with priority-based management, supporting multiple platforms and extensive configuration options.

Table of Contents

• Features
• Activation
  • Permanent Activation
  • Temporary Activation
• Platform Implementation
  • Linux
  • Windows
  • macOS
• Speech Control
  • Speech Context
  • Speech Priorities
• Language Support
  • Voice Characteristics
  • Platform-Specific Strategy
• Technical Features
  • Smart Queue Management
  • Intelligent Behavior
  • Volume Change Announcements
• Usage Guidelines
  • For English-Dominant Users
  • For Multi-Language Content
• Configuration Options
  • Basic Settings
  • Speech Characteristics
• Current Status & Roadmap
  • Current Implementation
  • Configuration Window Behavior
  • Planned Enhancements for Future Versions

[ Return to main doc ]

Features

The TTS system provides spoken feedback for:

• Station Navigation: Station names and numbers during browsing
• Playback Status: Connection establishment, playback start/stop
• Media Metadata: Song titles and artist information from stream metadata
• System Events: Connection errors, volume changes, status alerts
• Volume Adjustment Feedback: Optional debounced announcements during volume changes
• Dialog Interaction: Menu items, help text, configuration options

Activation

Permanent Activation

Enable TTS permanently through the configuration menu: Config → TTS → Enable TTS

This setting is saved in your configuration file and persists across sessions.

Temporary Activation

Toggle TTS during runtime by pressing \T (backslash + T). This setting is session-only and resets when restarting PyRadio.

Platform Implementation

Linux

Utilizes speech-dispatcher configured for English language by default. Provides robust, interruptible speech synthesis with priority-based queue management.

Windows

Leverages Windows SAPI (Speech API) with automatic selection of English voices when available. Features immediate speech interruption and consistent volume control.

macOS

Employs the native say command using the system's default voice. Most macOS voices support multiple languages natively, handling mixed-language content seamlessly.

Speech Control

Speech Context

Control how much speech feedback you receive:

• limited: Essential information only (system messages, errors, station data)
• window: Extended feedback (includes window text and interface elements)
• all: Comprehensive feedback (speaks all available text and information)

Speech Priorities

The system intelligently manages speech priorities:

• Critical information (errors, alerts) receives immediate attention
• Navigation feedback can be interrupted for rapid browsing
• Song titles are preserved and spoken after important announcements

Language Support

Voice Characteristics

TTS voices generally fall into two categories:

Monolingual Voices (typical on Linux/Windows):

• Specialized in one language
• System messages sound clear in English
• Non-English characters may be mispronounced or skipped entirely

Multilingual Voices (common on macOS):

• Automatic language detection and switching
• Handle mixed-language content naturally
• Provide authentic pronunciation for both system messages and station names

Platform-Specific Strategy

• Linux: English-configured for consistent system messaging
• Windows: Auto-selects English voices while respecting system preferences
• macOS: Uses default system voice - typically multilingual by design

Technical Features

Smart Queue Management

• Priority-based processing
• Pending title queuing after high-priority interruptions
• Volume adjustment debouncing
• Platform-optimized anti-stutter protection

Intelligent Behavior

• Critical alerts receive immediate priority
• Song titles are queued and spoken after high-priority interruptions
• Rapid navigation triggers queue optimization

Volume Change Announcements

When enabled, PyRadio provides spoken feedback for volume adjustments using a debounce mechanism.

A "volume change session" begins with the first volume modification and ends after no further changes occur within the configured delay period. At the end of the session, the system announces:

"Volume set to XX%"

The debounce delay (300–3000 ms) prevents repetitive announcements while rapidly adjusting the volume.

Optionally, an additional start notification:

"Volume change initiated"

can be enabled to indicate the beginning of a volume adjustment session.

Typical values: 300–500 ms for responsive feedback.

Usage Guidelines

For English-Dominant Users

• Default configuration works optimally
• System messages and international station names sound natural

For Multi-Language Content

• macOS: Handles mixed content seamlessly with multilingual voices
• Windows/Linux: Non-English characters in station names may not be pronounced correctly
• Consider using English names for frequently-accessed stations

Configuration Options

Basic Settings

Setting	Values	Default	Description
enable_tts	True/False	False	Master switch for TTS functionality
tts_context	limited/window/all	all	Controls how much information is spoken
tts_volume	0-100	50	Speech volume (Linux/Windows only)
tts_rate	-100 to 100	0	Speech speed (negative=slower, positive=faster)
tts_pitch	-100 to 100	0	Voice pitch adjustment
tts_verbosity	default/punctuation	default	Controls how punctuation is spoken
tts_speak_volume_change	0, 300 to 3000	0	Enables announcements during volume changes
tts_speak_volume_shange_start	True / False	False	Enables "Volume change initiated" announcement

Speech Characteristics

• Volume: Adjustable on Linux and Windows (macOS uses system volume)
• Rate: Controls speech speed across all platforms
• Pitch: Alters voice pitch (platform-dependent implementation)
• Verbosity:
  • default: Punctuation is interpreted naturally
  • punctuation: Punctuation is spoken literally (e.g., "read-only" becomes "read dash only")

Current Status & Roadmap

Current Implementation

The TTS support in PyRadio is continuously evolving. Currently, TTS is available for:

• Main station selection window
• Playback status and notifications
• Station navigation and browsing
• Volume adjustment feedback
• Basic configuration menus

Configuration Window Behavior

To assist users in configuring the program, special rules apply when using the Configuration windows, provided the TTS system is already enabled:

1. Full TTS Access: When navigating through the Configuration menus and windows (including all sub-windows), the TTS system operates at its fullest capacity, temporarily overriding the tts_context setting to provide complete auditory feedback about all interface elements.

2. Voice Sample: While in the TTS configuration group, pressing "T" (uppercase) will speak a voice sample using the current TTS settings, allowing you to preview how your configuration sounds.

3. Detailed Help: In all configuration windows (currently implemented in the "Keyboard Shortcuts" window), pressing "t" (lowercase) provides additional spoken information about the current setting being configured.

This special behavior ensures that all users can effectively configure the program to their preferences, regardless of their current TTS context settings.

Planned Enhancements for Future Versions

• Extended TTS support for all program windows and dialogs
• Enhanced context-aware speech patterns
• More granular control over speech feedback
• Implementation of the detailed help feature (lowercase t) across all configuration windows

Note: The TTS system is designed to be unobtrusive yet informative. If you encounter issues with speech feedback or have suggestions for improvement, please report them via the PyRadio issue tracker.