Skip to content

python_readme.md

Latest commit

 

History

History
363 lines (239 loc) · 8.37 KB

python_readme.md

File metadata and controls

363 lines (239 loc) · 8.37 KB
Raw

SpeechCore API Documentation

Overview

SpeechCore is a cross-platform Python wrapper for screen reader and text-to-speech functionality. It provides a unified interface for speech synthesis, voice control, and braille output across different operating systems. The library supports multiple speech drivers and includes Windows-specific SAPI (Speech API) functionality.

Installation

pip install speechcore

Classes

SpeechCore

Main class for speech synthesis and screen reader functionality. Only one instance may exist at a time.

Context Manager Support: Can be used with with statement for automatic initialization and cleanup.

with SpeechCore() as speech:
    speech.output("Hello, world!")

Sapi

Windows-only class providing direct access to Microsoft's Speech API (SAPI). Only available on Windows platforms.

Context Manager Support: Can be used with with statement for automatic initialization and cleanup.

# Windows only
with Sapi() as sapi:
    sapi.speak("Hello from SAPI!")

SpeechCore Methods

Initialization and Management

SpeechCore.init()

Initialize the SpeechCore library.

  • Returns: None
  • Raises: InitializationError if initialization fails

SpeechCore.free()

Free resources and shutdown the library.

  • Returns: None

SpeechCore.is_loaded() -> bool

Check if SpeechCore is currently loaded and initialized.

  • Returns: bool - True if loaded, False otherwise

Driver Management

detect_driver() -> None

Automatically detect and set the best available speech driver.

  • Returns: None

get_driver(index: int) -> str

Get the name of a speech driver by index.

  • Parameters:
    • index (int): Driver index
  • Returns: str - Driver name

current_driver() -> str

Get the name of the currently active speech driver.

  • Returns: str - Current driver name

set_driver(index: int) -> None

Set the active speech driver by index.

  • Parameters:
    • index (int): Driver index to activate
  • Returns: None

get_drivers() -> int

Get the total number of available speech drivers.

  • Returns: int - Number of available drivers

Voice Management

get_voice(index: int) -> str

Get the name of a voice by index.

  • Parameters:
    • index (int): Voice index
  • Returns: str - Voice name

get_current_voice() -> str

Get the name of the currently active voice.

  • Returns: str - Current voice name

set_voice(index: int) -> None

Set the active voice by index.

  • Parameters:
    • index (int): Voice index to activate
  • Returns: None

get_voices() -> int

Get the total number of available voices.

  • Returns: int - Number of available voices

Audio Control

set_volume(offset: float) -> None

Set the speech volume level.

  • Parameters:
    • offset (float): Volume level (typically 0.0 to 1.0)
  • Returns: None

get_volume() -> float

Get the current speech volume level.

  • Returns: float - Current volume level

set_rate(offset: float) -> None

Set the speech rate (speed).

  • Parameters:
    • offset (float): Speech rate value
  • Returns: None

get_rate() -> float

Get the current speech rate.

  • Returns: float - Current speech rate

Speech Output

output(text: str, interrupt: bool = False) -> bool

Speak the given text.

  • Parameters:
    • text (str): Text to speak
    • interrupt (bool): Whether to interrupt current speech (default: False)
  • Returns: bool - True if successful

output_braille(text: str) -> bool

Output text to braille display.

  • Parameters:
    • text (str): Text to output to braille
  • Returns: bool - True if successful

output_file(filename: str, text: str) -> None

Save speech output to an audio file.

  • Parameters:
    • filename (str): Output file path
    • text (str): Text to convert to audio
  • Returns: None

Playback Control

resume() -> None

Resume paused speech.

  • Returns: None

pause() -> None

Pause current speech.

  • Returns: None

stop() -> None

Stop current speech immediately.

  • Returns: None

is_speaking() -> bool

Check if speech is currently active.

  • Returns: bool - True if speaking, False otherwise

System Information

get_speech_flags() -> int

