Merge pull request #267 from opentok/feature/support-trasnport-header-audio-connector/VIDMR-1483

[VIDMR-1483] Support for AudioTransport

Author: superchilled

opentok/opentok.py

@@ -2010,13 +2010,25 @@ def connect_audio_to_websocket(
             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.
             Boolean 'bidirectional' Optional: If true, enables bidirectional audio streaming over the WebSocket connection.
+            Dictionary 'audio_transport' Optional: Configuration for audio transport format.
+                String 'transport': The transport type ('binary' or 'json').
+                String 'encoding' Optional: The encoding type (required for 'json' transport, e.g. 'base64').
+                String 'audio_field' Optional: The JSON field name for outbound audio data.
+                String 'receive_audio_field' Optional: The JSON field name for inbound audio data.
+                Dictionary 'static_fields' Optional: Static fields included in every outbound JSON message.
         """
         self.validate_websocket_options(websocket_options)
 
+        ws_opts = dict(websocket_options)
+        if "audio_transport" in ws_opts:
+            audio_transport = ws_opts.pop("audio_transport")
+            filtered = {k: v for k, v in audio_transport.items() if v is not None}
+            ws_opts["audioTransport"] = json.dumps(filtered, separators=(',', ':'))
+
         payload = {
             "sessionId": session_id,
             "token": opentok_token,
-            "websocket": websocket_options,
+            "websocket": ws_opts,
         }
 
         logger.debug(
@@ -2065,6 +2077,18 @@ def validate_websocket_options(self, options):
             if not isinstance(options["bidirectional"], bool):
                 raise InvalidWebSocketOptionsError("'bidirectional' must be a boolean if provided.")
 
+        if "audio_transport" in options:
+            audio_transport = options["audio_transport"]
+            if not isinstance(audio_transport, dict):
+                raise InvalidWebSocketOptionsError("'audio_transport' must be a dictionary if provided.")
+            if "transport" not in audio_transport:
+                raise InvalidWebSocketOptionsError("'audio_transport' must include a 'transport' field.")
+            valid_transports = ("binary", "json")
+            if audio_transport["transport"] not in valid_transports:
+                raise InvalidWebSocketOptionsError(
+                    f"'transport' must be one of {valid_transports}."
+                )
+
     def start_captions(
         self,
         session_id: str,

tests/test_audio_connector.py

@@ -165,3 +165,145 @@ def test_connect_audio_to_websocket_missing_uri_error(self):
         with self.assertRaises(InvalidWebSocketOptionsError) as context:
             self.opentok.connect_audio_to_websocket(self.session_id, self.token, websocket_options)
         self.assertTrue("Provide a WebSocket URI." in str(context.exception))
+
+    @httpretty.activate
+    def test_connect_audio_to_websocket_with_audio_transport_json(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",
+            "audio_transport": {
+                "transport": "json",
+                "encoding": "base64",
+            },
+        }
+
+        websocket_audio_connection = self.opentok.connect_audio_to_websocket(
+            self.session_id, self.token, websocket_options
+        )
+
+        if PY3:
+            body = json.loads(httpretty.last_request().body.decode("utf-8"))
+
+        expect(body["websocket"]).to(have_key("audioTransport"))
+        expect(body["websocket"]).not_to(have_key("audio_transport"))
+        parsed = json.loads(body["websocket"]["audioTransport"])
+        expect(parsed["transport"]).to(equal("json"))
+        expect(parsed["encoding"]).to(equal("base64"))
+        expect(websocket_audio_connection).to(be_a(WebSocketAudioConnection))
+
+    @httpretty.activate
+    def test_connect_audio_to_websocket_with_audio_transport_full(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",
+            "audio_transport": {
+                "transport": "json",
+                "encoding": "base64",
+                "audio_field": "data",
+                "static_fields": {"event": "media"},
+            },
+        }
+
+        websocket_audio_connection = self.opentok.connect_audio_to_websocket(
+            self.session_id, self.token, websocket_options
+        )
+
+        if PY3:
+            body = json.loads(httpretty.last_request().body.decode("utf-8"))
+
+        parsed = json.loads(body["websocket"]["audioTransport"])
+        expect(parsed["transport"]).to(equal("json"))
+        expect(parsed["encoding"]).to(equal("base64"))
+        expect(parsed["audio_field"]).to(equal("data"))
+        expect(parsed["static_fields"]).to(equal({"event": "media"}))
+        expect(websocket_audio_connection).to(be_a(WebSocketAudioConnection))
+
+    @httpretty.activate
+    def test_connect_audio_to_websocket_with_binary_transport(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",
+            "audio_transport": {
+                "transport": "binary",
+            },
+        }
+
+        websocket_audio_connection = self.opentok.connect_audio_to_websocket(
+            self.session_id, self.token, websocket_options
+        )
+
+        if PY3:
+            body = json.loads(httpretty.last_request().body.decode("utf-8"))
+
+        expect(body["websocket"]["audioTransport"]).to(equal('{"transport":"binary"}'))
+        expect(websocket_audio_connection).to(be_a(WebSocketAudioConnection))
+
+    @httpretty.activate
+    def test_connect_audio_to_websocket_without_audio_transport(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"}
+
+        self.opentok.connect_audio_to_websocket(
+            self.session_id, self.token, websocket_options
+        )
+
+        if PY3:
+            body = json.loads(httpretty.last_request().body.decode("utf-8"))
+
+        expect(body["websocket"]).not_to(have_key("audioTransport"))
+        expect(body["websocket"]).not_to(have_key("audio_transport"))
+
+    def test_connect_audio_to_websocket_invalid_audio_transport_type(self):
+        websocket_options = {
+            "uri": "wss://service.com/ws-endpoint",
+            "audio_transport": "invalid",
+        }
+        with self.assertRaises(InvalidWebSocketOptionsError) as context:
+            self.opentok.connect_audio_to_websocket(self.session_id, self.token, websocket_options)
+        self.assertTrue("'audio_transport' must be a dictionary if provided." in str(context.exception))
+
+    def test_connect_audio_to_websocket_audio_transport_missing_transport(self):
+        websocket_options = {
+            "uri": "wss://service.com/ws-endpoint",
+            "audio_transport": {"encoding": "base64"},
+        }
+        with self.assertRaises(InvalidWebSocketOptionsError) as context:
+            self.opentok.connect_audio_to_websocket(self.session_id, self.token, websocket_options)
+        self.assertTrue("'audio_transport' must include a 'transport' field." in str(context.exception))
+
+    def test_connect_audio_to_websocket_audio_transport_invalid_transport(self):
+        websocket_options = {
+            "uri": "wss://service.com/ws-endpoint",
+            "audio_transport": {"transport": "invalid"},
+        }
+        with self.assertRaises(InvalidWebSocketOptionsError) as context:
+            self.opentok.connect_audio_to_websocket(self.session_id, self.token, websocket_options)
+        self.assertTrue("'transport' must be one of" in str(context.exception))