added audio streamer lite functionality and tests

maxkahan · maxkahan · commit a46013480dd5 · 2022-11-08T18:14:59.000Z
diff --git a/opentok/__init__.py b/opentok/__init__.py
@@ -15,3 +15,4 @@
 from .sip_call import SipCall
 from .broadcast import Broadcast, BroadcastStreamModes
 from .render import Render, RenderList
+from .webhook_audio_connection import WebhookAudioConnection
diff --git a/opentok/endpoints.py b/opentok/endpoints.py
@@ -208,3 +208,9 @@ def get_render_url(self, render_id: str = None):
             url += "/" + render_id
 
         return url
+
+    def get_audio_streamer_url(self):
+        """Returns URLs for working with the Audio Streamer (lite) API."""
+        url = self.api_url + "/v2/project/" + self.api_key + "/connect"
+        
+        return url
diff --git a/opentok/exceptions.py b/opentok/exceptions.py
@@ -116,3 +116,15 @@ class BroadcastHLSOptionsError(OpenTokException):
     
     dvr and lowLatency modes cannot both be set to true in a broadcast.
     """
+
+
+class InvalidWebsocketOptionsError(OpenTokException):
+    """
+    Indicates that the websocket options selected are invalid.
+    """
+
+
+class InvalidMediaModeError(OpenTokException):
+    """
+    Indicates that the media mode selected was not valid for the type of request made.
+    """
diff --git a/opentok/opentok.py b/opentok/opentok.py
@@ -16,7 +16,6 @@
 import random  # _create_jwt_auth_header
 import logging  # logging
 import warnings  # Native. Used for notifying deprecations
-import os
 
 
 # compat
@@ -33,6 +32,7 @@
 from .streamlist import StreamList
 from .sip_call import SipCall
 from .broadcast import Broadcast, BroadcastStreamModes
+from .webhook_audio_connection import WebhookAudioConnection
 from .exceptions import (
     ArchiveStreamModeError,
     BroadcastHLSOptionsError,
@@ -48,8 +48,9 @@
     SipDialError,
     SetStreamClassError,
     BroadcastError,
-    DTMFError
-
+    DTMFError,
+    InvalidWebsocketOptionsError,
+    InvalidMediaModeError  
 )
 
 
@@ -1653,7 +1654,7 @@ def start_render(self, session_id, opentok_token, url, max_duration=7200, resolu
        `Experience Composer developer guide <https://tokbox.com/developer/guides/experience-composer>`_.
 
         :param String 'session_id': The session ID of the OpenTok session that will include the Experience Composer stream.
-        :param String 'token': A valid OpenTok token with a Publisher role and (optionally) connection data to be associated with the output stream.
+        :param String 'opentok_token': A valid OpenTok token with a Publisher role and (optionally) connection data to be associated with the output stream.
         :param String 'url': A publically reachable URL controlled by the customer and capable of generating the content to be rendered without user intervention.
         :param Integer 'maxDuration' Optional: The maximum time allowed for the Experience Composer, in seconds. After this time, it is stopped automatically, if it is still running. The maximum value is 36000 (10 hours), the minimum value is 60 (1 minute), and the default value is 7200 (2 hours). When the Experience Composer ends, its stream is unpublished and an event is posted to the callback URL, if configured in the Account Portal.
         :param String 'resolution' Optional: The resolution of the Experience Composer, either "640x480" (SD landscape), "480x640" (SD portrait), "1280x720" (HD landscape), "720x1280" (HD portrait), "1920x1080" (FHD landscape), or "1080x1920" (FHD portrait). By default, this resolution is "1280x720" (HD landscape, the default).
@@ -1699,7 +1700,6 @@ def start_render(self, session_id, opentok_token, url, max_duration=7200, resolu
         else:
             raise RequestError("An unexpected error occurred", response.status_code)
 
-
     def get_render(self, render_id):
         """
         This method allows you to see the status of a render, which can be one of the following:
@@ -1804,6 +1804,64 @@ def list_renders(self, offset=0, count=50):
         else:
             raise RequestError("An unexpected error occurred", response.status_code)
 