Get current speech system capability flags.

  • Returns: int - Bitfield of capability flags

check_speech_flags(flags: int) -> bool

Check if specific speech flags are set.

  • Parameters:
    • flags (int): Flags to check
  • Returns: bool - True if flags are set

Sapi Methods (Windows Only)

Initialization

Sapi.init()

Initialize the SAPI interface.

  • Returns: None
  • Raises: InitializationError if initialization fails
  • Raises: NotImplementedError on non-Windows platforms

Sapi.release()

Release SAPI resources.

  • Returns: None

Sapi.sapi_loaded() -> bool

Check if SAPI is currently loaded.

  • Returns: bool - True if loaded, False otherwise

Voice Control

voice_set_rate(offset: float) -> None

Set SAPI voice speech rate.

  • Parameters:
    • offset (float): Speech rate value
  • Returns: None

voice_get_rate() -> float

Get current SAPI voice speech rate.

  • Returns: float - Current speech rate

voice_set_volume(offset: float) -> None

Set SAPI voice volume level.

  • Parameters:
    • offset (float): Volume level
  • Returns: None

voice_get_volume() -> float

Get current SAPI voice volume level.

  • Returns: float - Current volume level

get_voice(index: int) -> str

Get SAPI voice name by index.

  • Parameters:
    • index (int): Voice index
  • Returns: str - Voice name

get_current_voice() -> str

Get current SAPI voice name.

  • Returns: str - Current voice name

set_voice_by_index(index: int) -> None

Set SAPI voice by index.

  • Parameters:
    • index (int): Voice index
  • Returns: None

set_voice(voice_name: str) -> None

Set SAPI voice by name.

  • Parameters:
    • voice_name (str): Name of voice to set
  • Returns: None

get_voices() -> int

Get number of available SAPI voices.

  • Returns: int - Number of voices

SAPI Speech Output

speak(text: str, interrupt: bool = False, xml: bool = False) -> None

Speak text using SAPI.

  • Parameters:
    • text (str): Text to speak
    • interrupt (bool): Whether to interrupt current speech (default: False)
    • xml (bool): Whether text contains SSML markup (default: False)
  • Returns: None

output_file(filename: str, text: str, xml: bool = False) -> None

Save SAPI speech to audio file.

  • Parameters:
    • filename (str): Output file path
    • text (str): Text to convert
    • xml (bool): Whether text contains SSML markup (default: False)
  • Returns: None

SAPI Playback Control

resume() -> None

Resume paused SAPI speech.

  • Returns: None

pause() -> None

Pause current SAPI speech.

  • Returns: None

stop() -> None

Stop current SAPI speech.

  • Returns: None

Constants

Speech capability flags available from __speech_common:

  • SC_SPEECH_FLOW_CONTROL - Speech flow control support
  • SC_SPEECH_PARAMETER_CONTROL - Speech parameter control support
  • SC_VOICE_CONFIG - Voice configuration support
  • SC_FILE_OUTPUT - File output support
  • SC_HAS_SPEECH - Speech synthesis support
  • SC_HAS_BRAILLE - Braille output support
  • SC_HAS_SPEECH_STATE - Speech state monitoring support

Exceptions

InitializationError

Raised when SpeechCore or SAPI initialization fails.

NotLoadedError

Raised when attempting to use methods before proper initialization.

Example Usage

from speechcore import SpeechCore

# Basic usage with context manager
with SpeechCore() as speech:
    speech.output("Hello, this is SpeechCore!")
    
    # Check available voices
    voice_count = speech.get_voices()
    for i in range(voice_count):
        print(f"Voice {i}: {speech.get_voice(i)}")
    
    # Adjust speech parameters
    speech.set_rate(0.5)  # Slower speech
    speech.set_volume(0.8)  # Lower volume
    
    speech.output("This is slower and quieter speech.")

# Windows-specific SAPI usage
if sys.platform == "win32":
    from speechcore import Sapi
    
    with Sapi() as sapi:
        sapi.speak("Hello from Windows SAPI!")