Add mute feature (#197)

* Adding the ObserveForceMute flag

* Removed 3.5 from the build and fixed extra space in opentok.py

* Add SIP Outbound video flag and Play DTMF API

* Change wording in docstring for force mute

* Made changes to the mute function and added a test

- Updated the mute functionality with the active flag, excludedStream and excludedStreamIds

- Added a new test in test_opentok.py

* Changed Force Mute function

- Split the ForceMute into two functions: mute_all and mute_stream
- added return statements for the urls in the endpoints.py file
- added a new test for the single stream

* Docs edits

* Updated mute all and mute stream

- Removed options from mute_all
- Removed body from mute_stream

Co-authored-by: Paul Ardeleanu <[email protected]>
Co-authored-by: Jeff Swartz <[email protected]>

Author: 3 people

opentok/endpoints.py

@@ -130,6 +130,7 @@ def get_broadcast_url(self, broadcast_id=None, stop=False, layout=False):
             url = url + "/stop"
         if layout:
             url = url + "/layout"
+            
         return url
 
     def get_mute_all_url(self, session_id):
@@ -144,6 +145,8 @@ def get_mute_all_url(self, session_id):
 
         )
 
+        return url
+
     def get_dtmf_all_url(self, session_id):
         """ this method returns the url for Play DTMF to all clients in the session """
         url = (
@@ -155,6 +158,8 @@ def get_dtmf_all_url(self, session_id):
             + "/play-dtmf"
         )
 
+        return url
+
     def get_dtmf_specific_url(self, session_id, connection_id):
         """ this method returns the url for Play DTMF to a specific client connection"""
         url = (
@@ -168,6 +173,8 @@ def get_dtmf_specific_url(self, session_id, connection_id):
             + "/play-dtmf"
         )
 
+        return url
+
     def get_archive_stream(self, archive_id=None):
         """ this method returns urls for working with streamModes in archives """
         url = (
@@ -179,6 +186,8 @@ def get_archive_stream(self, archive_id=None):
             + "/streams"
         )
 
+        return url
+
     def get_broadcast_stream(self, broadcast_id=None):
         """ this method returns urls for working with streamModes in broadcasts """
         url = (
@@ -189,3 +198,5 @@ def get_broadcast_stream(self, broadcast_id=None):
             + broadcast_id
             + "/streams"
         )
+
+        return url

opentok/opentok.py

@@ -1,4 +1,5 @@
 from datetime import datetime  # generate_token
+from typing import List, Optional # imports List, Optional type hint
 import calendar  # generate_token
 import base64  # generate_token
 import random  # generate_token
@@ -1152,6 +1153,7 @@ def dial(self, session_id, token, sip_uri, options=[]):
                     }
                 }
 
+
         :rtype: A SipCall object, which contains data of the SIP call: id, connectionId and streamId. 
         This is what the response body should look like after returning with a status code of 200:
 
@@ -1639,46 +1641,82 @@ def __init__(
             app_version=app_version
         )
 
+    def mute_all(self, 
+                session_id: str, 
+                excludedStreamIds: Optional[List[str]], 
+                active: bool= True) -> requests.Response:
 
-
-    def mute(self, session_id: str, stream_id: str= "", options: dict = {}) -> requests.Response:
         """
-        Use this method so the moderator can mute all streams or a specific stream for OpenTok.
-        Please note that a client is able to unmute themselves.
-        This function stays in the OpenTok class and inherits from the Client class.
+        Mutes all streams in an OpenTok session.
+
+        You can include an optional list of streams IDs to exclude from being muted. 
+
+        :param session_id The session ID
 
-        :param session_id gets the session id from another function called get_session()
+        :param excludedStreamIds A list of stream IDs for streams that should not be muted. 
+        This is an optional property. If you omit this property, all streams in the session will be muted.
 
-        :param stream_id gets the stream id from another function called get_stream(). Note
-        that this variable is set to an empty string in the function definition as a specific
-        stream may not be chosen.
-   
+        :param active Whether streams published after the call, in addition to the current streams
+        in the session, should be muted (True) or not (False).
         """
-        
+
+        options = {}
+        url = self.endpoints.get_mute_all_url(session_id)
+
         try:
-            if not stream_id:
-                url = self.endpoints.get_mute_all_url(session_id)
-                data = {'excludedStream': stream_id}
+            if excludedStreamIds:
+                if active:
+                    options = {'active': active, 'excludedStreams': excludedStreamIds }
             else:
