add maxBitrate and hlsStatus to Broadcast API

Author: maxkahan

README.rst

@@ -438,8 +438,9 @@ The live streaming broadcast can target one HLS endpoint and up to five RTMP ser
       'stylesheet': 'the layout stylesheet (only used with type == custom)'
     },
     'maxDuration': 5400,
-    'hasAudio': True
-    'hasVideo': True
+    'hasAudio': True,
+    'hasVideo': True,
+    'maxBitrate': 2000000,
     'outputs': {
       'hls': {},
       'rtmp': [{
@@ -466,6 +467,8 @@ You can specify the following broadcast resolutions:
 * "1920x1080" (FHD landscape)
 * "1080x1920" (FHD portrait)
 
+You can specify a maximum bitrate between 100000 and 6000000.
+
 .. code:: python
 
   session_id = 'SESSIONID'
@@ -476,6 +479,7 @@ You can specify the following broadcast resolutions:
       'stylesheet': 'the layout stylesheet (only used with type == custom)'
     },
     'maxDuration': 5400,
+    'maxBitrate': 2000000,
     'outputs': {
       'hls': {},
       'rtmp': [{
@@ -508,8 +512,9 @@ to ``False`` as required. These fields are ``True`` by default.
       'stylesheet': 'the layout stylesheet (only used with type == custom)'
     },
     'maxDuration': 5400,
-    'hasAudio': True
-    'hasVideo': False
+    'hasAudio': True,
+    'hasVideo': False,
+    'maxBitrate': 2000000,
     'outputs': {
       'hls': {},
       'rtmp': [{

opentok/broadcast.py

@@ -24,7 +24,7 @@ class Broadcast(object):
 
     :ivar resolution:
         The resolution of the broadcast (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1920x1080").
-        
+
     :ivar status:
         The status of the broadcast.
 
@@ -34,29 +34,36 @@ class Broadcast(object):
     :ivar hasVideo:
         Whether the broadcast has video.
 
+    :ivar 'maxBitrate' optional:
+        The maximum bitrate (bits per second) used by the broadcast.
+
     :ivar broadcastUrls:
         An object containing details about the HLS and RTMP broadcasts.
-        
-        If you specified an HLS endpoint, the object includes an hls property, which is set to the URL for the HLS broadcast. 
-        Note this HLS broadcast URL points to an index file, an .M3U8-formatted playlist that contains a list of URLs 
+
+        If you specified an HLS endpoint, the object includes an hls property, which is set to the URL for the HLS broadcast.
+        Note this HLS broadcast URL points to an index file, an .M3U8-formatted playlist that contains a list of URLs
         to .ts media segment files (MPEG-2 transport stream files).
         While the URLs of both the playlist index file and media segment files are provided as soon as the HTTP response
-        is returned, these URLs should not be accessed until 15 - 20 seconds later, 
-        after the initiation of the HLS broadcast, due to the delay between the HLS broadcast and the live streams 
-        in the OpenTok session. 
-        See https://developer.apple.com/library/ios/technotes/tn2288/_index.html for more information about the playlist index 
+        is returned, these URLs should not be accessed until 15 - 20 seconds later,
+        after the initiation of the HLS broadcast, due to the delay between the HLS broadcast and the live streams
+        in the OpenTok session.
+        See https://developer.apple.com/library/ios/technotes/tn2288/_index.html for more information about the playlist index
         file and media segment files for HLS.
 
-        If you specified RTMP stream endpoints, the object includes an rtmp property. 
-        This is an array of objects that include information on each of the RTMP streams. 
-        Each of these objects has the following properties: id (the ID you assigned to the RTMP stream), 
-        serverUrl (the server URL), streamName (the stream name), and status property (which is set to "connecting"). 
-        You can call the OpenTok REST method to check for status updates for the broadcast: 
+        If you specified an HLS endpoint, the object will also include an "hlsStatus" property with
+        information about the HLS broadcast. This will have one of the following values:
+            ["connecting", "ready", "live", "ended", "error"].
+
+        If you specified RTMP stream endpoints, the object includes an rtmp property.
+        This is an array of objects that include information on each of the RTMP streams.
+        Each of these objects has the following properties: id (the ID you assigned to the RTMP stream),
+        serverUrl (the server URL), streamName (the stream name), and status property (which is set to "connecting").
+        You can call the OpenTok REST method to check for status updates for the broadcast:
         https://tokbox.com/developer/rest/#get_info_broadcast
 
     :ivar streamMode:
         Whether streams included in the broadcast are selected automatically
-        ("auto", the default) or manually ("manual"). 
+        ("auto", the default) or manually ("manual").
 
     :ivar streams:
         A list of streams currently being broadcasted. This is only set for a broadcast with
@@ -71,6 +78,8 @@ def __init__(self, kwargs):
         self.updatedAt = kwargs.get("updatedAt")
         self.hasAudio = kwargs.get("hasAudio")
         self.hasVideo = kwargs.get("hasVideo")
+        self.maxBitrate = kwargs.get("maxBitrate")
+        self.maxDuration = kwargs.get("maxDuration")
         self.resolution = kwargs.get("resolution")
         self.status = kwargs.get("status")
         self.broadcastUrls = kwargs.get("broadcastUrls")
@@ -83,8 +92,9 @@ def json(self):
         """
         return json.dumps(self, default=lambda o: o.__dict__, sort_keys=True, indent=4)
 
+
 class BroadcastStreamModes(Enum):
-    """"List of valid settings for the stream_mode parameter of the OpenTok.start_broadcast()
+    """ "List of valid settings for the stream_mode parameter of the OpenTok.start_broadcast()
     method."""
 
     auto = u("auto")

opentok/exceptions.py

@@ -89,11 +89,13 @@ class BroadcastError(OpenTokException):
 
     pass
 
+
 class DTMFError(OpenTokException):
     """
     Indicates that one of the properties digits, session_id or connection_id is invalid
     """
 
+
 class ArchiveStreamModeError(OpenTokException):
     """
     Indicates that the archive is configured with a streamMode that does not support stream manipulation.
@@ -110,12 +112,18 @@ class BroadcastStreamModeError(OpenTokException):
 
 class BroadcastHLSOptionsError(OpenTokException):
     """
-    Indicates that HLS options have been set incorrectly. 
-    
+    Indicates that HLS options have been set incorrectly.
+
     dvr and lowLatency modes cannot both be set to true in a broadcast.
     """
 
 
+class BroadcastOptionsError(OpenTokException):
+    """
+    Indicates that broadcast options have been set incorrectly.
+    """
+
+
 class InvalidWebSocketOptionsError(OpenTokException):
     """
     Indicates that the WebSocket options selected are invalid.