Merge pull request #307 from opentok/dev

Release candidate, DVR/HLS

Author: SecondeJK

README.md

@@ -13,7 +13,7 @@ The OpenTok PHP SDK provides methods for:
 * Working with [OpenTok archives](https://tokbox.com/opentok/tutorials/archiving)
 * Working with [OpenTok live streaming broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/)
 * Working with [OpenTok SIP interconnect](https://tokbox.com/developer/guides/sip)
-* [Sending signals to clients connected to a session](https://www.tokbox.com/developer/guides/signaling/)
+* [Sending signals to clients connected to a session](https://tokbox.com/developer/guides/signaling/)
 * [Disconnecting clients from sessions](https://tokbox.com/developer/guides/moderation/rest/)
 * [Forcing clients in a session to disconnect or mute published audio](https://tokbox.com/developer/guides/moderation/)
 
@@ -278,19 +278,36 @@ You can only start live streaming broadcasts for sessions that use the OpenTok M
 Start the live streaming broadcast of an OpenTok Session using the
 `startBroadcast($sessionId, $options)` method of the `OpenTok\OpenTok` class.
 This will return an `OpenTok\Broadcast` instance. The `$options` parameter is
-an optional array used to assign broadcast options such as layout, maxDuration, resolution, and more.
+an array used to define the broadcast streams, assign broadcast options such as layout,
+maxDuration, resolution, and more.
 
 ```php
-// Start a live streaming broadcast of a session
-$broadcast = $opentok->startBroadcast($sessionId);
-
+// Define options for the broadcast
+$options = [
+  'layout' => Layout::getBestFit(),
+  'maxDuration' => 5400,
+  'resolution' => '1280x720',
+  'output' => [
+    'hls' => [
+      'dvr' => true,
+      'lowLatency' => false
+    ],
+    'rtmp' => [
+      [
+        'id' => 'foo',
+        'serverUrl' => 'rtmps://myfooserver/myfooapp',
+        'streamName' => 'myfoostream'
+      ],
+      [
+        'id' => 'bar',
+        'serverUrl' => 'rtmps://myfooserver/mybarapp',
+        'streamName' => 'mybarstream'
+      ],
+    ]
+  ]
+];
 
-// Start a live streaming broadcast of a session, using broadcast options
-$options = array(
-    'layout' => Layout::getBestFit(),
-    'maxDuration' => 5400,
-    'resolution' => '1280x720'
-);
+// Start a live streaming broadcast of a session
 $broadcast = $opentok->startBroadcast($sessionId, $options);
 
 // Store the broadcast ID in the database for later use
@@ -474,7 +491,7 @@ Reference documentation is available at
 ## Requirements
 
 You need an OpenTok API key and API secret, which you can obtain by logging into your
-[TokBox account](https://tokbox.com/account).
+[Vonage Video API account](https://tokbox.com/account).
 
 The OpenTok PHP SDK requires PHP 7.2 or higher.
 

src/OpenTok/Broadcast.php

@@ -35,6 +35,15 @@
 * @property boolean $isStopped
 * Whether the broadcast is stopped (true) or in progress (false).
 *
+* @property boolean $isHls
+* Whether the broadcast supports HLS.
+*
+* @property boolean $isDvr
+* Whether the broadcast supports DVR functionality for the HLS stream.
+*
+* @property boolean $isLowLatency
+* Whether the broadcast supports low-latency mode for the HLS stream.
+*
 * @property string $streamMode
 * Whether streams included in the broadcast are selected automatically (<code>StreamMode.AUTO</code>)
 * or manually (<code>StreamMode.MANUAL</code>). When streams are selected automatically (<code>StreamMode.AUTO</code>),
@@ -48,26 +57,35 @@
 */
 class Broadcast
 {
-    // NOTE: after PHP 5.3.0 support is dropped, the class can implement JsonSerializable
-
     /** @ignore */
     private $data;
     /** @ignore */
-    private $isStopped = false;
+    private $isStopped;
     /** @ignore */
     private $client;
+    /** @ignore */
+    private $isHls;
+    /** @ignore */
+    private $isLowLatency;
+    /** @ignore */
+    private $isDvr;
 
     /** @ignore */
     public function __construct($broadcastData, $options = array())
     {
         // unpack optional arguments (merging with default values) into named variables
+        // when adding these properties like this, it's worth noting that the method that
+        // starts a broadcast ALSO sets a load of defaults
         $defaults = array(
             'apiKey' => null,
             'apiSecret' => null,
             'apiUrl' => 'https://api.opentok.com',
             'client' => null,
             'isStopped' => false,
-            'streamMode' => StreamMode::AUTO
+            'streamMode' => StreamMode::AUTO,
+            'isHls' => true,
+            'isLowLatency' => false,
+            'isDvr' => false
         );
         $options = array_merge($defaults, array_intersect_key($options, $defaults));
         list($apiKey, $apiSecret, $apiUrl, $client, $isStopped, $streamMode) = array_values($options);
@@ -80,6 +98,9 @@ public function __construct($broadcastData, $options = array())
         $this->data = $broadcastData;
 
         $this->isStopped = $isStopped;
+        $this->isHls = isset($this->data['settings']['hls']);
+        $this->isLowLatency = $this->data['settings']['hls']['lowLatency'] ?? false;
+        $this->isDvr = $this->data['settings']['hls']['dvr'] ?? false;
 
         $this->client = isset($client) ? $client : new Client();
         if (!$this->client->isConfigured()) {
@@ -110,10 +131,17 @@ public function __get($name)
                 return $this->data['broadcastUrls']['hls'];
             case 'isStopped':
                 return $this->isStopped;
+            case 'isHls':
+                return $this->isHls;
+            case 'isLowLatency':
+                return $this->isLowLatency;
+            case 'isDvr':
+                return $this->isDvr;
             default:
                 return null;
         }
     }
+
     /**
      * Stops the broadcast.
      */

src/OpenTok/OpenTok.php

@@ -12,7 +12,7 @@
 * Contains methods for creating OpenTok sessions, generating tokens, and working with archives.
 * <p>
 * To create a new OpenTok object, call the OpenTok() constructor with your OpenTok API key
-* and the API secret for your <a href="https://tokbox.com/account">TokBox account</a>. Do not
+* and the API secret for your <a href="https://tokbox.com/account">OpenTok Video API account</a>. Do not
 * publicly share your API secret. You will use it with the OpenTok() constructor (only on your web
 * server) to create OpenTok sessions.
 * <p>
@@ -67,7 +67,7 @@ public function __construct($apiKey, $apiSecret, $options = array())
      * connecting to an OpenTok session, the client passes a token when connecting to the session.
      * <p>
      * For testing, you generate tokens or by logging in to your
-     * <a href="https://tokbox.com/account">TokBox account</a>.
+     * <a href="https://tokbox.com/account">OpenTok Video API account</a>.
      *
      * @param string $sessionId The session ID corresponding to the session to which the user
      * will connect.
@@ -152,7 +152,7 @@ public function generateToken($sessionId, $options = array())
     * Check the error message for details.
     * <p>
     * You can also create a session by logging in to your
-    * <a href="https://tokbox.com/account">TokBox account</a>.
+    * <a href="https://tokbox.com/account">OpenTok Video API account</a>.
     *
     * @param array $options (Optional) This array defines options for the session. The array includes
     * the following keys (all of which are optional):
@@ -625,7 +625,7 @@ public function disableForceMute(string $sessionId, array $options): bool
      *     Video Layout for the OpenTok live streaming feature</a>.
      *   </li>
      *
-     *    <li><code>'streamMode'</code> (String) &mdash; Whether streams included in the broadcast
+     *    <li><code>streamMode</code> (String) &mdash; Whether streams included in the broadcast
      *    are selected automatically (<code>StreamMode.AUTO</code>, the default) or manually
      *    (<code>StreamMode.MANUAL</code>). When streams are selected automatically
      *    (<code>StreamMode.AUTO</code>), all streams in the session can be included in the broadcast.
@@ -637,6 +637,36 @@ public function disableForceMute(string $sessionId, array $options): bool
      *    <a href="https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules">stream
      *    prioritization rules</a>.</li>
      *
+     *    <li><code>outputs</code> (Array) &mdash;
+     *      Defines the HLS broadcast and RTMP streams. You can provide the following keys:
+     *      <ul>
+     *        <li><code>hls</code> (Array) &mdash; available with the following options:
+     *          <p>
+     *            <ul>
+     *              <li><code>'dvr'</code> (Bool) &mdash; Whether to enable
+     *                <a href="https://tokbox.com/developer/guides/broadcast/live-streaming/#dvr">DVR functionality</a>
+     *                — rewinding, pausing, and resuming — in players that support it (<code>true</code>),
+     *                or not (<code>false</code>, the default). With DVR enabled, the HLS URL will include
+     *                a ?DVR query string appended to the end.
+     *              </li>
+     *              <li><code>'lowLatency'</code> (Bool) &mdash; Whether to enable
+     *                <a href="https://tokbox.com/developer/guides/broadcast/live-streaming/#low-latency">low-latency mode</a>
+     *                for the HLS stream. Some HLS players do not support low-latency mode. This feature
+     *                is incompatible with DVR mode HLS broadcasts.
+     *              </li>
+     *            </ul>
+     *           </p>
+     *        </li>
+     *        <li><code>rtmp</code> (Array) &mdash; An array of arrays defining RTMP streams to broadcast. You
+     *          can specify up to five target RTMP streams. Each RTMP stream array has the following keys:
+     *          <ul>
+     *            <li><code>id</code></code> (String) &mdash; The stream ID (optional)</li>
+     *            <li><code>serverUrl</code> (String) &mdash; The RTMP server URL</li>
+     *            <li><code>streamName</code> (String) &mdash; The stream name, such as
+     *                the YouTube Live stream name or the Facebook stream key</li>
+     *          </ul>
+     *        </li>
+     *      </ul>
      * </ul>
      *
      * @return Broadcast An object with properties defining the broadcast.
@@ -647,11 +677,28 @@ public function startBroadcast(string $sessionId, array $options = []): Broadcas
         // NOTE: although the server can be authoritative about the default value of layout, its
         // not preferred to depend on that in the SDK because its then harder to garauntee backwards
         // compatibility
-        $defaults = array(
+
+	    if (isset($options['output']['hls'])) {
+		    Validators::validateBroadcastOutputOptions($options['output']['hls']);
+	    }
+
+		if (isset($options['output']['rtmp'])) {
+			Validators::validateRtmpStreams($options['output']['rtmp']);
+		}
+
+        $defaults = [
             'layout' => Layout::getBestFit(),
-            'streamMode' => 'auto'
-        );
+            'streamMode' => 'auto',
+	        'output' => [
+				'hls' => [
+	                'dvr' => false,
+					'lowLatency' => false
+				]
+            ]
+        ];
+
         $options = array_merge($defaults, $options);
+
         list($layout, $streamMode) = array_values($options);
 
         // validate arguments

src/OpenTok/Session.php

@@ -120,7 +120,7 @@ public function __toString()
      * the client passes a token when connecting to the session.
      * <p>
      * For testing, you can also generate tokens or by logging in to your
-     * <a href="https://tokbox.com/account">TokBox account</a>.
+     * <a href="https://tokbox.com/account">OpenTok Video API account</a>.
      *
      * @param array $options This array defines options for the token. This array include the
      * following keys, all of which are optional:

src/OpenTok/Util/Client.php

@@ -38,7 +38,7 @@
 
 // TODO: build this dynamically
 /** @internal */
-define('OPENTOK_SDK_VERSION', '4.10.0');
+define('OPENTOK_SDK_VERSION', '4.11.0');
 /** @internal */
 define('OPENTOK_SDK_USER_AGENT', 'OpenTok-PHP-SDK/' . OPENTOK_SDK_VERSION);
 
@@ -628,7 +628,8 @@ public function dial($sessionId, $token, $sipUri, $options)
             'token' => $token,
             'sip' => array(
                 'uri' => $sipUri,
-                'secure' => $options['secure']
+                'secure' => $options['secure'],
+                'observeForceMute' => $options['observeForceMute']
             )
         );
 

src/OpenTok/Util/Validators.php

@@ -288,6 +288,7 @@ public static function validateOpenTok($opentok)
             );
         }
     }
+
     public static function validateBroadcastData($broadcastData)
     {
         if (!self::$broadcastSchemaUri) {
@@ -304,6 +305,14 @@ public static function validateBroadcastData($broadcastData)
             );
         }
     }
+
+    public static function validateRtmpStreams(array $rtmpData)
+    {
+        if (count($rtmpData) > 5) {
+            throw new InvalidArgumentException('The maximum permitted RTMP Streams is set to 5');
+        }
+    }
+
     public static function validateBroadcastId($broadcastId)
     {
         if (!is_string($broadcastId) || preg_match(self::$guidRegEx, $broadcastId)) {
@@ -312,6 +321,18 @@ public static function validateBroadcastId($broadcastId)
             );
         }
     }
+
+	public static function validateBroadcastOutputOptions(array $outputOptions)
+	{
+		if (
+			isset($outputOptions['lowLatency'], $outputOptions['dvr'])
+			&& $outputOptions['lowLatency'] === true && $outputOptions['dvr'] === true
+		) {
+			throw new InvalidArgumentException('When starting in HLS mode, DVR AND lowLatency
+			cannot both be true');
+		}
+	}
+
     public static function validateLayout($layout)
     {
         if (!($layout instanceof Layout)) {

tests/OpenTokTest/ArchiveTest.php

@@ -161,7 +161,7 @@ public function testStopsArchive()
         // TODO: test the dynamically built User Agent string
         $userAgent = $request->getHeaderLine('User-Agent');
         $this->assertNotEmpty($userAgent);
-        $this->assertStringStartsWith('OpenTok-PHP-SDK/4.10.0', $userAgent);
+        $this->assertStringStartsWith('OpenTok-PHP-SDK/4.11.0', $userAgent);
 
         // TODO: test the properties of the actual archive object
         $this->assertEquals('stopped', $this->archive->status);
@@ -278,7 +278,7 @@ public function testDeletesArchive()
         // TODO: test the dynamically built User Agent string
         $userAgent = $request->getHeaderLine('User-Agent');
         $this->assertNotEmpty($userAgent);
-        $this->assertStringStartsWith('OpenTok-PHP-SDK/4.10.0', $userAgent);
+        $this->assertStringStartsWith('OpenTok-PHP-SDK/4.11.0', $userAgent);
 
         $this->assertTrue($success);
         // TODO: assert that all properties of the archive object were cleared