Docs edits.

Author: jeffswartz

.gitignore

@@ -43,3 +43,6 @@ docs/_build/
 
 # Virtual env
 venv/
+
+# Mac Desktop files
+.DS_Store

README.rst

@@ -10,8 +10,6 @@ The OpenTok Python SDK lets you generate
 `tokens <http://tokbox.com/opentok/tutorials/create-token/>`_ for `OpenTok <http://www.tokbox.com/>`_
 applications, and `archive <http://www.tokbox.com/platform/archiving>`_ OpenTok sessions.
 
-If you are updating from a previous version of this SDK, see "Important changes since v2.2.0" below.
-
 Installation using Pip (recommended):
 -------------------------------------
 
@@ -59,6 +57,8 @@ store (such as a database).
   # to use the OpenTok TURN server to relay streams if the clients cannot connect):
   session = opentok.create_session()
   # A session that uses the OpenTok Media Router:
+  session = opentok.create_session(media_mode=MediaModes.routed)
+  # An automatically archived session:
   session = opentok.create_session(media_mode=MediaModes.routed, archive_mode=ArchiveModes.always)
   # A session with a location hint
   session = opentok.create_session(location=u'12.34.56.78')
@@ -114,7 +114,7 @@ the `options` parameter to `false`:
 
 By default, all streams are recorded to a single (composed) file. You can record the different
 streams in the session to individual files (instead of a single composed file) by setting the
-``output_mode`` parameter of the ``opentok.start_archive()`` method `OutputModesModes.individual`.
+``output_mode`` parameter of the ``opentok.start_archive()`` method `OutputModes.individual`.
 
 .. code:: python
 
@@ -170,9 +170,13 @@ instance of the ``ArchiveList`` class.
   # Get the total number of Archives for this API Key
   total = archive_list.total
 
