Allow to prepare virtual participants without immediately joining the call

docs/Talkbuchet-cli.py

@@ -1296,6 +1296,12 @@ def endSiege(index = None):
         if removeVirtualParticipants:
             removeVirtualParticipants()
 
+        del globals()['prepareVirtualParticipant']
+        del globals()['prepareVirtualParticipants']
+        del globals()['startVirtualParticipants']
+        del globals()['startVirtualParticipantsParallel']
+        del globals()['stopVirtualParticipants']
+        del globals()['stopVirtualParticipantsParallel']
         del globals()['addVirtualParticipant']
         del globals()['addVirtualParticipants']
         del globals()['removeVirtualParticipant']
@@ -1352,6 +1358,13 @@ def switchToVirtualParticipantMode():
     "addVirtualParticipants(NUMBER)", setting the new parameters and calling
     "addVirtualParticipants(NUMBER)" again.
 
+    In case joining/leaving a call should be tested, it makes sense to use
+    "prepareVirtualParticipant()" / "prepareVirtualParticipants(NUMBER)" and
+    then start them with "startVirtualParticipants()" and stop them with
+    "stopVirtualParticipants()". In case joining/leaving should be done in
+    parallel one can use "startVirtualParticipantsParallel()" and
+    "stopVirtualParticipantsParallel()".
+
     Global functions provided for virtual participants only cover adding and
     removing them. Any specific action, like enabling or disabling media of a
     virtual participant, must be directly called on the Talkbuchet wrapper
@@ -1378,9 +1391,9 @@ def _isValidConfiguration():
 
         return True
 
-    def addVirtualParticipant():
+    def prepareVirtualParticipant():
         """
-        Adds a single virtual participant.
+        Prepares a single virtual participant.
 
         The global target Nextcloud URL and conversation token need to be set
         first.
@@ -1391,6 +1404,9 @@ def addVirtualParticipant():
         Note that changing any of those values later will have no effect on an
         existing virtual participant, the updated value will be used only by
         virtual participants added after they were changed.
+
+        This method just prepares a virtual participant, but does not start it.
+        See :py:func:`addVirtualParticipant` as an alternative.
         """
 
         if not _isValidConfiguration():
@@ -1408,6 +1424,112 @@ def addVirtualParticipant():
         if _audio or _video:
             virtualParticipant.startMedia(_audio, _video)
 
+        return virtualParticipant
+
+    def prepareVirtualParticipants(count):
+        """
+        Prepares as many virtual participants as the given count.
+
+        See :py:func:`prepareVirtualParticipant`.
+
+        :param count: the number of virtual participants to prepare.
+        """
+
+        if not _isValidConfiguration():
+            return
+
+        for i in range(count):
+            prepareVirtualParticipant()
+
+            print('.', end='', flush=True)
+
+        print("")
+
+    def startVirtualParticipants():
+        """
+        Starts all virtual participants which are prepared.
+
+        Note that there is no check if a virtual participant was already started
+        before. The result of starting again a virtual participant before
+        stopping it first is undefined, no matter if the virtual participant was
+        started with any of the "startVirtualParticipants" or
+        "addVirtualParticipant" variants.
+
+        See :py:func:`prepareVirtualParticipant`.
+        """
+        for virtualParticipant in virtualParticipants:
+            virtualParticipant.startVirtualParticipant()
+
+    def startVirtualParticipantsParallel():
+        """
+        Starts all virtual participants.
+
+        Same as :py:func:`startVirtualParticipants`, but starting each virtual
+        participant in parallel.
+
+        This method returns before the virtual participants were fully started,
+        so it should be ensured that starting them finished before starting more
+        virtual participants or stopping them.
+        """
+
+        for virtualParticipant in virtualParticipants:
+            startThread = threading.Thread(target=virtualParticipant.startVirtualParticipant)
+            startThread.start()
+
+    def stopVirtualParticipants():
+        """
+        Stops all virtual participants.
+
+        The participants are not removed and can be started again.
+        See :py:func:`prepareVirtualParticipant`.
+
+        Note that there is no check if a virtual participant was started/stopped
+        before.
+
+        See :py:func:`prepareVirtualParticipant`.
+        """
+
+        for virtualParticipant in virtualParticipants:
+            virtualParticipant.stopVirtualParticipant()
+
+    def stopVirtualParticipantsParallel():
+        """
+        Stops all virtual participants.
+
+        Same as :py:func:`stopVirtualParticipants`, but stopping each virtual
+        participant in parallel.
+
+        This method returns before the virtual participants were fully stopped,
+        so it should be ensured that stopping them finished before starting or
+        stopping them again.
+        """
+
+        for virtualParticipant in virtualParticipants:
+            stopThread = threading.Thread(target=virtualParticipant.stopVirtualParticipant)
+            stopThread.start()
+
+    def addVirtualParticipant():
+        """
+        Adds a single virtual participant.
+
+        The global target Nextcloud URL and conversation token need to be set
+        first.
+
+        If global credentials or media were set they will be applied to the
+        virtual participant.
+
+        Note that changing any of those values later will have no effect on an
+        existing virtual participant, the updated value will be used only by
+        virtual participants added after they were changed.
+
+        This method prepares a participant and immediately starts it.
+        """
+
+        if not _isValidConfiguration():
+            return
+
+        virtualParticipant = prepareVirtualParticipant()
+
         virtualParticipant.startVirtualParticipant()
 
     def addVirtualParticipants(count):
@@ -1471,6 +1593,12 @@ def removeVirtualParticipants():
         del globals()['removeRealParticipant']
         del globals()['removeRealParticipants']
 
+    globals()['prepareVirtualParticipant'] = prepareVirtualParticipant
+    globals()['prepareVirtualParticipants'] = prepareVirtualParticipants
+    globals()['startVirtualParticipants'] = startVirtualParticipants
+    globals()['startVirtualParticipantsParallel'] = startVirtualParticipantsParallel
+    globals()['stopVirtualParticipants'] = stopVirtualParticipants
+    globals()['stopVirtualParticipantsParallel'] = stopVirtualParticipantsParallel
     globals()['addVirtualParticipant'] = addVirtualParticipant
     globals()['addVirtualParticipants'] = addVirtualParticipants
     globals()['removeVirtualParticipant'] = removeVirtualParticipant
@@ -1607,6 +1735,12 @@ def removeRealParticipants():
         if removeVirtualParticipants:
             removeVirtualParticipants()
 
+        del globals()['prepareVirtualParticipant']
+        del globals()['prepareVirtualParticipants']
+        del globals()['startVirtualParticipants']
+        del globals()['startVirtualParticipantsParallel']
+        del globals()['stopVirtualParticipants']
+        del globals()['stopVirtualParticipantsParallel']
         del globals()['addVirtualParticipant']
         del globals()['addVirtualParticipants']
         del globals()['removeVirtualParticipant']