Add verbose parameter to recognize_vosk()

reference/library-reference.rst

@@ -280,8 +280,8 @@ Returns the most likely transcription if ``show_all`` is false (the default). Ot
 
 Raises a ``speech_recognition.UnknownValueError`` exception if the speech is unintelligible. Raises a ``speech_recognition.RequestError`` exception if the speech recognition operation failed, if the key isn't valid, or if there is no internet connection.
 
-``recognizer_instance.recognize_vosk(audio_data: AudioData)``
---------------------------------------------------------------
+``recognizer_instance.recognize_vosk(audio_data: AudioData, *, verbose: bool = False) -> Union[str, Dict[str, Any]]``
+------------------------------------------------------------------------------------------------------------------------------
 
 .. autofunction:: speech_recognition.recognizers.vosk.recognize
 

speech_recognition/recognizers/vosk.py

@@ -1,17 +1,39 @@
 from __future__ import annotations
 
+import json
 import os
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal, TypedDict, Union, cast, overload
 
 if TYPE_CHECKING:
     from speech_recognition.audio import AudioData
 
 
-def recognize(recognizer, audio_data: AudioData) -> str:
+class VoskResponse(TypedDict):
+    text: str
+
+
+@overload
+def recognize(
+    recognizer, audio_data: AudioData, *, verbose: Literal[False]
+) -> str: ...
+
+
+@overload
+def recognize(
+    recognizer, audio_data: AudioData, *, verbose: Literal[True]
+) -> VoskResponse: ...
+
+
+def recognize(
+    recognizer, audio_data: AudioData, *, verbose: bool = False
+) -> Union[str, VoskResponse]:
     """
     Perform speech recognition on ``audio_data`` using Vosk.
 
     Requires the Vosk model to be downloaded and unpacked in a folder named 'model' (``$PWD/model``).
+
+    If ``verbose`` is ``False`` (default), only the recognized text is returned.
+    If ``verbose`` is ``True``, the parsed result dictionary from Vosk is returned.
     """
 
     from vosk import KaldiRecognizer, Model
@@ -25,6 +47,10 @@ def recognize(recognizer, audio_data: AudioData) -> str:
     rec.AcceptWaveform(
         audio_data.get_raw_data(convert_rate=SAMPLE_RATE, convert_width=2)
     )
-    finalRecognition = rec.FinalResult()
+    final_recognition: str = rec.FinalResult()
+
+    result = cast(VoskResponse, json.loads(final_recognition))
+    if verbose:
+        return result
 
-    return finalRecognition
+    return result["text"]

tests/recognizers/test_vosk.py

@@ -1,18 +1,25 @@
 from pathlib import Path
 
+import pytest
+
 from speech_recognition import AudioData, Recognizer
 
 
-def test_recognize_vosk():
+@pytest.fixture
+def audio_data() -> AudioData:
     audio_file = str(Path(__file__).parent.parent / "english.wav")
-    audio_data = AudioData.from_file(audio_file)
-    sut = Recognizer()
+    return AudioData.from_file(audio_file)
+
+
+def test_recognize_vosk(audio_data):
+    recognizer = Recognizer()
+    actual = recognizer.recognize_vosk(audio_data)
+
+    assert actual == "one two three"
+
 
-    actual = sut.recognize_vosk(audio_data)
+def test_recognize_vosk_verbose(audio_data):
+    recognizer = Recognizer()
+    actual = recognizer.recognize_vosk(audio_data, verbose=True)
 
-    expected = """\
-{
-  "text" : "one two three"
-}\
-"""
-    assert actual == expected
+    assert actual == {"text": "one two three"}