-                url = self.endpoints.get_stream_url(session_id, stream_id) + "/mute"
-                data = None
-            
-            
-            response = requests.post(url, headers=self.get_headers(), data=data)
+                active = False
+                options = {'active': active, 'excludedStreams': []}
+  
+            response = requests.post(url, headers=self.get_headers(), data=json.dumps(options))
 
             if response:
                 return response
             elif response.status_code == 400:
                 raise GetStreamError("Invalid request. This response may indicate that data in your request data is invalid JSON. Or it may indicate that you do not pass in a session ID or you passed in an invalid stream ID.")
             elif response.status_code == 403:
-                raise AuthError("Failed to create session, invalid credentials")
+                raise AuthError("Failed to mute, invalid credentials.")
+            elif response.status_code == 404:
+                raise NotFoundError("The session or a stream is not found.")
+        except Exception as e:
+            raise OpenTokException(
+                ("There was an error thrown by the OpenTok SDK, please check that your session_id {0} and excludedStreamIds (if exists) {1} are valid").format(
+                    session_id, excludedStreamIds))
+
+        
+
+    def mute_stream(self, session_id: str, stream_id: str) -> requests.Response:
+        """
+        Mutes a single stream in an OpenTok session.
+
+        :param session_id The session ID.
+
+        :param stream_id The stream iD.
+        """
+
+        try:
+            if stream_id:
+                url = self.endpoints.get_stream_url(session_id, stream_id) + "/mute"
+
+            response = requests.post(url, headers=self.get_headers())
+
+            if response:
+                    return response
+            elif response.status_code == 400:
+                raise GetStreamError("Invalid request. This response may indicate that data in your request data is invalid JSON. Or it may indicate that you do not pass in a session ID or you passed in an invalid stream ID.")
+            elif response.status_code == 403:
+                raise AuthError("Failed to mute, invalid credentials.")
             elif response.status_code == 404:
                 raise NotFoundError("Mute not found")
         except Exception as e:
             raise OpenTokException(
-                ("There was an error thrown by the OpenTok SDK, please check that your session_id {0} and stream_id (if exists) {1} are valid").format(
+                ("There was an error thrown by the OpenTok SDK, please check that your session_id {0} and stream_id {1} are valid").format(
                     session_id, stream_id))
 
+
     def play_dtmf(self, session_id: str, connection_id: str, digits: str, options: dict = {}) -> requests.Response:
         """
         Plays a DTMF string into a session or to a specific connection

tests/test_opentok.py

@@ -28,16 +28,18 @@ def setUp(self):
         self.jwt_token_string = ''.join(random.choice(token[:100]))
         self.stream_id_1 = "Stream1"
 
+   
+
     @httpretty.activate
-    def test_mute_all_response(self):
+    def test_mute_all_exclude_streams(self):
         self.url = "https://api.opentok.com/v2/project/{0}/session/{1}/mute".format(
                                                                                 self.api_key, 
                                                                                 self.session_id)
 
         httpretty.register_uri(httpretty.POST, 
                                         self.url, 
                                         responses=[
-                                            httpretty.Response(body="Testing text matches inside of the JSON file", 
+                                            httpretty.Response(body='{"active": True, "excludedStreams": "excludedStreamIds1"}', 
                                                                content_type="application/json",
                                                                adding_headers= {"x-opentok-auth": self.jwt_token_string},
                                                                status=201)
@@ -46,11 +48,34 @@ def test_mute_all_response(self):
 
         response = requests.post(self.url)
 
-        response.status_code.should.equal(201)
-        response.text.should.equal("Testing text matches inside of the JSON file")
+        response.text.should.equal('{"active": True, "excludedStreams": "excludedStreamIds1"}')
+        response.headers["x-opentok-auth"].should.equal(self.jwt_token_string)
+        response.headers["Content-Type"].should.equal("application/json")
+
+    @httpretty.activate
+    def test_mute_single_stream(self):
+        self.url = "https://api.opentok.com/v2/project/{0}/session/{1}/stream/{2}/mute".format(
+                                                                                self.api_key, 
+                                                                                self.session_id,
+                                                                                self.stream_id_1)
+
+        httpretty.register_uri(httpretty.POST, 
+                                        self.url, 
+                                        responses=[
+                                            httpretty.Response(body='{"session_id": "12345", "stream_id": "abcde"}', 
+                                                               content_type="application/json",
+                                                               adding_headers= {"x-opentok-auth": self.jwt_token_string},
+                                                               status=201)
+                                        ])
+
+    
+        response = requests.post(self.url)
+
+        response.text.should.equal('{"session_id": "12345", "stream_id": "abcde"}')
         response.headers["x-opentok-auth"].should.equal(self.jwt_token_string)
         response.headers["Content-Type"].should.equal("application/json")
 
+
     @httpretty.activate
     def test_mute_stream_response(self):
         self.url = "https://api.opentok.com/v2/project/${0}/session/${1}/stream/${2}/mute".format(