Feature/manual stream mode minimal (#291)

* Minimal changes to implement and test streammode

* Add the new response for manual mode

* Added streamMode enum object for better validation

* Take out offending lines in tests that will not pass on CI but aren't related to what we're testing

* New methods for being able to add and remove streams from manual mode broadcasts and archives

* Fix missing terminator

* Added tests for stream mode, php8.1 compatibility, fixed client call to encode payload

* Reference docs edits for selective stream archive/broadcast enhancements

* Readme edits

Co-authored-by: Jeff Swartz <[email protected]>

Author: SecondeJK

README.md

@@ -4,13 +4,18 @@
 
 <img src="https://assets.tokbox.com/img/vonage/Vonage_VideoAPI_black.svg" height="48px" alt="Tokbox is now known as Vonage" />
 
-The OpenTok PHP SDK lets you generate [sessions](http://tokbox.com/developer/guides/create-session/) and
-[tokens](http://tokbox.com/developer/guides/create-token/) for [OpenTok](http://www.tokbox.com/)
-applications, and [archive](http://tokbox.com/developer/guides/archiving/) sessions.
-It also includes methods for working with OpenTok
-[archives](http://tokbox.com/developer/guides/archiving), working with OpenTok
-[SIP interconnect](http://tokbox.com/developer/guides/sip), and
-[disconnecting clients from sessions](http://tokbox.com/developer/guides/moderation/rest/).
+The OpenTok PHP SDK provides methods for:
+
+* Generating
+[sessions](https://tokbox.com/developer/guides/create-session/) and
+[tokens](https://tokbox.com/developer/guides/create-token/) for
+[OpenTok](https://www.tokbox.com/) applications that run on the .NET platform
+* 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/)
+* [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/)
 
 ## Installation
 
@@ -370,6 +375,17 @@ use OpenTok\OpenTok;
 $opentok->forceDisconnect($sessionId, $connectionId);
 ```
 
+### Forcing clients in a session mute published audio
+
+You can force the publisher of a specific stream to stop publishing audio using the 
+`Opentok.forceMuteStream($sessionId, $stream)` method.
+
+You can force the publisher of all streams in a session (except for an optional list of streams)
+to stop publishing audio using the `Opentok.forceMuteAll($sessionId, $excludedStreamIds)` method.
+You can then disable the mute state of the session by calling the
+`Opentok.DisableForceMute(sessionId)` or `Opentok.DisableForceMuteAsync(sessionId)`
+method.
+
 ### Sending Signals
 
 Once a Session is created, you can send signals to everyone in the session or to a specific connection.

src/OpenTok/Archive.php

@@ -49,6 +49,17 @@
 * @property string $size
 * The size of the MP4 file. For archives that have not been generated, this value is set to 0.
 *
+* @property string $streamMode
+* Whether streams included in the archive are selected automatically (<code>StreamMode.AUTO</code>) 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 archive. When streams are selected manually
+* (<code>StreamMode.MANUAL</code>), you specify streams to be included based on calls to the
+* <code>Archive.addStreamToArchive()</code> and <code>Archive.removeStreamFromArchive()</code> methods.
+* With manual mode, you can specify whether a stream's audio, video, or both are included in the
+* archive. In both automatic and manual modes, the archive composer includes streams based on
+* <a href="https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules">stream
+* prioritization rules</a>.
+*
 * @property string $status
 * The status of the archive, which can be one of the following:
 *
@@ -95,14 +106,16 @@ public function __construct($archiveData, $options = array())
             'apiKey' => null,
             'apiSecret' => null,
             'apiUrl' => 'https://api.opentok.com',
-            'client' => null
+            'client' => null,
+            'streamMode' => StreamMode::AUTO
         );
         $options = array_merge($defaults, array_intersect_key($options, $defaults));
-        list($apiKey, $apiSecret, $apiUrl, $client) = array_values($options);
+        list($apiKey, $apiSecret, $apiUrl, $client, $streamMode) = array_values($options);
 
         // validate params
         Validators::validateArchiveData($archiveData);
         Validators::validateClient($client);
+        Validators::validateHasStreamMode($streamMode);
 
         $this->data = $archiveData;
 
@@ -137,6 +150,7 @@ public function __get($name)
             case 'hasAudio':
             case 'outputMode':
             case 'resolution':
+            case 'streamMode':
                 return $this->data[$name];
             default:
                 return null;
@@ -202,6 +216,65 @@ public function toJson()
         return json_encode($this->jsonSerialize());
     }
 
+    /**
+     * Adds a stream to a currently running archive that was started with the
+     * the <code>streamMode</code> set to <code>StreamMode.Manual</code>. You can call the method
+     * repeatedly with the same stream ID, to toggle the stream's audio or video in the archive.
+     * 
+     * @param String $streamId The stream ID.
+     * @param Boolean $hasAudio Whether the archive should include the stream's audio (true, the default)
+     * or not (false).
+     * @param Boolean $hasVideo Whether the archive should include the stream's video (true, the default)
+     * or not (false).
+     *
+     * @return Boolean Returns true on success.
+     */
+    public function addStreamToArchive(string $streamId, bool $hasAudio, bool $hasVideo): bool
+    {
+        if ($this->streamMode === StreamMode::AUTO) {
+            throw new InvalidArgumentException('Cannot add stream to an Archive in auto stream mode');
+        }
+
+        if ($hasAudio === false && $hasVideo === false) {
+            throw new InvalidArgumentException('Both hasAudio and hasVideo cannot be false');
+        }
+
+        if ($this->client->addStreamToArchive(
+            $this->data['id'],
+            $streamId,
+            $hasVideo,
+            $hasVideo
+        )) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Removes a stream from a currently running archive that was started with the
+     * the <code>streamMode</code> set to <code>StreamMode.Manual</code>.
+     * 
+     * @param String $streamId The stream ID.
+     *
+     * @return Boolean Returns true on success.
+     */
+    public function removeStreamFromArchive(string $streamId): bool
+    {
+        if ($this->streamMode === StreamMode::AUTO) {
+            throw new InvalidArgumentException('Cannot remove stream to an Archive in auto stream mode');
+        }
+
+        if ($this->client->removeStreamFromArchive(
+            $this->data['id'],
+            $streamId
+        )) {
+            return true;
+        }
+
+        return false;
+    }
+
     /**
      * Returns an associative array representation of this Archive object.
      * @deprecated 3.0.0 A more standard name for this method is supplied by JsonSerializable

src/OpenTok/ArchiveMode.php

@@ -17,10 +17,10 @@ abstract class ArchiveMode extends BasicEnum
      * The session is not archived automatically. To archive the session, you can call the
      * \OpenTok\OpenTok->startArchive() method.
      */
-    const MANUAL = 'manual';
+    public const MANUAL = 'manual';
     /**
      * The session is archived automatically (as soon as there are clients connected
      * to the session).
      */
-    const ALWAYS = 'always';
+    public const ALWAYS = 'always';
 }

src/OpenTok/Broadcast.php

@@ -34,6 +34,17 @@
 *
 * @property boolean $isStopped
 * Whether the broadcast is stopped (true) or in progress (false).
+*
+* @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>),
+* all streams in the session can be included in the broadcast. When streams are selected manually
+* (<code>StreamMode.MANUAL</code>), you specify streams to be included based on calls to the
+* <code>Broadcast.addStreamToBroadcast()</code> and <code>Broadcast.removeStreamFromBroadcast()</code> methods.
+* With manual mode, you can specify whether a stream's audio, video, or both are included in the
+* broadcast. In both automatic and manual modes, the broadcast composer includes streams based on
+* <a href="https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules">stream
+* prioritization rules</a>.
 */
 class Broadcast
 {
@@ -55,14 +66,16 @@ public function __construct($broadcastData, $options = array())
             'apiSecret' => null,
             'apiUrl' => 'https://api.opentok.com',
             'client' => null,
-            'isStopped' => false
+            'isStopped' => false,
+            'streamMode' => StreamMode::AUTO
         );
         $options = array_merge($defaults, array_intersect_key($options, $defaults));
-        list($apiKey, $apiSecret, $apiUrl, $client, $isStopped) = array_values($options);
+        list($apiKey, $apiSecret, $apiUrl, $client, $isStopped, $streamMode) = array_values($options);
 
         // validate params
         Validators::validateBroadcastData($broadcastData);
         Validators::validateClient($client);
+        Validators::validateHasStreamMode($streamMode);
 
         $this->data = $broadcastData;
 
@@ -91,6 +104,7 @@ public function __get($name)
             case 'status':
             case 'maxDuration':
             case 'resolution':
+            case 'streamMode':
                 return $this->data[$name];
             case 'hlsUrl':
                 return $this->data['broadcastUrls']['hls'];
@@ -149,6 +163,65 @@ public function updateLayout($layout)
         $this->client->updateLayout($this->id, $layout, 'broadcast');
     }
 
+    /**
+     * Adds a stream to a currently running broadcast that was started with the
+     * the <code>streamMode</code> set to <code>StreamMode.Manual</code>. You can call the method
+     * repeatedly with the same stream ID, to toggle the stream's audio or video in the broadcast.
+     * 
+     * @param String $streamId The stream ID.
+     * @param Boolean $hasAudio Whether the broadcast should include the stream's audio (true, the default)
+     * or not (false).
+     * @param Boolean $hasVideo Whether the broadcast should include the stream's video (true, the default)
+     * or not (false).
+     *
+     * @return Boolean Returns true on success.
+     */
+    public function addStreamToBroadcast(string $streamId, bool $hasAudio, bool $hasVideo): bool
+    {
+        if ($this->streamMode === StreamMode::AUTO) {
+            throw new InvalidArgumentException('Cannot add stream to a Broadcast in auto stream mode');
+        }
+
+        if ($hasAudio === false && $hasVideo === false) {
+            throw new InvalidArgumentException('Both hasAudio and hasVideo cannot be false');
+        }
+
+        if ($this->client->addStreamToBroadcast(
+            $this->data['id'],
+            $streamId,
+            $hasVideo,
+            $hasVideo
+        )) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Removes a stream from a currently running broadcast that was started with the
+     * the <code>streamMode</code> set to <code>StreamMode.Manual</code>.
+     * 
+     * @param String $streamId The stream ID.
+     *
+     * @return Boolean Returns true on success.
+     */
+    public function removeStreamFromBroadcast(string $streamId): bool
+    {
+        if ($this->streamMode === StreamMode::AUTO) {
+            throw new InvalidArgumentException('Cannot remove stream from a Broadcast in auto stream mode');
+        }
+
+        if ($this->client->removeStreamFromBroadcast(
+            $this->data['id'],
+            $streamId
+        )) {
+            return true;
+        }
+
+        return false;
+    }
+
     public function jsonSerialize()
     {
         return $this->data;

src/OpenTok/Layout.php

@@ -140,6 +140,7 @@ public function setScreenshareType(string $screenshareType): Layout
         throw new \RuntimeException('Screenshare type cannot be set on a layout type other than bestFit');
     }
 
+    #[\ReturnTypeWillChange]
     public function jsonSerialize()
     {
         return $this->toArray();

src/OpenTok/OpenTok.php

@@ -283,6 +283,18 @@ public function createSession($options = array())
      *    <code>hasVideo</code> to false, the call to the <code>startArchive()</code> method results
      *    in an error.</li>
      *
+     *    <li><code>'streamMode'</code> (String) &mdash; Whether streams included in the archive 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 archive.
+     *    When streams are selected manually (<code>StreamMode.MANUAL</code>), you specify streams
+     *    to be included based on calls to the <code>Archive.addStreamToArchive()</code> and
+     *    <code>Archive.removeStreamFromArchive()</code>. methods. With manual mode, you can specify
+     *    whether a stream's audio, video, or both are included in the archive. In both automatic and
+     *    manual modes, the archive composer includes streams based on
+     *    <a href="https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules">stream
+     *    prioritization rules</a>.</li>
+     *
      *    <li><code>'hasAudio'</code> (Boolean) &mdash; Whether the archive will record audio
      *    (true, the default) or not (false). If you set both <code>hasAudio</code> and
      *    <code>hasVideo</code> to false, the call to the <code>startArchive()</code> method results
@@ -315,15 +327,17 @@ public function startArchive(string $sessionId, $options = []): Archive
             'hasAudio' => true,
             'outputMode' => OutputMode::COMPOSED,
             'resolution' => null,
+            'streamMode' => StreamMode::AUTO
         );
         $options = array_merge($defaults, array_intersect_key($options, $defaults));
-        list($name, $hasVideo, $hasAudio, $outputMode, $resolution) = array_values($options);
+        list($name, $hasVideo, $hasAudio, $outputMode, $resolution, $streamMode) = array_values($options);
         // validate arguments
         Validators::validateSessionId($sessionId);
         Validators::validateArchiveName($name);
         Validators::validateArchiveHasVideo($hasVideo);
         Validators::validateArchiveHasAudio($hasAudio);
         Validators::validateArchiveOutputMode($outputMode);
+        Validators::validateHasStreamMode($streamMode);
 
         if ((is_null($resolution) || empty($resolution)) && $outputMode === OutputMode::COMPOSED) {
             $options['resolution'] = "640x480";
@@ -598,6 +612,19 @@ public function disableForceMute(string $sessionId, array $options): bool
      *     <a href="https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-live-streaming-video-layout">Configuring
      *     Video Layout for the OpenTok live streaming feature</a>.
      *   </li>
+     *
+     *    <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.
+     *    When streams are selected manually (<code>StreamMode.MANUAL</code>), you specify streams
+     *    to be included based on calls to the <code>Broadcast.addStreamToBroadcast()</code> and
+     *    <code>Broadcast.removeStreamFromBroadcast()</code> methods. With manual mode, you can specify
+     *    whether a stream's audio, video, or both are included in the broadcast. In both automatic and
+     *    manual modes, the broadcast composer includes streams based on
+     *    <a href="https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules">stream
+     *    prioritization rules</a>.</li>
+     *
      * </ul>
      *
      * @return Broadcast An object with properties defining the broadcast.
@@ -609,14 +636,16 @@ public function startBroadcast(string $sessionId, array $options = []): Broadcas
         // not preferred to depend on that in the SDK because its then harder to garauntee backwards
         // compatibility
         $defaults = array(
-            'layout' => Layout::getBestFit()
+            'layout' => Layout::getBestFit(),
+            'streamMode' => 'auto'
         );
         $options = array_merge($defaults, $options);
-        list($layout) = array_values($options);
+        list($layout, $streamMode) = array_values($options);
 
         // validate arguments
         Validators::validateSessionId($sessionId);
         Validators::validateLayout($layout);
+        Validators::validateHasStreamMode($streamMode);
 
         // make API call
         $broadcastData = $this->client->startBroadcast($sessionId, $options);

src/OpenTok/StreamMode.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace OpenTok;
+
+use OpenTok\Util\BasicEnum;
+
+/**
+ * Defines streamMode values that can be used when either starting an Archive or a Broadcast
+ */
+abstract class StreamMode extends BasicEnum
+{
+    /**
+     * Default mode, will automatically add all streams to Archive or Broadcast
+     */
+    public const AUTO = 'auto';
+
+    /**
+     * Manual mode, will allow for manual adding and removal of streams for an Archive or Broadcast
+     */
+    public const MANUAL = 'manual';
+}