docs(samples): More STT v2 samples (#10443)

* docs(samples): More STT v2 samples

Added samples for:
* Enabling CMEK
* BatchRecognize (GCS output, inline output, dynamic batching, multiple files)
* Multiple languages recognition
* Various recognizer features

Author: nitsanshai

speech/snippets/create_recognizer.py

@@ -27,7 +27,11 @@ def create_recognizer(project_id: str, recognizer_id: str) -> cloud_speech.Recog
     request = cloud_speech.CreateRecognizerRequest(
         parent=f"projects/{project_id}/locations/global",
         recognizer_id=recognizer_id,
-        recognizer=cloud_speech.Recognizer(language_codes=["en-US"], model="long"),
+        recognizer=cloud_speech.Recognizer(
+            default_recognition_config=cloud_speech.RecognitionConfig(
+                language_codes=["en-US"], model="long"
+            ),
+        ),
     )
 
     operation = client.create_recognizer(request=request)

speech/snippets/create_recognizer_test.py

@@ -31,10 +31,19 @@ def delete_recognizer(name: str) -> None:
 
 
 @Retry()
-def test_create_recognizer(capsys: pytest.CaptureFixture) -> None:
+def test_create_recognizer(
+    capsys: pytest.CaptureFixture, request: pytest.FixtureRequest
+) -> None:
     project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
+    recognizer_id = "recognizer-" + str(uuid4())
 
-    recognizer = create_recognizer.create_recognizer(
-        project_id, "recognizer-" + str(uuid4())
-    )
-    delete_recognizer(recognizer.name)
+    def cleanup():
+        delete_recognizer(
+            f"projects/{project_id}/locations/global/recognizers/{recognizer_id}"
+        )
+
+    request.addfinalizer(cleanup)
+
+    recognizer = create_recognizer.create_recognizer(project_id, recognizer_id)
+
+    assert recognizer_id in recognizer.name

speech/snippets/enable_cmek.py

@@ -0,0 +1,57 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import argparse
+
+# [START speech_enable_cmek]
+from google.cloud.speech_v2 import SpeechClient
+from google.cloud.speech_v2.types import cloud_speech
+
+
+def enable_cmek(
+    project_id: str,
+    kms_key_name: str,
+) -> cloud_speech.RecognizeResponse:
+    """Enable CMEK in a project and region."""
+    # Instantiates a client
+    client = SpeechClient()
+
+    request = cloud_speech.UpdateConfigRequest(
+        config=cloud_speech.Config(
+            name=f"projects/{project_id}/locations/global/config",
+            kms_key_name=kms_key_name,
+        ),
+        update_mask={"paths": ["kms_key_name"]},
+    )
+
+    # Updates the KMS key for the project and region.
+    response = client.update_config(request=request)
+
+    print(f"Updated KMS key: {response.kms_key_name}")
+
+    return response
+
+
+# [END speech_enable_cmek]
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("project_id", help="GCP Project ID")
+    parser.add_argument("kms_key_name", help="Resource path of a KMS key")
+    args = parser.parse_args()
+    enable_cmek(args.project_id, args.kms_key_name)

speech/snippets/enable_cmek_test.py

@@ -0,0 +1,31 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+from google.api_core.retry import Retry
+
+import enable_cmek
+
+
+@Retry()
+def test_enable_cmek() -> None:
+    project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
+
+    response = enable_cmek.enable_cmek(
+        project_id,
+        "",
+    )
+
+    assert response.kms_key_name == ""

speech/snippets/transcribe_batch_dynamic_batching_v2.py

@@ -0,0 +1,79 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import argparse
+
+# [START speech_transcribe_batch_dynamic_batching_v2]
+from google.cloud.speech_v2 import SpeechClient
+from google.cloud.speech_v2.types import cloud_speech
+
+
+def transcribe_batch_dynamic_batching_v2(
+    project_id: str,
+    gcs_uri: str,
+) -> cloud_speech.BatchRecognizeResults:
+    """Transcribes audio from a Google Cloud Storage URI.
+
+    Args:
+        project_id: The Google Cloud project ID.
+        gcs_uri: The Google Cloud Storage URI.
+
+    Returns:
+        The RecognizeResponse.
+    """
+    # Instantiates a client
+    client = SpeechClient()
+
+    config = cloud_speech.RecognitionConfig(
+        auto_decoding_config=cloud_speech.AutoDetectDecodingConfig(),
+        language_codes=["en-US"],
+        model="long",
+    )
+
+    file_metadata = cloud_speech.BatchRecognizeFileMetadata(uri=gcs_uri)
+
+    request = cloud_speech.BatchRecognizeRequest(
+        recognizer=f"projects/{project_id}/locations/global/recognizers/_",
+        config=config,
+        files=[file_metadata],
+        recognition_output_config=cloud_speech.RecognitionOutputConfig(
+            inline_response_config=cloud_speech.InlineOutputConfig(),
+        ),
+        processing_strategy=cloud_speech.BatchRecognizeRequest.ProcessingStrategy.DYNAMIC_BATCHING,
+    )
+
+    # Transcribes the audio into text
+    operation = client.batch_recognize(request=request)
+
+    print("Waiting for operation to complete...")
+    response = operation.result(timeout=120)
+
+    for result in response.results[gcs_uri].transcript.results:
+        print(f"Transcript: {result.alternatives[0].transcript}")
+
+    return response.results[gcs_uri].transcript
+
+
+# [END speech_transcribe_batch_dynamic_batching_v2]
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("project_id", help="GCP Project ID")
+    parser.add_argument("gcs_uri", help="URI to GCS file")
+    args = parser.parse_args()
+    transcribe_batch_dynamic_batching_v2(args.project_id, args.gcs_uri)

speech/snippets/transcribe_batch_dynamic_batching_v2_test.py

@@ -0,0 +1,44 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import re
+
+from flaky import flaky
+
+import pytest
+
+import transcribe_batch_dynamic_batching_v2
+
+
+_TEST_AUDIO_FILE_PATH = "gs://cloud-samples-data/speech/audio.flac"
+
+
+@flaky(max_runs=10, min_passes=1)
+def test_transcribe_batch_dynamic_batching_v2(
+    capsys: pytest.CaptureFixture,
+) -> None:
+    project_id = os.getenv("GOOGLE_CLOUD_PROJECT")
+
+    response = (
+        transcribe_batch_dynamic_batching_v2.transcribe_batch_dynamic_batching_v2(
+            project_id, _TEST_AUDIO_FILE_PATH
+        )
+    )
+
+    assert re.search(
+        r"how old is the Brooklyn Bridge",
+        response.results[0].alternatives[0].transcript,
+        re.DOTALL | re.I,
+    )

speech/snippets/transcribe_batch_gcs_input_gcs_output_v2.py

@@ -0,0 +1,108 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import argparse
+
+# [START speech_transcribe_batch_gcs_input_gcs_output_v2]
+import re
+
+from google.cloud import storage
+from google.cloud.speech_v2 import SpeechClient
+from google.cloud.speech_v2.types import cloud_speech
+
+
+def transcribe_batch_gcs_input_gcs_output_v2(
+    project_id: str,
+    gcs_uri: str,
+    gcs_output_path: str,
+) -> cloud_speech.BatchRecognizeResults:
+    """Transcribes audio from a Google Cloud Storage URI.
+
+    Args:
+        project_id: The Google Cloud project ID.
+        gcs_uri: The Google Cloud Storage URI.
+        gcs_output_path: The Cloud Storage URI to which to write the transcript.
+
+    Returns:
+        The BatchRecognizeResults message.
+    """
+    # Instantiates a client
+    client = SpeechClient()
+
+    config = cloud_speech.RecognitionConfig(
+        auto_decoding_config=cloud_speech.AutoDetectDecodingConfig(),
+        language_codes=["en-US"],
+        model="long",
+    )
+
+    file_metadata = cloud_speech.BatchRecognizeFileMetadata(uri=gcs_uri)
+
+    request = cloud_speech.BatchRecognizeRequest(
+        recognizer=f"projects/{project_id}/locations/global/recognizers/_",
+        config=config,
+        files=[file_metadata],
+        recognition_output_config=cloud_speech.RecognitionOutputConfig(
+            gcs_output_config=cloud_speech.GcsOutputConfig(
+                uri=gcs_output_path,
+            ),
+        ),
+    )
+
+    # Transcribes the audio into text
+    operation = client.batch_recognize(request=request)
+
+    print("Waiting for operation to complete...")
+    response = operation.result(timeout=120)
+
+    file_results = response.results[gcs_uri]
+
+    print(f"Operation finished. Fetching results from {file_results.uri}...")
+    output_bucket, output_object = re.match(
+        r"gs://([^/]+)/(.*)", file_results.uri
+    ).group(1, 2)
+
+    # Instantiates a Cloud Storage client
+    storage_client = storage.Client()
+
+    # Fetch results from Cloud Storage
+    bucket = storage_client.bucket(output_bucket)
+    blob = bucket.blob(output_object)
+    results_bytes = blob.download_as_bytes()
+    batch_recognize_results = cloud_speech.BatchRecognizeResults.from_json(
+        results_bytes, ignore_unknown_fields=True
+    )
+
+    for result in batch_recognize_results.results:
+        print(f"Transcript: {result.alternatives[0].transcript}")
+
+    return batch_recognize_results
+
+
+# [END speech_transcribe_batch_gcs_input_gcs_output_v2]
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("project_id", help="GCP Project ID")
+    parser.add_argument("gcs_uri", help="URI to GCS file")
+    parser.add_argument(
+        "gcs_output_path", help="GCS URI to which to write the transcript"
+    )
+    args = parser.parse_args()
+    transcribe_batch_gcs_input_gcs_output_v2(
+        args.project_id, args.gcs_uri, args.gcs_output_path
+    )