Method RemoveAsync

Namespace: OBSStudioClient.Model

Assembly: OBSClient.dll

RemoveAsync(CancellationToken)

Removes the scene, and the scene items that show it in other scenes, and returns when the model shows it.

public Task RemoveAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken: A token that ends the wait. A change that was not sent yet is not sent.

Returns

Task: A task that completes when the scene is removed (State is not Live) and the scene items that were showing it are gone.

Remarks

OBS Studio keeps a scene alive after it is removed for as long as scene items in other scenes show it (the scene is Detached: it is not in Scenes and it can not be changed; with OBS Studio 31.0 and older its name stays taken, and OBS Studio 31.1 and newer free the name at once). This call removes those scene items too, so that OBS Studio destroys the scene (Gone). The scene is removed first, and the scene items after it, one request after the other: when OBS Studio refuses one of the scene items (it was removed meanwhile: by the user, or by OBS Studio itself, which takes the scene items of a removed scene out of the scenes that it is rendering on the next frame), the call ends with the exception once the model shows what the requests before it made (the scene is Detached, and the scene items that were removed are gone), so that calling RemoveAsync(CancellationToken) again removes what is left. A scene that a scene item shows that the model did not know yet (OBS Studio announces it a few milliseconds late) stays Detached in the same way.

The call returns when the model shows the scene removed and the scene items that showed it gone, and the scene can still be Detached at that moment: OBS Studio destroys it when the last of those scene items is gone, and the model learns of that from an event of OBS Studio. When the events are slower than the confirmation time of the options (they can be, on a busy machine) the model learns that the scene items are gone from a read instead, which is ahead of the events, so it reads OBS Studio once more to be sure that it destroyed the scene: the scene is Gone a moment after the call returned. Wait for that when what follows needs the scene to be destroyed (PropertyChanged is raised for State, and Changed for StateChanged).

What the scene shows is destroyed with it: the inputs that only this scene showed are destroyed by OBS Studio a moment after the scene, and the model learns of that from its events. If this call removes the scene (a scene that is Detached already has no such wait: the model learns from the events of OBS Studio which scene is the program scene now) and the scene is the program scene, OBS Studio makes another scene the program scene about one frame after it has answered (16 ms were measured, and a read of the program scene in between still says the scene that was removed): the call returns when the model shows that scene as the program scene, so that ProgramScene is the scene that OBS Studio has now. The model is read for that after the answer whatever the events said, also when a switch to this scene was asked for just before and the model did not show it yet. When the events do not show it within the confirmation time of the options (1 second by default) the model is read again, and the call returns when that read has been applied, whatever it shows (the model goes on following OBS Studio by its events); when no read is applied in time (the read timeout of the options, 10 seconds by default, counts twice, after the confirmation time) the call returns all the same, with a warning in the log. See SetEnabledAsync(bool, CancellationToken) for the order of changes and the wait.

A scene that is Detached because a list of scenes did not have it, while no event of OBS Studio removed it, can still be a live scene in OBS Studio (OBS Studio makes that list from its user interface, which can be busy for seconds, right after it was started for one). The call asks OBS Studio to remove such a scene first, and then removes the scene items that show it. A scene that OBS Studio removed already and keeps alive for a scene item refuses that request (701 with OBS Studio 33.0.0), and that is taken for the answer: the scene items are removed all the same. A scene that OBS Studio does not have at all (600) ends the call with ObsRemovedException. A scene that the model only knows as the source of a scene item was never seen live, and is taken for removed. The two steps are two changes in the line of changes (see SetEnabledAsync(bool, CancellationToken)): a change that you ask for right after this call is made between them, not after both.

Exceptions

InvalidOperationException: The scene is a group (IsGroup): remove the scene item that shows it. Or a scene item in a group shows the scene: obs-websocket removes the scene items of scenes only, not those of a group, so the scene can not be removed for good from here (take it out of the group in OBS Studio first); nothing was changed.
ObsRemovedException: The scene does not exist any more.
ObsNotConnectedException: There is no connection to OBS Studio. Nothing was changed.
ObsNotReadyException: OBS Studio is changing its scene collection, or did so after the call. Nothing was changed.
ObsUnknownOutcomeException: OBS Studio did not answer in time, or the connection ended: it is not known whether it made the change.
ObsNotConfirmedException: OBS Studio made the change, and the model does not show it. Do not send the change again.
ObsResponseException: OBS Studio refused the change (it does not remove the last scene of a collection).