openwakeword silent API incompatibility on Python 3.13+ and documentation issues

[JavideuS]

Description

On Python 3.13+, openwakeword 0.6.0 cannot be installed because tflite-runtime has no wheels for Python 3.13. pip silently falls back to 0.4.0, which has a completely different API than what RealtimeSTT's code expects. This causes a cascade of confusing errors with no clear explanation for the user.

Related issues

This appears to be the root cause of #266, #291.

Errors encountered (in order)

1. AttributeError: module 'openwakeword.utils' has no attribute 'download_models'
->this method doesn't exist in 0.4.0

2. TypeError: AudioFeatures.__init__() got an unexpected keyword argument 'wakeword_models'
->correct parameter in 0.4.0 is wakeword_model_paths

3. TypeError: AudioFeatures.__init__() got an unexpected keyword argument 'inference_framework'
-> this parameter does not exists in 0.4.0

Environment

• Python 3.13 / 3.14
• RealtimeSTT 0.3.104
• openwakeword installed: 0.4.0 (0.6.0 blocked by tflite-runtime)

Root cause

setup.py declares openwakeword>=0.4.0 but the code in audio_recorder.py uses APIs only available in 0.6.0+. The version floor should be raised to >=0.6.0 to fail loudly rather than silently install an incompatible version.

Suggested fix

In setup.py / pyproject.toml, change:

openwakeword>=0.4.0

to:

openwakeword>=0.6.0

This won't fix Python 3.13+ support entirely (tflite-runtime is still unavailable), but it will produce a clear installation error instead of a runtime crash with misleading tracebacks. Full Python 3.13+ support would require either a tflite-free code path or waiting for tflite-runtime to publish 3.13 wheels.

README inaccuracies

The documentation adds to the confusion in two ways:

1. wake_words is documented as optional for openwakeword backend, but it is required
The README states:

"For the 'openwakeword' backend, wake words are automatically extracted from the provided
model files, so specifying them here is not necessary."

In practice, the init code has:

elif wake_words and self.wakeword_backend in {'oww', 'openwakeword', 'openwakewords'}:

If wake_words is empty, the entire openwakeword initialization block is skipped and owwModel is never set, causing a runtime crash.

2. Wake word name mismatch
The README lists jarvis as a supported wake word, which is correct for pvporcupine. However, the equivalent openwakeword built-in model is hey_jarvis, which is not documented anywhere. This is particularly relevant since pvporcupine is no longer free, making openwakeword the primary free alternative, yet its wake word names are undocumented.