Merge branch 'dev' into add-hls-options-and-docs

Author: maxkahan

README.rst

@@ -183,8 +183,15 @@ Setting the ``resolution`` parameter while setting the ``output_mode`` parameter
   # Store this archive_id in the database
   archive_id = archive.id
 
-To stop the recording of a started archive, call the ``opentok.stop_archive(archive_id)``
-method. You can also do this using the ``archive.stop()`` method of an ``Archive`` instance.
+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.
 
 .. code:: python
 
@@ -436,6 +443,36 @@ You can specify the following broadcast resolutions:
 * "1920x1080" (FHD landscape)
 * "1080x1920" (FHD portrait)
 
+.. 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)
+  
+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.
+
 You can stop a started Broadcast using the ``opentok.stop_broadcast(broadcast_id)`` method.
 
 .. code:: python

opentok/__init__.py

@@ -14,3 +14,4 @@
 from .streamlist import StreamList
 from .sip_call import SipCall
 from .broadcast import Broadcast, BroadcastStreamModes
+from .render import Render, RenderList

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/endpoints.py

@@ -200,3 +200,11 @@ def get_broadcast_stream(self, broadcast_id=None):
         )
 
         return url
+
+    def get_render_url(self, render_id: str = None):
+        "Returns URLs for working with the Render API."""
+        url = self.api_url + "/v2/project/" + self.api_key + "/render"
+        if render_id:
+            url += "/" + render_id
+
+        return url

opentok/opentok.py

@@ -28,6 +28,7 @@
 from .endpoints import Endpoints
 from .session import Session
 from .archives import Archive, ArchiveList, OutputModes, StreamModes
+from .render import Render, RenderList
 from .stream import Stream
 from .streamlist import StreamList
 from .sip_call import SipCall
