added lowLatency/dvr exception, check for new HLS options, added methods in deprecated class to Client class

Author: maxkahan

opentok/archives.py

@@ -4,6 +4,8 @@
 import pytz
 from enum import Enum
 
+from .exceptions import ArchiveError
+
 if PY3:
     from datetime import timezone
 

opentok/broadcast.py

@@ -1,6 +1,6 @@
 import json
 from enum import Enum
-from six import iteritems, u
+from six import u
 
 
 class Broadcast(object):

opentok/exceptions.py

@@ -108,3 +108,11 @@ class BroadcastStreamModeError(OpenTokException):
     """
 
     pass
+
+
+class BroadcastHLSOptionsError(OpenTokException):
+    """
+    Indicates that HLS options have been set incorrectly. 
+    
+    dvr and lowLatency modes cannot both be set to true in a broadcast.
+    """

opentok/opentok.py

@@ -34,6 +34,7 @@
 from .broadcast import Broadcast, BroadcastStreamModes
 from .exceptions import (
     ArchiveStreamModeError,
+    BroadcastHLSOptionsError,
     BroadcastStreamModeError,
     OpenTokException,
     RequestError,
@@ -47,6 +48,7 @@
     SetStreamClassError,
     BroadcastError,
     DTMFError
+
 )
 
 
@@ -1274,8 +1276,8 @@ class names (Strings) to apply to the stream. For example:
 
     def start_broadcast(self, session_id, options, stream_mode=BroadcastStreamModes.auto):
         """
-        Use this method to start a live streaming for an OpenTok session. This broadcasts the
-        session to an HLS (HTTP live streaming) or to RTMP streams. To successfully start
+        Use this method to start a live streaming broadcast for an OpenTok session. This broadcasts
+        the session to an HLS (HTTP live streaming) or to RTMP streams. To successfully start
         broadcasting a session, at least one client must be connected to the session. You can only
         start live streaming for sessions that use the OpenTok Media Router (with the media mode set
         to routed); you cannot use live streaming with sessions that have the media mode set to
@@ -1309,7 +1311,8 @@ def start_broadcast(self, session_id, options, stream_mode=BroadcastStreamModes.
             If you include RTMP streaming, you can specify up to five target RTMP streams. For
             each RTMP stream, specify 'serverUrl' (the RTMP server URL), 'streamName' (the stream
             name, such as the YouTube Live stream name or the Facebook stream key), and
-            (optionally) 'id' (a unique ID for the stream)
+            (optionally) 'id' (a unique ID for the stream). You can optionally specify lowLatency or
+            DVR mode, but these options are mutually exclusive.
 
             String 'resolution' optional: The resolution of the broadcast, either "640x480"
             (SD, the default) or "1280x720" (HD)
@@ -1322,6 +1325,14 @@ def start_broadcast(self, session_id, options, stream_mode=BroadcastStreamModes.
         :rtype A Broadcast object, which contains information of the broadcast: id, sessionId
         projectId, createdAt, updatedAt, resolution, status and broadcastUrls
         """
+
+        if 'hls' in options['outputs']:
+            if 'lowLatency' in options['outputs']['hls'] and 'dvr' in options['outputs']['hls']:
+                if options['outputs']['hls']['lowLatency'] == True and options['outputs']['hls']['dvr'] == True:
+                    raise BroadcastHLSOptionsError(
+                        'HLS options "lowLatency" and "dvr" cannot both be set to "True".'
+                        )
+
         payload = {
                     "sessionId": session_id,
                     "streamMode": stream_mode.value
@@ -1615,8 +1626,152 @@ def _create_jwt_auth_header(self):
         }
 
         return jwt.encode(payload, self.api_secret, algorithm="HS256")
+        
+
+    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.
+
+        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.disable_force_mute() method.
+
+        :param session_id The session ID
+
+        :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.
+        """
+
+        options = {}
+        url = self.endpoints.get_mute_all_url(session_id)
+
+        try:
+            if excludedStreamIds:
+                options = {'active': True, 'excludedStreams': excludedStreamIds }
+            else:
+                options = {'active': True, '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 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 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.
+        """
+
+        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 {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
+
+        :param session_id The ID of the OpenTok session that the participant being called
+        will join
+
+        :param connection_id An optional parameter used to send the DTMF tones to a specific
+        connection in a session.
+
+        :param digits DTMF digits to play
+        Valid DTMF digits are 0-9, p, #, and * digits. 'p' represents a 500ms pause if a delay is
+        needed during the input process.
+
+        """
+
+        try:
+            if not connection_id:
+                url = self.endpoints.get_dtmf_all_url(session_id)
+                payload = {"digits": digits}
+            else:
+                url = self.endpoints.get_dtmf_specific_url(session_id, connection_id)
+                payload = {"digits": digits}
+
+            response = requests.post(url, headers=self.get_json_headers(), data=json.dumps(payload))
+
+            if response.status_code == 200:
+                return response
+            elif response.status_code == 400:
+                raise DTMFError("One of the properties digits, sessionId or connectionId is invalid.")
+            elif response.status_code == 403:
+                raise AuthError("Failed to create session, invalid credentials. Please check your OpenTok API Key or JSON web token")
+            elif response.status_code == 404:
+                raise NotFoundError("The session does not exists or the client specified by the connection_id is not connected to the session")
+        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"))
 
 class OpenTok(Client):
     def __init__(
@@ -1646,15 +1801,11 @@ def mute_all(self,
 
         """
         Mutes all streams in an OpenTok session.
-
         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.
         This is an optional property. If you omit this property, all streams in the session will be muted.
         """
@@ -1688,12 +1839,10 @@ 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.
         """
 
@@ -1721,9 +1870,7 @@ def disable_force_mute(self, session_id: str) -> requests.Response:
     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.
         """
 
@@ -1750,17 +1897,13 @@ def mute_stream(self, session_id: str, stream_id: str) -> requests.Response:
     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
-
         :param session_id The ID of the OpenTok session that the participant being called
         will join
-
         :param connection_id An optional parameter used to send the DTMF tones to a specific
         connectoiin in a session.
-
         :param digits DTMF digits to play
         Valid DTMF digits are 0-9, p, #, and * digits. 'p' represents a 500ms pause if a delay is
         needed during the input process.
-
         """
 
         try:
@@ -1783,4 +1926,4 @@ def play_dtmf(self, session_id: str, connection_id: str, digits: str, options: d
                 raise NotFoundError("The session does not exists or the client specified by the connection_id is not connected to the session")
         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"))
+                (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"))