-Note that you can also create an automatically archived session, by passing in ``ArchiveModes.always``
-as the ``archive_mode`` parameter when you call the ``opentok.create_session()`` method (see "Creating
-Sessions," above).
+Note that you can also create an automatically archived session, by passing in
+``ArchiveModes.always`` as the ``archive_mode`` parameter when you call the
+``opentok.create_session()`` method (see "Creating Sessions," above).
+
+For more information on archiving, see the
+`OpenTok archiving <https://tokbox.com/opentok/tutorials/archiving/>`_ programming guide.
+
 
 Samples
 -------
@@ -215,8 +219,7 @@ session uses the OpenTok TURN server to relay audio-video streams.
 
 **Changes in v2.2.0:**
 
-This version of the SDK includes support for working with OpenTok 2.0 archives. (This API does not
-work with OpenTok 1.0 archives.)
+This version of the SDK includes support for working with OpenTok archives.
 
 The OpenTok.create_session() method now includes a media_mode parameter, instead of a p2p parameter.
 

opentok/archives.py

@@ -12,12 +12,12 @@
 dthandler = lambda obj: obj.isoformat() if isinstance(obj, datetime)  or isinstance(obj, date) else None
 
 class OutputModes(Enum):
-    """List of valid settings for the outputMode parameter of the OpenTok.start_archive() method."""
+    """List of valid settings for the output_mode parameter of the OpenTok.start_archive()
+    method."""
     composed = u('composed')
-    """The archive will produce a single MP4 file composed of all streams."""
+    """All streams in the archive are recorded to a single (composed) file."""
     individual = u('individual')
-    """The archive will generate a ZIP container with multiple individual WEBM files and a JSON metadata
-    file for video synchronization."""
+    """Each stream in the archive is recorded to an individual file."""
 
 class Archive(object):
     """Represents an archive of an OpenTok session.
@@ -28,27 +28,25 @@ class Archive(object):
     :ivar duration:
        The duration of the archive, in milliseconds.
 
-    :ivar hasAudio:
+    :ivar has_audio:
        Boolean value set to true when the archive contains an audio track,
        and set to false otherwise.
 
-    :ivar hasVideo:
+    :ivar has_video:
        Boolean value set to true when the archive contains a video track,
        and set to false otherwise.
 
-    :ivar outputMode:
-        The output mode to be generated for this archive:
-        The default value is composed (a single MP4 file composed of all streams).
-        Value individual will generate a ZIP container with multiple individual WEBM files
-        and a JSON metadata file for video synchronization.
-
     :ivar id:
        The archive ID.
 
     :ivar name:
        The name of the archive. If no name was provided when the archive was created, this is set
        to null.
 
+    :ivar output_mode:
+        Whether all streams in the archive are recorded to a single file
+        (OutputModes.composed) or to individual files (OutputModes.individual).
+
     :ivar partnerId:
        The API key associated with the archive.
 
@@ -69,7 +67,12 @@ class Archive(object):
        * "available" -- The archive is available for download from the OpenTok cloud.
        * "expired" -- The archive is no longer available for download from the OpenTok cloud.
        * "failed" -- The archive recording failed.
-       * "paused" -- The archive recording has paused.
+       * "paused" -- The archive is in progress and no clients are publishing streams to the
+         session. When an archive is in progress and any client publishes a stream, the status is
+         "started". When an archive is paused, nothing is recorded. When a client starts publishing
+         a stream, the recording starts (or resumes). If all clients disconnect from a session that
+         is being archived, the status changes to "paused", and after 60 seconds the archive
+         recording stops (and the status changes to "stopped").
        * "started" -- The archive started and is in the process of being recorded.
        * "stopped" -- The archive stopped recording.
        * "uploaded" -- The archive is available for download from the the upload target

opentok/opentok.py

@@ -42,7 +42,8 @@ class MediaModes(Enum):
     their streams will be relayed using the OpenTok TURN Server."""
 
 class ArchiveModes(Enum):
-    """List of valid settings for the archiveMode parameter of the OpenTok.createSession() method."""
+    """List of valid settings for the archive_mode parameter of the OpenTok.createSession()
+    method."""
     manual = u('manual')
     """The session will be manually archived."""
     always = u('always')
@@ -172,21 +173,21 @@ def create_session(self, location=None, media_mode=MediaModes.relayed, archive_m
         Calling this method results in an OpenTokException in the event of an error.
         Check the error message for details.
 
-        You can also create a session using the OpenTok REST API (see
-        http://www.tokbox.com/opentok/api/#session_id_production) or the OpenTok dashboard
-        (see https://dashboard.tokbox.com/projects).
+        You can also create a session using the OpenTok
+        `REST API <https://tokbox.com/opentok/api/#session_id_production>`_ or
+        `the OpenTok dashboard <https://dashboard.tokbox.com/projects>`_.
 
-        :param String mediaMode: Determines whether the session will transmit streams using the
+        :param String media_mode: Determines whether the session will transmit streams using the
              OpenTok Media Router (MediaMode.routed) or not (MediaMode.relayed). By default,
              the setting is MediaMode.relayed.
              
-             With the mediaMode property set to MediaMode.relayed, the session
+             With the media_mode property set to MediaMode.relayed, the session
              will attempt to transmit streams directly between clients. If clients cannot connect 
              due to firewall restrictions, the session uses the OpenTok TURN server to relay
              audio-video streams.
              
-             The OpenTok Media Router (see
-             https://tokbox.com/opentok/tutorials/create-session/#media-mode)
+             The `OpenTok Media
+             Router <https://tokbox.com/opentok/tutorials/create-session/#media-mode>`_
              provides the following benefits:
 
                * The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
@@ -203,12 +204,12 @@ def create_session(self, location=None, media_mode=MediaModes.relayed, archive_m
                * The OpenTok Media Router supports the archiving feature, which lets
                  you record, save, and retrieve OpenTok sessions (see http://tokbox.com/platform/archiving).
 
-         :param String archiveMode: Whether the session is automatically archived
-             (ArchiveMode.always) or not (ArchiveMode.manual). By default,
-             the setting is ArchiveMode.manual, and you must call the
-             start_archive() method of the OpenTok object to start archiving. To archive the session
-             (either automatically or not), you must set the mediaMode parameter to
-             MediaMode.routed.
+        :param String archive_mode: Whether the session is automatically archived
+            (ArchiveModes.always) or not (ArchiveModes.manual). By default,
+            the setting is ArchiveModes.manual, and you must call the
+            start_archive() method of the OpenTok object to start archiving. To archive the session
+            (either automatically or not), you must set the media_mode parameter to
+            MediaModes.routed.
 
         :param String location: An IP address that the OpenTok servers will use to
             situate the session in its global network. If you do not set a location hint,
@@ -285,29 +286,31 @@ def archive_url(self, archive_id=None):
 
     def start_archive(self, session_id, has_audio=True, has_video=True, name=None, output_mode=OutputModes.composed):
         """
-        Starts archiving an OpenTok 2.0 session.
+        Starts archiving an OpenTok session.
 
         Clients must be actively connected to the OpenTok session for you to successfully start
         recording an archive.
 
         You can only record one archive at a time for a given session. You can only record archives
-        of sessions that use the OpenTok Media Router (sessions witht the media mode set to routed);
-        you cannot archive sessions witht the media mode set to relayed.
+        of sessions that use the OpenTok Media Router (sessions with the media mode set to routed);
+        you cannot archive sessions with the media mode set to relayed.
+
+        For more information on archiving, see the
+        `OpenTok archiving <https://tokbox.com/opentok/tutorials/archiving/>`_ programming guide.
 
         :param String session_id: The session ID of the OpenTok session to archive.
         :param String name: This is the name of the archive. You can use this name
           to identify the archive. It is a property of the Archive object, and it is a property
           of archive-related events in the OpenTok.js library.
-        :param Boolean hasAudio: if set to True, an audio track will be inserted to the archive.
-          hasAudio is an optional parameter that is set to True by default. If you set both
-          hasAudio and hasVideo to False, the call to the start_archive() method results in
+        :param Boolean has_audio: if set to True, an audio track will be inserted to the archive.
+          has_audio is an optional parameter that is set to True by default. If you set both
+          has_audio and has_video to False, the call to the start_archive() method results in
           an error.
-        :param Boolean hasVideo: if set to True, a video track will be inserted to the archive.
-          hasVideo is an optional parameter that is set to True by default.
-        :param OutputModes outputMode: if set to composed, a single MP4 file composed of all streams
-          will be generated. If you set it to individual it will create a ZIP container with multiple
-          individual WEBM files and a JSON metadata file for video synchronization.
-          outputMode is an optional parameter that is set to composed by default.
+        :param Boolean has_video: if set to True, a video track will be inserted to the archive.
+          has_video is an optional parameter that is set to True by default.
+        :param OutputModes output_mode: Whether all streams in the archive are recorded
+          to a single file (OutputModes.composed, the default) or to individual files
+          (OutputModes.individual).
 
         :rtype: The Archive object, which includes properties defining the archive,
           including the archive ID.