PyObjC Speech Framework

Warnings

• breaking PyObjC 12.0 dropped support for Python 3.9. PyObjC 11.0 dropped support for Python 3.8. Users must use newer Python versions to install and run these PyObjC releases.
  Fix: Upgrade to Python 3.10 or newer (Python 3.13 is supported by recent PyObjC releases, with experimental free-threading).
• gotcha Using the macOS Speech framework (and many other macOS frameworks) requires explicit user permissions (e.g., microphone access, speech recognition). Your application must request these permissions, and users must grant them.
  Fix: Implement `SFSpeechRecognizer.requestAuthorization_` and handle its callback. Crucially, ensure your app's `Info.plist` (for bundled apps) includes `NSSpeechRecognitionUsageDescription` and `NSMicrophoneUsageDescription` keys with descriptive strings.
• breaking PyObjC 12.0 introduced a significant change by splitting the `AVFAudio` bindings into their own top-level package, instead of being merged into `AVFoundation`. While `pyobjc-framework-speech` imports directly from `Speech`, projects using multiple PyObjC bindings, especially those involving audio, might be affected.
  Fix: Update imports from `AVFoundation` to `AVFAudio` for specific audio components. Ensure `pyobjc-framework-AVFoundation` is installed if you need the `AVFAudio` components (it is included in that distribution).
• gotcha PyObjC 11.1 aligned its core bridge behavior with clang's Automatic Reference Counting (ARC) documentation for initializer methods. This means methods in the 'init' family now correctly steal a reference to self and return a new one, which might change memory management expectations for advanced users interacting directly with Objective-C object lifecycles.
  Fix: Review memory management patterns, especially around object creation and initialization, for code interacting deeply with Objective-C objects via `alloc().init()` and similar patterns.
• gotcha Speech recognition with `SFSpeechRecognizer` is an inherently asynchronous process using delegates and callbacks, which is different from typical synchronous Python APIs. Proper handling often requires running within a Cocoa event loop.
  Fix: Familiarize yourself with Cocoa's delegate pattern. For command-line tools or scripts, consider using `PyObjCTools.AppHelper.runConsoleEventLoop()` to ensure callbacks are processed and permission dialogs are handled correctly.

Install

• pip install pyobjc-framework-speech Install latest version

Imports

• SFSpeechRecognizer

  from Speech import SFSpeechRecognizer

• SFSpeechRecognitionRequest

  from Speech import SFSpeechRecognitionRequest

• SFSpeechRecognizerAuthorizationStatusAuthorized

  from Speech import SFSpeechRecognizerAuthorizationStatusAuthorized

• NSLocale

  from Foundation import NSLocale

Quickstart

Checks the authorization status for speech recognition, requests it if not determined, and then initializes an `SFSpeechRecognizer` to check its availability and supported locales. Note that a full PyObjC application typically runs within an event loop to handle UI interactions and asynchronous callbacks properly. Running this script directly will trigger the permission dialog, but a `PyObjCTools.AppHelper.runConsoleEventLoop` might be needed for the callback to be fully processed if the script exits too quickly.

import objc
from Foundation import NSLog, NSLocale
from Speech import SFSpeechRecognizer, SFSpeechRecognizerAuthorizationStatusAuthorized, SFSpeechRecognizerAuthorizationStatusNotDetermined

def check_speech_recognizer_availability():
    # Check authorization status
    status = SFSpeechRecognizer.authorizationStatus()
    if status == SFSpeechRecognizerAuthorizationStatusNotDetermined:
        NSLog("Speech recognition authorization status: Not Determined. Requesting access...")
        # This will present a permission dialog to the user. The callback will be invoked.
        # In a full app, you'd handle the response asynchronously.
        SFSpeechRecognizer.requestAuthorization_(lambda new_status: NSLog(f"New authorization status: {new_status}"))
    elif status != SFSpeechRecognizerAuthorizationStatusAuthorized:
        NSLog(f"Speech recognition authorization denied or restricted: {status}")
        return

    # Create a recognizer for the default locale
    recognizer = SFSpeechRecognizer.alloc().init()
    if recognizer:
        NSLog(f"SFSpeechRecognizer available: {recognizer.isAvailable()}")
        NSLog(f"Supported locales: {[locale.localeIdentifier() for locale in recognizer.supportedLocales()]}")
    else:
        NSLog("Failed to create SFSpeechRecognizer. Ensure device supports speech recognition.")

if __name__ == "__main__":
    # For permission requests to fully process and callbacks to fire reliably in a script,
    # a Cocoa event loop is often necessary.
    check_speech_recognizer_availability()
    # For interactive scripts, uncomment the following lines to run a small event loop:
    # from PyObjCTools import AppHelper
    # AppHelper.runConsoleEventLoop(installInterrupt=True)