+    def stream_audio_to_websocket(self, session_id: str, opentok_token: str, websocket_options: dict):
+        """
+        Connects audio streams to a specified webhook URI.
+        For more information, see the `Audio Streamer developer guide <https://tokbox.com/developer/guides/audio-streamer/>`.
+
+        :param String 'session_id': The OpenTok session ID that includes the OpenTok streams you want to include in the WebSocket stream. The Audio Streamer feature is only supported in routed sessions (sessions that use the OpenTok Media Router).
+        :param String 'opentok_token': The OpenTok token to be used for the Audio Streamer connection to the OpenTok session.
+        :param Dictionary 'websocket_options': Included options for the websocket.
+            String 'uri': A publicly reachable WebSocket URI to be used for the destination of the audio stream (such as "wss://example.com/ws-endpoint").
+            List 'streams' Optional: A list of stream IDs for the OpenTok streams you want to include in the WebSocket audio. If you omit this property, all streams in the session will be included.
+            Dictionary 'headers' Optional: An object of key-value pairs of headers to be sent to your WebSocket server with each message, with a maximum length of 512 bytes.
+        """
+        self.validate_websocket_options(websocket_options)
+        
+        payload = {
+            "sessionId": session_id,
+            "token": opentok_token,
+            "websocket": websocket_options
+        }
+
+        logger.debug(
+            "POST to %r with params %r, headers %r, proxies %r",
+            self.endpoints.get_audio_streamer_url(),
+            json.dumps(payload),
+            self.get_json_headers(),
+            self.proxies,
+        )
+
+        response = requests.post(
+            self.endpoints.get_audio_streamer_url(),
+            json=payload,
+            headers=self.get_json_headers(),
+            proxies=self.proxies,
+            timeout=self.timeout,
+        )
+
+        if response and response.status_code == 200:
+            return WebhookAudioConnection(response.json())
+        elif response.status_code == 400:
+            """
+            The HTTP response has a 400 status code in the following cases:
+            You did not pass in a session ID or you pass in an invalid session ID.
+            You specified an invalid value for input parameters.
+            """
+            raise RequestError(response.json().get("message"))
+        elif response.status_code == 403:
+            raise AuthError("You passed in an invalid OpenTok API key or JWT token.")
+        elif response.status_code == 409:
+            raise InvalidMediaModeError("Only routed sessions are allowed to initiate Audio Streamer WebSocket connections.")
+        else:
+            raise RequestError("An unexpected error occurred", response.status_code)
+
+    def validate_websocket_options(self, options):
+        if type(options) is not dict:
+            raise InvalidWebsocketOptionsError('Must pass websocket options as a dictionary.')
+        if 'uri' not in options:
+            raise InvalidWebsocketOptionsError('Provide a webhook URI.')
+
     def _sign_string(self, string, secret):
         return hmac.new(
             secret.encode("utf-8"), string.encode("utf-8"), hashlib.sha1
diff --git a/opentok/webhook_audio_connection.py b/opentok/webhook_audio_connection.py
@@ -0,0 +1,20 @@
+import json
+from six import iteritems
+
+class WebhookAudioConnection:
+    """Represents information about the audio streaming of an OpenTok session to a webhook."""
+
+    def __init__(self, kwargs):
+        self.id = kwargs.get("id")
+        self.connectionId = kwargs.get("connectionId")
+
+    def json(self):
+        """Returns a JSON representation of the webhook audio connection information."""
+        return json.dumps(self, default=lambda o: o.__dict__, sort_keys=True, indent=4)
+
+    def attrs(self):
+        """
+        Returns a dictionary of the webhook audio connection's attributes.
+        """
+        return dict((k, v) for k, v in iteritems(self.__dict__))
+        
diff --git a/tests/test_audio_streamer.py b/tests/test_audio_streamer.py
@@ -0,0 +1,152 @@
+import unittest
+import textwrap
+import httpretty
+import json
+from sure import expect
+
+from six import u, PY2, PY3
+from expects import *
+from opentok import Client, WebhookAudioConnection, __version__
+from opentok.exceptions import InvalidWebsocketOptionsError, InvalidMediaModeError
+from .validate_jwt import validate_jwt_header
+
+
+class OpenTokAudioStreamerLiteTest(unittest.TestCase):
+    def setUp(self):
+        self.api_key = u("123456")
+        self.api_secret = u("1234567890abcdef1234567890abcdef1234567890")
+        self.opentok = Client(self.api_key, self.api_secret)
+        self.session_id = u("2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4")
+        self.token = u("1234-5678-9012")
+        self.response_body = textwrap.dedent(
+            u(
+                """ \
+                    {
+                        "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
+                        "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007"
+                    }
+                """
+            )
+        )
+
+    @httpretty.activate
+    def test_stream_audio_to_websocket(self):
+        httpretty.register_uri(
+            httpretty.POST,
+            u(f"https://api.opentok.com/v2/project/{self.api_key}/connect"),
+            body=self.response_body,
+            status=200,
+            content_type=u("application/json"),
+        )
+
+        websocket_options = {
+            "uri": "wss://service.com/ws-endpoint"
+        }
+
+        webhook_audio_connection = self.opentok.stream_audio_to_websocket(self.session_id, self.token, websocket_options)
+                
+        validate_jwt_header(self, httpretty.last_request().headers[u("x-opentok-auth")])
+        expect(httpretty.last_request().headers[u("user-agent")]).to(
+            contain(u("OpenTok-Python-SDK/") + __version__)
+        )
+        expect(httpretty.last_request().headers[u("content-type")]).to(
+            equal(u("application/json"))
+        
+        )
+        # non-deterministic json encoding. have to decode to test it properly
+        if PY2:
+            body = json.loads(httpretty.last_request().body)
+        if PY3:
+            body = json.loads(httpretty.last_request().body.decode("utf-8"))
+
+        expect(body).to(have_key(u("token")))
+        expect(webhook_audio_connection).to(be_a(WebhookAudioConnection))
+        expect(webhook_audio_connection).to(
+            have_property(u("id"), u("b0a5a8c7-dc38-459f-a48d-a7f2008da853"))
+        )
+        expect(webhook_audio_connection).to(
+            have_property(u("connectionId"), u("e9f8c166-6c67-440d-994a-04fb6dfed007"))
+        )
+
+    @httpretty.activate
+    def test_stream_audio_to_websocket_custom_options(self):
+        httpretty.register_uri(
+            httpretty.POST,
+            u(f"https://api.opentok.com/v2/project/{self.api_key}/connect"),
+            body=self.response_body,
+            status=200,
+            content_type=u("application/json"),
+        )
+
+        websocket_options = {
+            "uri": "wss://service.com/ws-endpoint",
+            "streams": ["stream-id-1", "stream-id-2"],
+            "headers": {
+                "websocketHeader": "Sent via Audio Streamer API"
+            }
+        }
+
+        webhook_audio_connection = self.opentok.stream_audio_to_websocket(self.session_id, self.token, websocket_options)
+                
+        validate_jwt_header(self, httpretty.last_request().headers[u("x-opentok-auth")])
+        expect(httpretty.last_request().headers[u("user-agent")]).to(
+            contain(u("OpenTok-Python-SDK/") + __version__)
+        )
+        expect(httpretty.last_request().headers[u("content-type")]).to(
+            equal(u("application/json"))
+        
+        )
+        # non-deterministic json encoding. have to decode to test it properly
+        if PY2:
+            body = json.loads(httpretty.last_request().body)
+        if PY3:
+            body = json.loads(httpretty.last_request().body.decode("utf-8"))
+
+        expect(body).to(have_key(u("token")))
+        expect(webhook_audio_connection).to(be_a(WebhookAudioConnection))
+        expect(webhook_audio_connection).to(
+            have_property(u("id"), u("b0a5a8c7-dc38-459f-a48d-a7f2008da853"))
+        )
+        expect(webhook_audio_connection).to(
+            have_property(u("connectionId"), u("e9f8c166-6c67-440d-994a-04fb6dfed007"))
+        )
+
+    @httpretty.activate
+    def test_stream_audio_to_websocket_media_mode_error(self):
+        httpretty.register_uri(
+            httpretty.POST,
+            u(f"https://api.opentok.com/v2/project/{self.api_key}/connect"),
+            body={},
+            status=409,
+            content_type=u("application/json"),
+        )
+
+        websocket_options = {
+            "uri": "wss://service.com/ws-endpoint"
+        }
+
+        session_id = "session-where-mediaMode=relayed-was-selected"
+
+        with self.assertRaises(InvalidMediaModeError) as context:
+            self.opentok.stream_audio_to_websocket(session_id, self.token, websocket_options)
+        self.assertTrue("Only routed sessions are allowed to initiate Audio Streamer WebSocket connections." in str(context.exception))
+                
+        validate_jwt_header(self, httpretty.last_request().headers[u("x-opentok-auth")])
+        expect(httpretty.last_request().headers[u("user-agent")]).to(
+            contain(u("OpenTok-Python-SDK/") + __version__)
+        )
+        expect(httpretty.last_request().headers[u("content-type")]).to(
+            equal(u("application/json"))
+        )
+
+    def test_stream_audio_to_websocket_invalid_options_type_error(self):
+        websocket_options = "wss://service.com/ws-endpoint"
+        with self.assertRaises(InvalidWebsocketOptionsError) as context:
+            self.opentok.stream_audio_to_websocket(self.session_id, self.token, websocket_options)
+        self.assertTrue("Must pass websocket options as a dictionary." in str(context.exception))
+    
+    def test_stream_audio_to_websocket_missing_uri_error(self):
+        websocket_options = {}
+        with self.assertRaises(InvalidWebsocketOptionsError) as context:
+            self.opentok.stream_audio_to_websocket(self.session_id, self.token, websocket_options)
+        self.assertTrue("Provide a webhook URI." in str(context.exception))
