Merge pull request #213 from opentok/dev

3.3.0 Release

Author: maxkahan

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.2.0
+current_version = 3.3.0
 commit = True
 tag = False
 

CHANGES.md

@@ -1,3 +1,11 @@
+# Release v3.3.0
+
+- Support for Experience Composer (Render) API
+- Support for multiple archives and broadcasts in the `start_archive` and `start_broadcast` methods
+- Support for low latency and DVR modes
+- Documented more methods in README
+- Updated some out-of-date dependencies
+
 # Release v3.2.0
 
 ## Added

README.rst

@@ -146,12 +146,35 @@ streams in the session to individual files (instead of a single composed file) b
   # Store this archive_id in the database
   archive_id = archive.id
 
+To add an individual stream to an archive, use the
+``opentok.add_archive_stream(archive_id, stream_id, has_audio, has_video)`` method:
+
+.. code:: python
+
+  opentok.add_archive_stream(archive.id, stream_id, has_audio=True, has_video=True)
+
+To remove a stream from an archive, use the ``opentok.remove_archive_stream()`` method:
+
+.. code:: python
+
+  opentok.remove_archive_stream(archive.id, stream_id)
+
 Composed archives (output_mode=OutputModes.composed) have an optional ``resolution`` parameter.
-If no value is supplied the opentok platform will use the default resolution "640x480".
-You can set this to "1280x720" by setting the
+If no value is supplied, the archive will use the default resolution, "640x480".
+You can set this to another resolution by setting the
 ``resolution`` parameter of the ``opentok.start_archive()`` method.
 
-Warning: This value cannot be set for Individual output mode, an error will be thrown.
+You can specify the following archive resolutions:
+
+* "640x480" (SD landscape, default resolution)
+* "480x640" (SD portrait)
+* "1280x720" (HD landscape)
+* "720x1280" (HD portrait)
+* "1920x1080" (FHD landscape)
+* "1080x1920" (FHD portrait)
+
+Setting the ``resolution`` parameter while setting the ``output_mode`` parameter to
+``OutputModes.individual`` results in an error.
 
 .. code:: python
 
@@ -160,8 +183,15 @@ 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 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.
+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
 
@@ -195,7 +225,7 @@ filter by session ID. This method returns an instance of the ``ArchiveList`` cla
 
 .. code:: python
 
-  archive_list = opentok.list_archive()
+  archive_list = opentok.list_archives()
 
   # Get a specific Archive from the list
   archive = archive_list.items[i]
@@ -371,7 +401,8 @@ Working with Broadcasts
 
 OpenTok broadcast lets you share live OpenTok sessions with many viewers.
 
-You can use the ``opentok.start_broadcast()`` method to start a live streaming for an OpenTok session. This broadcasts the session to an HLS (HTTP live streaming) or to RTMP streams.
+You can use the ``opentok.start_broadcast()`` method to start a live stream for an OpenTok session.
+This broadcasts the session to HLS (HTTP live streaming) or to RTMP streams.
 
 To successfully start broadcasting a session, at least one client must be connected to the session.
 
@@ -403,6 +434,45 @@ The live streaming broadcast can target one HLS endpoint and up to five RTMP ser
 
   broadcast = opentok.start_broadcast(session_id, options)
 
+You can specify the following broadcast resolutions:
+
+* "640x480" (SD landscape, default resolution)
+* "480x640" (SD portrait)
+* "1280x720" (HD landscape)
+* "720x1280" (HD portrait)
+* "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
@@ -465,6 +535,16 @@ You can dynamically change the layout type of a live streaming broadcast.
       'stream.instructor {position: absolute; width: 100%;  height:50%;}'
   )
 
+You can add streams to a broadcast using the ``opentok.add_broadcast_stream()`` method:
+
+.. code:: python
+  opentok.add_broadcast_stream(broadcast_id, stream_id)
+
+Conversely, streams can be removed from a broadcast with the ``opentok.remove_broadcast_stream()`` method.
+
+.. code:: python
+  opentok.remove_broadcast_stream(broadcast_id, stream_id)
+
 For more information about OpenTok live streaming broadcasts, see the
 `Broadcast developer guide <https://tokbox.com/developer/guides/broadcast/>`_.
 
@@ -483,6 +563,46 @@ And then proceed to change the value with
 
 ``opentok.timeout = value``
 
+Muting streams
+--------------
+
+You can mute all streams in a session using the ``opentok.mute_all()`` method:
+
+.. code:: python
+  opentok.mute_all(session_id)
+
+  # You can also specify streams to exclude (e.g. main presenter)
+  excluded_stream_ids = ['1234', '5678']
+  opentok.mute_all(session_id, excluded_stream_ids)
+
+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:
+
+.. code:: python
+  opentok.disable_force_mute(session_id)
+
+After calling the ``opentok.disableForceMute()`` method, new streams that are published
+to the session will not be muted.
+
+You can mute a single stream using the ``opentok.mute_stream()`` method:
+
+.. code:: python
+  opentok.mute_stream(session_id, stream_id)
+
+DTMF
+------
+
+You can send dual-tone multi-frequency (DTMF) digits to SIP endpoints. You can play DTMF tones
+to all clients connected to session or to a specific connection:
+
+.. code:: python
+  digits = '12345'
+  opentok.play_dtmf(session_id, digits)
+
+  # To a specific connection
+  opentok.play_dtmf(session_id, connection_id, digits)
+
 Samples
 -------
 
@@ -495,7 +615,7 @@ repository and follow the Walkthroughs:
 Documentation
 -------------
 
-Reference documentation is available at http://www.tokbox.com/opentok/libraries/server/python/reference/index.html.
+Reference documentation is available at https://tokbox.com/developer/sdks/python/reference/.
 
 Requirements
 ------------
@@ -532,7 +652,7 @@ The Client.create_session() method now includes a media_mode parameter, instead
 This version of the SDK includes significant improvements such as top level entity naming, where the Opentok class is now `Client`.  We also implemented a standardised logging module, improved naming conventions and JWT generation to make developer experience more rewarding.
 
 For details, see the reference documentation at
-http://www.tokbox.com/opentok/libraries/server/python/reference/index.html.
+https://tokbox.com/developer/sdks/python/reference/.
 
 Development and Contributing
 ----------------------------

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/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,18 +1,59 @@
 import json
 from enum import Enum
-from six import iteritems, u
+from six import u
 
 
 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/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.
+    """