Merge pull request #285 from dvonthenen/prerecorded-callback-example

Fix for `transcribe_url_callback` and `transcribe_file_callback` with Example

Author: davidvonthenen

deepgram/clients/prerecorded/v1/async_client.py

@@ -57,7 +57,7 @@ async def transcribe_url(
         if options is not None and options.callback is not None:
             self.logger.debug("PreRecordedClient.transcribe_url LEAVE")
             return await self.transcribe_url_callback(
-                source, options["callback"], options, addons, timeout, endpoint
+                source, options.callback, options, addons, timeout, endpoint
             )
 
         url = f"{self.config.url}/{endpoint}"
@@ -120,7 +120,7 @@ async def transcribe_url_callback(
         url = f"{self.config.url}/{endpoint}"
         if options is None:
             options = {}
-        options["callback"] = callback
+        options.callback = callback
         if is_url_source(source):
             body = source
         else:
@@ -178,7 +178,7 @@ async def transcribe_file(
         if options is not None and options.callback is not None:
             self.logger.debug("PreRecordedClient.transcribe_file LEAVE")
             return await self.transcribe_file_callback(
-                source, options["callback"], options, addons, timeout, endpoint
+                source, options.callback, options, addons, timeout, endpoint
             )
 
         url = f"{self.config.url}/{endpoint}"
@@ -242,7 +242,7 @@ async def transcribe_file_callback(
         url = f"{self.config.url}/{endpoint}"
         if options is None:
             options = {}
-        options["callback"] = callback
+        options.callback = callback
         if is_buffer_source(source):
             body = source["buffer"]
         elif is_readstream_source(source):
@@ -264,7 +264,7 @@ async def transcribe_file_callback(
         self.logger.info("options: %s", options)
         self.logger.info("addons: %s", addons)
         result = await self.post(
-            url, options=options, addons=addons, json=body, timeout=timeout
+            url, options=options, addons=addons, content=body, timeout=timeout
         )
         self.logger.info("json: %s", result)
         res = AsyncPrerecordedResponse.from_json(result)

deepgram/clients/prerecorded/v1/client.py

@@ -57,7 +57,7 @@ def transcribe_url(
         if options is not None and options.callback is not None:
             self.logger.debug("PreRecordedClient.transcribe_url LEAVE")
             return self.transcribe_url_callback(
-                source, options["callback"], options, addons, timeout, endpoint
+                source, options.callback, options, addons, timeout, endpoint
             )
 
         url = f"{self.config.url}/{endpoint}"
@@ -120,7 +120,7 @@ def transcribe_url_callback(
         url = f"{self.config.url}/{endpoint}"
         if options is None:
             options = {}
-        options["callback"] = callback
+        options.callback = callback
         if is_url_source(source):
             body = source
         else:
@@ -178,7 +178,7 @@ def transcribe_file(
         if options is not None and options.callback is not None:
             self.logger.debug("PreRecordedClient.transcribe_file LEAVE")
             return self.transcribe_file_callback(
-                source, options["callback"], options, addons, timeout, endpoint
+                source, options.callback, options, addons, timeout, endpoint
             )
 
         url = f"{self.config.url}/{endpoint}"
@@ -242,7 +242,7 @@ def transcribe_file_callback(
         url = f"{self.config.url}/{endpoint}"
         if options is None:
             options = {}
-        options["callback"] = callback
+        options.callback = callback
         if is_buffer_source(source):
             body = source["buffer"]
         elif is_readstream_source(source):
@@ -264,7 +264,7 @@ def transcribe_file_callback(
         self.logger.info("options: %s", options)
         self.logger.info("addons: %s", addons)
         result = self.post(
-            url, options=options, addons=addons, json=body, timeout=timeout
+            url, options=options, addons=addons, content=body, timeout=timeout
         )
         self.logger.info("json: %s", result)
         res = AsyncPrerecordedResponse.from_json(result)

examples/prerecorded/callback/README.md

@@ -0,0 +1,37 @@
+# Callback Example
+
+This example shows how to use the [Callback](https://developers.deepgram.com/docs/callback) functionality on the Prerecorded API.
+
+> **_NOTE:_** To use this example, the `endpoint` component must run somewhere with a public-facing IP address. You cannot run this example locally behind your typical firewall.
+
+## Configuration
+
+This example consists of two components:
+- `endpoint`: which is an example of what a callback endpoint would look like. Reminder: this requires running with a public-facing IP address
+- `callback`: which is just a Deepgram client posts a PreRecorded transcription request using a local audio file preamble.wav (or using an audio file at a hosted URL, like [https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav](https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav).
+
+The `callback` component requires the Deepgram API Key environment variable to be configured to run.
+
+```sh
+export DEEPGRAM_API_KEY=YOUR-APP-KEY-HERE
+```
+
+### Prerequisites: Public-facing Endpoint
+
+This example requires that the Deepgram platform be able to reach your `endpoint` which means the IP address must be publically hosted. This could be an EC2 instance on AWS, an instance on GCP, etc. Another option is using [ngrok](https://ngrok.com/).
+
+`ngrok` brief overview: run ngrok http 8080 which opens up the local host port 8080, and gives a public URL https://e00a-42-156-98-177.ngrok-free.app/ (for example). Then in another terminal, run nc -l 8080 to listen on port 8080 for incoming messages. The `CALL_BACK_URL` should then be set to `https://e00a-42-156-98-177.ngrok-free.app`.
+
+## Installation
+
+Run the `endpoint` application using an SSL certificate to a system on the public-facing internet.
+
+On the `callback` project, modify the IP address constant in the code with the public-facing IP address of your EC2, GCP, etc instance.
+
+```Python
+CALL_BACK_URL = (
+    "https://127.0.0.1:8000"  # TODO: MUST REPLACE WITH YOUR OWN CALLBACK ENDPOINT
+)
+```
+
+Then run the `callback` application. This can be done from your local laptop.

examples/prerecorded/callback/callback/main.py

@@ -0,0 +1,67 @@
+# Copyright 2023 Deepgram SDK contributors. All Rights Reserved.
+# Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+# SPDX-License-Identifier: MIT
+
+import os
+from dotenv import load_dotenv
+import logging, verboselogs
+from datetime import datetime, timedelta
+
+from deepgram import (
+    DeepgramClient,
+    DeepgramClientOptions,
+    PrerecordedOptions,
+    FileSource,
+    UrlSource,
+)
+
+load_dotenv()
+
+AUDIO_FILE = "preamble.wav"
+CALL_BACK_URL = (
+    "https://127.0.0.1:8000"  # TODO: MUST REPLACE WITH YOUR OWN CALLBACK ENDPOINT
+)
+
+
+def main():
+    try:
+        # STEP 1 Create a Deepgram client using the API key in the environment variables
+        config = DeepgramClientOptions(
+            verbose=logging.SPAM,
+        )
+
+        deepgram = DeepgramClient("", config)
+
+        # STEP 2 Call the transcribe_file method on the prerecorded class
+        with open(AUDIO_FILE, "rb") as file:
+            buffer_data = file.read()
+
+        payload: FileSource = {
+            "buffer": buffer_data,
+        }
+        # For URL hosted audio files, comment out the above and uncomment the below
+        # payload: UrlSource = {
+        #     "url": "https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav"
+        # }
+
+        options = PrerecordedOptions(
+            model="nova-2",
+            smart_format=True,
+            utterances=True,
+        )
+
+        response = deepgram.listen.prerecorded.v("1").transcribe_file_callback(
+            payload, CALL_BACK_URL, options=options
+        )
+        # For URL hosted audio files, comment out the above and uncomment the below
+        # response = deepgram.listen.prerecorded.v("1").transcribe_url_callback(
+        #     payload, CALL_BACK_URL, options=options
+        # )
+        print(response.to_json(indent=4))
+
+    except Exception as e:
+        print(f"Exception: {e}")
+
+
+if __name__ == "__main__":
+    main()

examples/prerecorded/callback/callback/preamble.wav

@@ -0,0 +1,22 @@
+-----BEGIN CERTIFICATE-----
+MIIDoDCCAogCCQCtyWzcpdOQUDANBgkqhkiG9w0BAQUFADCBkTELMAkGA1UEBhMC
+VVMxCzAJBgNVBAgMAkNBMRMwEQYDVQQHDApMb25nIEJlYWNoMREwDwYDVQQKDAhT
+eW1ibC5haTEbMBkGA1UECwwSRGV2ZWxvcGVyIEFkdm9jYWN5MRIwEAYDVQQDDAkx
+MjcuMC4wLjExHDAaBgkqhkiG9w0BCQEWDXNwYW1Ac3ltYmwuYWkwHhcNMjIxMTIx
+MTYyOTM3WhcNMjMxMTIxMTYyOTM3WjCBkTELMAkGA1UEBhMCVVMxCzAJBgNVBAgM
+AkNBMRMwEQYDVQQHDApMb25nIEJlYWNoMREwDwYDVQQKDAhTeW1ibC5haTEbMBkG
+A1UECwwSRGV2ZWxvcGVyIEFkdm9jYWN5MRIwEAYDVQQDDAkxMjcuMC4wLjExHDAa
+BgkqhkiG9w0BCQEWDXNwYW1Ac3ltYmwuYWkwggEiMA0GCSqGSIb3DQEBAQUAA4IB
+DwAwggEKAoIBAQCv6xZu8caNs847YIVVsjE7odfcyFKsrIkXsUDyImkLNNLBCSQ8
+xMrNiVo4OoKwcpqGR1NsSoblFYoruE41gA5R2nbILIbNeu5Sq+Kqljtuci7kDog1
+OX8yliEVkSECJZ7uGGb811p8R9BDsZqUXk/gZTKknbYFon6fQkvbmucSBHHA98TC
+s3WhP/F7zCVwK1u3oX67TjfmN+RXkXwlC2FjnDjoc8TWRHtnV9Nv71i0ss5Ep6GB
+G6iwsM86C+bEhQYzGbT/oZexeP+1NuKBhhtXfvlo5aXP1RRfCGsCE5UcxVXE7Cid
+UGK0XQ9cHFgW8/axbP+WFWvbyqpE2hSFpZ3zAgMBAAEwDQYJKoZIhvcNAQEFBQAD
+ggEBAEsKMNI16CzuuM8dcLbzsxu490AEqlwbzCnEUqqEbe0m3z9rz3HTG6KV6ejc
+2ABl0MtSxGeW4K6Vb0+AC61NXa0snnDVFHNd8McsVvSSpnwvVll8S7oCjFviDzu3
+FYDlhqI8c7SNJNjC5FL4fV0P7IwR8cN3wn0hfd3dKzxvTVvU5AWA3S33M494ewrt
+HZE1CTX6Al+hghjSXOrpd1yvD1UBlYvnASHh+whRlAN2V9IpZEo9IpQB12sj97lZ
+Lw+O53Ysn1PR0WuTdjgmtc3m//6QrHQOxcOLxl8Jyi0uXclFv8Oy0VmUbZe18MzA
+n70mi+NaDxTrsFCL9goHUjc6uhw=
+-----END CERTIFICATE-----

examples/prerecorded/callback/endpoint/localhost.crt

@@ -0,0 +1,18 @@
+-----BEGIN CERTIFICATE REQUEST-----
+MIIC1zCCAb8CAQAwgZExCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTETMBEGA1UE
+BwwKTG9uZyBCZWFjaDERMA8GA1UECgwIU3ltYmwuYWkxGzAZBgNVBAsMEkRldmVs
+b3BlciBBZHZvY2FjeTESMBAGA1UEAwwJMTI3LjAuMC4xMRwwGgYJKoZIhvcNAQkB
+Fg1zcGFtQHN5bWJsLmFpMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
+r+sWbvHGjbPOO2CFVbIxO6HX3MhSrKyJF7FA8iJpCzTSwQkkPMTKzYlaODqCsHKa
+hkdTbEqG5RWKK7hONYAOUdp2yCyGzXruUqviqpY7bnIu5A6INTl/MpYhFZEhAiWe
+7hhm/NdafEfQQ7GalF5P4GUypJ22BaJ+n0JL25rnEgRxwPfEwrN1oT/xe8wlcCtb
+t6F+u0435jfkV5F8JQthY5w46HPE1kR7Z1fTb+9YtLLORKehgRuosLDPOgvmxIUG
+Mxm0/6GXsXj/tTbigYYbV375aOWlz9UUXwhrAhOVHMVVxOwonVBitF0PXBxYFvP2
+sWz/lhVr28qqRNoUhaWd8wIDAQABoAAwDQYJKoZIhvcNAQELBQADggEBAIB+1Lcx
+ywJvr3DQc3gkSNDZp5sR9hK65wjwt2dhzgbSBsbGPPyf0q54QCc9UPz37XSp/xkl
+vU1T12SMK53JIXwizoj47BM51hhrfIs0Ky6msrL2+FyAPBTQpYbVLg3AvqFZUejl
+Gj2kcG3nvTMtex3ktoHwOAfdvVhqWYqGomkQseVep6mAx/8soJycohtT6K255tyN
+IyMkNO8KZA+R8jVSjFIbMM5YG3dBqj//s0+Qb49dN/TybRmUAeuMQEnk737vzz63
+1w/58UGpshqBOwf4/jz1nESxXvDOgGu8ygMbaBe/uEI68szTGGXl4FZvRy3nHDsz
+Nn5k5SNMwaAQkW0=
+-----END CERTIFICATE REQUEST-----

examples/prerecorded/callback/endpoint/localhost.csr

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCv6xZu8caNs847
+YIVVsjE7odfcyFKsrIkXsUDyImkLNNLBCSQ8xMrNiVo4OoKwcpqGR1NsSoblFYor
+uE41gA5R2nbILIbNeu5Sq+Kqljtuci7kDog1OX8yliEVkSECJZ7uGGb811p8R9BD
+sZqUXk/gZTKknbYFon6fQkvbmucSBHHA98TCs3WhP/F7zCVwK1u3oX67TjfmN+RX
+kXwlC2FjnDjoc8TWRHtnV9Nv71i0ss5Ep6GBG6iwsM86C+bEhQYzGbT/oZexeP+1
+NuKBhhtXfvlo5aXP1RRfCGsCE5UcxVXE7CidUGK0XQ9cHFgW8/axbP+WFWvbyqpE
+2hSFpZ3zAgMBAAECggEAAkdoXf2R1eobZNeGQqrxSlV5Z2nM8GG30O/B6KEbfUKs
+7EVDC+p8uhbqbUoMwV5qtAyefwukHbmetZxInxbOmK7c1REGmgjap4WEhTM3B+JA
+y0GI8C+Tf0NEoHPl2pJEMc9tHh9oE64We5oEZ6GlJUIKWumUHxSQ0V1ZgDnMfoY8
+ttl/NpShMF9lz67GnaMcGNwrXr2a/oKEXUdAuOZKyS9vP80WLWAYzLGSBa2FEMmJ
+tumLb8EEQpWRPOPTwylPAJcV/67FjH/g4DCA8NgyevI2/lH/ZHlp0UYC5vLqzN8Z
+zN4MalYC+6ZWZSM//gyhxvXZ3j+WNUERSv+ndTk+YQKBgQDabhzExPgpzgtnQpg5
+hnJpcGmxdp6ajFz70AI1sU6rWisAItwF8g6xHIH4TkHhhn3oyJ4Xtzt7jOaT011t
+IVmks2uNoONjO4yFmLvkQORn4opvkdya+gm68acceb3jdKI663MmfLLUXKaHVpwN
+zP0kzWuKD++kCtHMphqK3LKXMQKBgQDOLRmzE8pxNtXNvgBFCqwPiSxGNZ3nfi+t
+MIhW/YhW6RypeTQ/NFWzIzklO79VUQCUidRdEmh21XGisDxMtnIw+5VAKliE40Aw
+hGTxLn+HsQ1IPxD3/3bVJkU2Htpxfo4/WClRnZ9E3wD++6hayGtDY6peRrBY5plq
+t31dXyoGYwKBgQCPEAevqQKQ/u7hFvD03GYbQRE4tmRy/PP5yedom1TXThtT34EU
+M9IDlpRZuYfU2m2lBaDmD5DZ/xMWRx2t2GYKRalv/axw1hPXfI2zlf0DPZFGOdav
+eozc8GFveR0x2LZYuNWWo53NEVHQ2p0jPNugOxrwNjfSzXNUAobn5FzkQQKBgDPc
+alt+PezucydWhLDZN2CNC6L5d6e0OP/idlkTWwkph/klMLw5SNlPod84wS8Pugqj
+BNUIfVhu5i+bDv/o4J5rmiZSwINkuk+57b4xCQkzwviKTJVlIBoLj1tGtYHY6KUM
+YxBRiq+DPLfmy3lScpC38DHYrCEgmDScxR8IggSrAoGBAJldUpe90FsKz26Eef6s
+ZTbWRT9BB3GQc4IhtWr23RmOGEiORRglHtHRIzaBose23ZTjCa/A9hkF6p+vtqBf
+RUzmHCNtK7n5yQMhqJPiLLhVlyzApsUwtlNPvjIOn7a6wbHu5U/1nrYDlOicSATx
+QgUzTpG/aebRgw9E35figb4p
+-----END PRIVATE KEY-----

examples/prerecorded/callback/endpoint/localhost.key

@@ -0,0 +1,30 @@
+from http.server import HTTPServer, BaseHTTPRequestHandler
+import ssl
+from io import BytesIO
+
+
+class SimpleHTTPRequestHandler(BaseHTTPRequestHandler):
+    def do_POST(self):
+        content_length = int(self.headers["Content-Length"])
+        body = self.rfile.read(content_length)
+        print("\n\n")
+        print(f"body: {body}")
+        print("\n\n")
+        self.send_response(200)
+        self.end_headers()
+
+
+def main():
+    context = ssl.SSLContext()
+    context.load_cert_chain("localhost.crt", "localhost.key")
+
+    httpd = HTTPServer(("localhost", 8000), SimpleHTTPRequestHandler)
+    httpd.socket = context.wrap_socket(
+        httpd.socket,
+        server_side=True,
+    )
+    httpd.serve_forever()
+
+
+if __name__ == "__main__":
+    main()