Merge pull request #207 from opentok/add-multiple-archives-and-broadcasts

enabled multiArchive and multiBroadcast options for start_archive and…

Author: maxkahan

README.rst

@@ -160,6 +160,13 @@ Warning: This value cannot be set for Individual output mode, an error will be t
   # Store this archive_id in the database
   archive_id = archive.id
 
+You can enable multiple simultaneous archives by specifying a unique value for the ``multi_archive_tag`` 
+parameter in the ``start_archive`` method.
+
+.. code:: python
+
+  archive = opentok.start_archive(session_id, name=u'Important Presentation', multi_archive_tag='MyArchiveTag')
+
 You can stop the recording of a started Archive using the ``opentok.stop_archive(archive_id)``
 method. You can also do this using the ``archive.stop()`` method of an ``Archive`` instance.
 
@@ -403,6 +410,36 @@ The live streaming broadcast can target one HLS endpoint and up to five RTMP ser
 
   broadcast = opentok.start_broadcast(session_id, options)
 
+To enable multiple simultaneous broadcasts on the same session, specify a unique value for the 
+``multiBroadcastTag`` parameter in ``options`` when calling the ``opentok.start_broadcast`` method.
+
+.. code:: python
+
+  session_id = 'SESSIONID'
+  options = {
+    'multiBroadcastTag': 'unique_broadcast_tag'
+    'layout': {
+      'type': 'custom',
+      'stylesheet': 'the layout stylesheet (only used with type == custom)'
+    },
+    'maxDuration': 5400,
+    'outputs': {
+      'hls': {},
+      'rtmp': [{
+        'id': 'foo',
+        'serverUrl': 'rtmp://myfooserver/myfooapp',
+        'streamName': 'myfoostream'
+      }, {
+        'id': 'bar',
+        'serverUrl': 'rtmp://mybarserver/mybarapp',
+        'streamName': 'mybarstream'
+      }]
+    },
+    'resolution': '640x480'
+  }
+
+  broadcast = opentok.start_broadcast(session_id, options)
+
 You can stop a started Broadcast using the ``opentok.stop_broadcast(broadcast_id)`` method.
 
 .. code:: python

opentok/broadcast.py

@@ -7,12 +7,53 @@ class Broadcast(object):
     """
     Represents a live streaming broadcast.
 
+    :ivar id:
+        The broadcast ID.
+
+    :ivar session_id:
+       The session ID of the OpenTok session associated with this broadcast.
+
+    :ivar project_id:
+        Your OpenTok API key.
+
+    :ivar created_at:
+       The time at which the broadcast was created, in milliseconds since the UNIX epoch.
+
+    :ivar updated_at:
+       The time at which the broadcast was last updated, in milliseconds since the UNIX epoch.
+
+    :ivar resolution:
+        The resolution of the broadcast (either "640x480", "1280x720", "1920x1080", "480x640", "720x1280", or "1920x1080").
+        
+    :ivar status:
+        The status of 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 
+        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 
+        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: 
+        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"). 
-    
+
     :ivar streams:
-        A list of streams currently being broadcast. This is only set for a broadcast with
+        A list of streams currently being broadcasted. This is only set for a broadcast with
         the status set to "started" and the stream_Mode set to "manual".
     """
 

opentok/opentok.py

@@ -484,7 +484,8 @@ def start_archive(
         output_mode=OutputModes.composed,
         stream_mode=StreamModes.auto,
         resolution=None,
-        layout=None
+        layout=None,
+        multi_archive_tag=None
     ):
         """
         Starts archiving an OpenTok session.
@@ -535,6 +536,14 @@ def start_archive(
         StreamModes.manual to explicitly select streams to include in the the archive, using the
         OpenTok.add_archive_stream() and OpenTok.remove_archive_stream() methods.
 
+        :param String multi_archive_tag (Optional): Set this to support recording multiple archives for the same 
+        session simultaneously. Set this to a unique string for each simultaneous archive of an ongoing session. 
+        You must also set this option when manually starting an archive that is automatically archived. 
+        Note that the multiArchiveTag value is not included in the response for the methods to list archives and 
+        retrieve archive information. If you do not specify a unique multi_archive_tag, you can only record one archive 
+        at a time for a given session. 
+        For more information, see simultaneous archives: https://tokbox.com/developer/guides/archiving/#simultaneous-archives. 
+
         :rtype: The Archive object, which includes properties defining the archive,
           including the archive ID.
         """
@@ -559,7 +568,8 @@ def start_archive(
             "hasVideo": has_video,
             "outputMode": output_mode.value,
             "resolution": resolution,
-            "streamMode": stream_mode.value
+            "streamMode": stream_mode.value,
+            "multiArchiveTag": multi_archive_tag
         }
 
         if layout is not None:
@@ -1314,6 +1324,12 @@ def start_broadcast(self, session_id, options, stream_mode=BroadcastStreamModes.
             String 'resolution' optional: The resolution of the broadcast, either "640x480"
             (SD, the default) or "1280x720" (HD)
 
+            String 'multiBroadcastTag' optional: Set this to support multiple broadcasts for the same session simultaneously. 
+            Set this to a unique string for each simultaneous broadcast of an ongoing session. 
+            Note that the multiBroadcastTag value is not included in the response for the methods to list live streaming 
+            broadcasts and get information about a live streaming broadcast. 
+            For more information, see https://tokbox.com/developer/guides/broadcast/live-streaming#simultaneous-broadcasts. 
+
         :param BroadcastStreamModes stream_mode (Optional): Determines the broadcast stream handling mode.
         Set this to BroadcastStreamModes.auto (the default) to have streams added automatically. Set this to
         BroadcastStreamModes.manual to explicitly select streams to include in the the broadcast, using the