@@ -486,7 +487,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.
@@ -537,6 +539,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.
         """
@@ -561,7 +571,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:
@@ -1334,6 +1345,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
@@ -1627,6 +1644,164 @@ def set_broadcast_layout(self, broadcast_id, layout_type, stylesheet=None, scree
         else:
             raise RequestError("OpenTok server error.", response.status_code)
 
+    def start_render(self, session_id, opentok_token, url, max_duration=7200, resolution="1280x720", status_callback_url=None, properties: dict = None):
+        """
+        Starts an Experience Composer for the specified OpenTok session.
+        For more information, see the
+       `Experience Composer developer guide <https://tokbox.com/developer/guides/experience-composer>`_.
+
+        :param String 'session_id': The session ID of the OpenTok session that will include the Experience Composer stream.
+        :param String 'token': A valid OpenTok token with a Publisher role and (optionally) connection data to be associated with the output stream.
+        :param String 'url': A publically reachable URL controlled by the customer and capable of generating the content to be rendered without user intervention.
+        :param Integer 'maxDuration' Optional: The maximum time allowed for the Experience Composer, in seconds. After this time, it is stopped automatically, if it is still running. The maximum value is 36000 (10 hours), the minimum value is 60 (1 minute), and the default value is 7200 (2 hours). When the Experience Composer ends, its stream is unpublished and an event is posted to the callback URL, if configured in the Account Portal.
+        :param String 'resolution' Optional: The resolution of the Experience Composer, either "640x480" (SD landscape), "480x640" (SD portrait), "1280x720" (HD landscape), "720x1280" (HD portrait), "1920x1080" (FHD landscape), or "1080x1920" (FHD portrait). By default, this resolution is "1280x720" (HD landscape, the default).
+        :param Dictionary 'properties' Optional: Initial configuration of Publisher properties for the composed output stream.
+            String name Optional: The name of the composed output stream which will be published to the session. The name must have a minimum length of 1 and a maximum length of 200.
+        """
+        payload = {
+            "sessionId": session_id,
+            "token": opentok_token,
+            "url": url,
+            "maxDuration": max_duration,
+            "resolution": resolution,
+            "properties": properties
+        }
+
+        logger.debug(
+            "POST to %r with params %r, headers %r, proxies %r",
+            self.endpoints.get_render_url(),
+            json.dumps(payload),
+            self.get_json_headers(),
+            self.proxies,
+        )
+
+        response = requests.post(
+            self.endpoints.get_render_url(),
+            json=payload,
+            headers=self.get_json_headers(),
+            proxies=self.proxies,
+            timeout=self.timeout,
+        )
+
+        if response and response.status_code == 202:
+            return Render(response.json())
+        elif response.status_code == 400:
+            """
+            The HTTP response has a 400 status code in the following cases:
+            You do not pass in a session ID or you pass in an invalid session ID.
+            You specify an invalid value for input parameters.
+            """
+            raise RequestError(response.json().get("message"))
+        elif response.status_code == 403:
+            raise AuthError("You passed in an invalid OpenTok API key or JWT token.")
+        else:
+            raise RequestError("An unexpected error occurred", response.status_code)
+
+
+    def get_render(self, render_id):
+        """
+        This method allows you to see the status of a render, which can be one of the following:
+            ['starting', 'started', 'stopped', 'failed']
+
+        :param String 'render_id': The ID of a specific render. 
+        """
+        logger.debug(
+            "GET to %r with headers %r, proxies %r",
+            self.endpoints.get_render_url(render_id=render_id),
+            self.get_json_headers(),
+            self.proxies,
+        )
+
+        response = requests.get(
+            self.endpoints.get_render_url(render_id=render_id),
+            headers=self.get_json_headers(),
+            proxies=self.proxies,
+            timeout=self.timeout,
+        )
+
+        if response.status_code == 200:
+            return Render(response.json())
+        elif response.status_code == 400:
+            raise RequestError(
+                "Invalid request. This response may indicate that data in your request is invalid JSON. Or it may indicate that you do not pass in a session ID."
+            )
+        elif response.status_code == 403:
+            raise AuthError("You passed in an invalid OpenTok API key or JWT token.")
+        elif response.status_code == 404:
+            raise NotFoundError("No render matching the specified render ID was found.")
+        else:
+            raise RequestError("An unexpected error occurred", response.status_code)
+
+    def stop_render(self, render_id):
+        """
+        This method stops a render.
+
+        :param String 'render_id': The ID of a specific render. 
+        """
+        logger.debug(
+            "DELETE to %r with headers %r, proxies %r",
+            self.endpoints.get_render_url(render_id=render_id),
+            self.get_headers(),
+            self.proxies,
+        )
+
+        response = requests.delete(
+            self.endpoints.get_render_url(render_id=render_id),
+            headers=self.get_headers(),
+            proxies=self.proxies,
+            timeout=self.timeout,
+        )
+
+        if response.status_code == 200:
+            return response
+        elif response.status_code == 400:
+            raise RequestError(
+                "Invalid request. This response may indicate that data in your request is invalid JSON. Or it may indicate that you do not pass in a session ID."
+            )
+        elif response.status_code == 403:
+            raise AuthError("You passed in an invalid OpenTok API key or JWT token.")
+        elif response.status_code == 404:
+            raise NotFoundError("No render matching the specified render ID was found.")
+        else:
+            raise RequestError("An unexpected error occurred", response.status_code)
+
+    def list_renders(self, offset=0, count=50):
+        """
+        List existing renders associated with the project's API key.
+
+        :param Integer 'offset' Optional: Start offset in the list of existing renders.
+        :param Integer 'count' Optional: Number of renders to retrieve, starting at 'offset'. 
+        """
+
+        query_params = {"offset": offset, "count": count}
+
+        logger.debug(
+            "GET to %r with headers %r, params %r, proxies %r",
+            self.endpoints.get_render_url(),
+            self.get_headers(),
+            query_params,
+            self.proxies,
+        )
+
+        response = requests.get(
+            self.endpoints.get_render_url(),
+            headers=self.get_headers(),
+            params=query_params,
+            proxies=self.proxies,
+            timeout=self.timeout,
+        )
+
+        if response.status_code == 200:
+            return RenderList(self, response.json())
+        elif response.status_code == 400:
+            raise RequestError(
+                "Invalid request. This response may indicate that data in your request is invalid JSON. Or it may indicate that you do not pass in a session ID."
+            )
+        elif response.status_code == 403:
+            raise AuthError("You passed in an invalid OpenTok API key or JWT token.")
+        else:
+            raise RequestError("An unexpected error occurred", response.status_code)
+
     def _sign_string(self, string, secret):
         return hmac.new(
             secret.encode("utf-8"), string.encode("utf-8"), hashlib.sha1

opentok/render.py

@@ -0,0 +1,39 @@
+import json
+from six import iteritems
+
+class Render:
+    """Represents an Experience Composer render of an OpenTok session."""
+
+    def __init__(self, kwargs):
+        self.id = kwargs.get("id")
+        self.sessionId = kwargs.get("sessionId")
+        self.projectId = kwargs.get("projectId")
+        self.createdAt = kwargs.get("createdAt")
+        self.updatedAt = kwargs.get("updatedAt")
+        self.url = kwargs.get("url")
+        self.resolution = kwargs.get("resolution")
+        self.status = kwargs.get("status")
+        self.streamId = kwargs.get("streamId") or None
+        self.reason = kwargs.get("reason") or None
+
+    def json(self):
+        """Returns a JSON representation of the render."""
+        return json.dumps(self, default=lambda o: o.__dict__, sort_keys=True, indent=4)
+
+    def attrs(self):
+        """
+        Returns a dictionary of the render's attributes.
+        """
+        return dict((k, v) for k, v in iteritems(self.__dict__))
+
+class RenderList:
+    """Object that represents a list of renders."""
+    def __init__(self, sdk, values):
+        self.count = values.get("count")
+        self.items = list(map(lambda x: Render(x), values.get("items", [])))
+
+    def attrs(self):
+        return {"count": self.count, "items": map(Render.attrs, self.items)}
+
+    def json(self):
+        return json.dumps(self.attrs(), indent=4)