How to use Application.Speech in the xlwings API way

The Speech member of the Application object in Excel’s object model provides access to text-to-speech functionality, allowing developers to programmatically control speech playback of cell contents. This can be particularly useful for accessibility features, data verification by auditory feedback, or creating interactive tutorials. In xlwings, this functionality is exposed through the api property, which grants direct access to the underlying Excel VBA object model, enabling the use of the Speech object’s methods and properties.

Functionality:
The Speech object primarily controls the speech engine’s behavior, including speaking cell contents, managing speech playback (like pausing or resuming), and adjusting speech properties such as direction (by rows or columns) and speaking order. It allows for dynamic auditory output from spreadsheet data.

Syntax and Parameters:
In xlwings, the Speech member is accessed via app.api.Speech, where app is an instance of xlwings.App. Key methods include:

• Speak(text, speakAsync, speakXML, purge): Speaks the specified text.
• text: A string representing the text to be spoken.
• speakAsync: A boolean; True for asynchronous speech (allows code to continue running), False for synchronous (code waits until speech finishes).
• speakXML: A boolean; if True, interprets text as XML for speech synthesis control.
• purge: A boolean; if True, purges any pending speech before speaking.
• Properties like SpeakCellOnEnter: A boolean property that controls whether Excel speaks the cell contents when the Enter key is pressed. It can be set or retrieved.

Code Examples:
Here are practical examples using xlwings to demonstrate the Speech functionality:

1. Speak a Specific Text Asynchronously:

import xlwings as xw
app = xw.App(visible=True)
# Speak "Hello from Excel" without blocking code execution
app.api.Speech.Speak("Hello from Excel", speakAsync=True)
app.quit()

2. Enable Speaking Cell on Enter:

import xlwings as xw
app = xw.App(visible=True)
workbook = app.books.open('example.xlsx')
# Turn on speech when Enter is pressed in cells
app.api.Speech.SpeakCellOnEnter = True
# Now, when a user presses Enter after editing a cell, its content will be spoken
workbook.save()
app.quit()

3. Speak Cell Contents Programmatically:

import xlwings as xw
app = xw.App(visible=True)
workbook = app.books.open('data.xlsx')
sheet = workbook.sheets['Sheet1']
# Get the value from cell A1 and speak it synchronously
cell_value = sheet.range('A1').value
app.api.Speech.Speak(str(cell_value), speakAsync=False)
app.quit()