Merge pull request #199 from opentok/add_mute_feature

Modify mute_all function and add function to disable force mute

Author: superchilled

opentok/opentok.py

@@ -407,7 +407,7 @@ def create_session(
                 proxies=self.proxies,
                 timeout=self.timeout,
             )
-           
+
             response.encoding = "utf-8"
 
             if response.status_code == 403:
@@ -754,13 +754,13 @@ def list_archives(self, offset=None, count=None, session_id=None):
         return self.get_archives(offset, count, session_id)
 
     def add_archive_stream(
-        self, 
+        self,
         archive_id: str,
         stream_id: str,
         has_audio: bool = True,
-        has_video: bool = True    
+        has_video: bool = True
         ) -> requests.Response:
-        
+
         """
         This method will add streams to the archive with addStream for new participant(choosing audio, video or both).
 
@@ -1120,16 +1120,15 @@ def dial(self, session_id, token, sip_uri, options=[]):
                 }
 
             Boolean 'secure': A Boolean flag that indicates whether the media must be transmitted
-            encrypted (true) or not (false, the default)
+            encrypted (true) or not (False, the default)
 
-            Boolean 'observeForceMute': A Boolean flag that determines whether the SIP endpoint should 
-            honor the force mute action. The force mute action allows a moderator to force clients to 
-            mute audio in streams they publish. It defaults to False if moderator does not want to observe 
-            force mute a stream and set to True if the moderator wants to observe force mute a stream.
+            Boolean 'observeForceMute': Whether the SIP endpoint should honor a force mute action
+            (True) or not (False, the default). A force mute action allows a moderator to force clients to
+            mute audio in streams they publish.
 
-            Boolean 'video': A Boolean flag that indicates whether the SIP call will include video(true)
-            or not(false, which is the default). With video included, the SIP client's video is included 
-            in the OpenTok stream that is sent to the OpenTok session. The SIP client will receive a single 
+            Boolean 'video': Whether the SIP call will include video (true)
+            or not (False, the default). With video included, the SIP client's video is included
+            in the OpenTok stream that is sent to the OpenTok session. The SIP client will receive a single
             composed video of the published streams in the OpenTok session.
 
             This is an example of what the payload POST data body could look like:
@@ -1154,7 +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. 
+        :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:
 
         {
@@ -1184,7 +1183,7 @@ def dial(self, session_id, token, sip_uri, options=[]):
         if "observeForceMute" in options:
             observeForceMute = True
             payload["sip"]["observeForceMute"] = options["observeForceMute"]
-        
+
         if "video" in options:
             video = True
             payload["sip"]["video"] = options["video"]
@@ -1382,7 +1381,7 @@ def stop_broadcast(self, broadcast_id):
             self.json_headers(),
             self.proxies,
         )
-    
+
         response = requests.post(
             endpoint,
             headers=self.get_json_headers(),
@@ -1408,13 +1407,13 @@ def stop_broadcast(self, broadcast_id):
             raise RequestError("OpenTok server error.", response.status_code)
 
     def add_broadcast_stream(
-        self, 
+        self,
         broadcast_id: str,
         stream_id: str,
         has_audio: bool = True,
-        has_video: bool = True    
+        has_video: bool = True
         ) -> requests.Response:
-        
+
         """
         This method will add streams to the broadcast with addStream for new participant(choosing audio, video or both).
 
@@ -1462,7 +1461,7 @@ def add_broadcast_stream(
         else:
             raise RequestError("OpenTok server error.", response.status_code)
 
-    
+
     def remove_broadcast_stream(self, broadcast_id: str, stream_id: str) -> requests.Response:
         """
         This method will remove streams from the broadcast with removeStream.
@@ -1616,8 +1615,8 @@ def _create_jwt_auth_header(self):
         }
 
         return jwt.encode(payload, self.api_secret, algorithm="HS256")
-                
-  
+
+
 
 class OpenTok(Client):
     def __init__(
@@ -1641,36 +1640,34 @@ def __init__(
             app_version=app_version
         )
 
-    def mute_all(self, 
-                session_id: str, 
-                excludedStreamIds: Optional[List[str]], 
-                active: bool= True) -> requests.Response:
+    def mute_all(self,
+                session_id: str,
+                excludedStreamIds: Optional[List[str]]) -> requests.Response:
 
         """
         Mutes all streams in an OpenTok session.
 
-        You can include an optional list of streams IDs to exclude from being muted. 
+        You can include an optional list of streams IDs to exclude from being muted.
+
+        In addition to existing streams, any streams that are published after the call to
+        this method are published with audio muted. You can remove the mute state of a session
+        by calling the OpenTok.disableForceMute() method.
 
         :param session_id The session ID
 
-        :param excludedStreamIds A list of stream IDs for streams that should not be muted. 
+        :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 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 excludedStreamIds:
-                if active:
-                    options = {'active': active, 'excludedStreams': excludedStreamIds }
+                options = {'active': True, 'excludedStreams': excludedStreamIds }
             else:
-                active = False
-                options = {'active': active, 'excludedStreams': []}
-  
+                options = {'active': True, 'excludedStreams': []}
+
             response = requests.post(url, headers=self.get_headers(), data=json.dumps(options))
 
             if response:
@@ -1686,15 +1683,48 @@ def mute_all(self,
                 ("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 disable_force_mute(self, session_id: str) -> requests.Response:
+        """
+        Disables the active mute state of the session. After you call this method, new streams
+        published to the session will no longer have audio muted.
+
+        After you call the mute_all() method, any streams published after
+        the call are published with audio muted. Call the OpenTok.disable_force_mute() method
+        to remove the mute state of a session, so that new published streams are not
+        automatically muted.
+
+        :param session_id The session ID.
+        """
+
+        options = {'active': False}
+        url = self.endpoints.get_mute_all_url(session_id)
+
+        response = requests.post(url, headers=self.get_headers(), data=json.dumps(options))
+
+
+        try:
+            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("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} is valid").format(
+                    session_id))
+
 
     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.
+        :param stream_id The stream ID.
         """
 
         try:
@@ -1754,4 +1784,3 @@ def play_dtmf(self, session_id: str, connection_id: str, digits: str, options: d
         except Exception as e:
             raise OpenTokException(
                 (f"There was an error thrown by the OpenTok SDK, please check that your session_id: {session_id}, connection_id (if exists): {connection_id} and digits: {digits} are valid"))
-

tests/test_opentok.py

@@ -52,6 +52,29 @@ def test_mute_all_exclude_streams(self):
         response.headers["x-opentok-auth"].should.equal(self.jwt_token_string)
         response.headers["Content-Type"].should.equal("application/json")
 
+    @httpretty.activate
+    def test_disable_force_mute(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='{}',
+                                                                content_type="application/json",
+                                                                adding_headers= {"x-opentok-auth": self.jwt_token_string},
+                                                                status=201)
+                                        ])
+
+    
+        response = requests.post(self.url)
+
+        response.text.should.equal('{}')
+        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(