# Manage scenes (/en/realtime-media/whiteboard/build/display-files-and-manage-scenes/scenes/manage-scenes)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Once you understand the scene structure and identification as well as the rules for adding, deleting, and changing scenes, you can call APIs of the Whiteboard SDK to manage scenes and build multi-scene whiteboard applications according to your business needs.

This feature is for Web only.

This page describes how to call APIs provided by the Whiteboard SDK to get scene information, insert new scenes, switch, move, and delete scenes, and clear all the contents of a scene.

## Understand the tech [#understand-the-tech]

The Whiteboard SDK provides the following methods in the `Room` interface for managing scenes:

| Methods                                                 | Description                                                        |
| :------------------------------------------------------ | :----------------------------------------------------------------- |
| [`SceneState`](/en/api-reference/whiteboard/web)        | Gets the information of the currently displayed scene.             |
| [`entireScenes`](/en/api-reference/whiteboard/web)      | Gets the information of all scenes in the current room.            |
| [`scenePathType`](/en/api-reference/whiteboard/web)     | Gets the type of the scene path.                                   |
| [`putScenes`](/en/api-reference/whiteboard/web)         | Inserts multiple scenes under the specified scene directory.       |
| [`setScenePath`](/en/api-reference/whiteboard/web)      | Switches to the specified scene.                                   |
| [`setSceneIndex`](/en/api-reference/whiteboard/web)     | Switches to the specified scene under the current scene directory. |
| [`moveScene`](/en/api-reference/whiteboard/web)         | Moves or renames a scene.                                          |
| [`removeScenes`](/en/api-reference/whiteboard/web)      | Deletes a scene or a scene directory.                              |
| [`cleanCurrentScene`](/en/api-reference/whiteboard/web) | Clears all contents on the current scene.                          |

## Prerequisites [#prerequisites]

To follow the procedure on this page, ensure that you have integrated the Whiteboard SDK into your project and implemented joining a room. For details, see [Join the Whiteboard Room](../../set-up-and-build-your-first-app/get-started-uikit/#join-the-whiteboard-room).

The following section extends the [Join the Whiteboard Room](../../set-up-and-build-your-first-app/get-started-uikit/#join-the-whiteboard-room) sample code to show the implementation of scene management.

## Implement scene management [#implement-scene-management]

### Get scene information [#get-scene-information]

After successfully joining the whiteboard room, you can call the following methods to get the scene information:

* `SceneState`: Gets the information of the scene that is currently displayed on the whiteboard. The information includes the scene path, name, and index.
* `entireScenes`: Gets the information of all scenes in the current room.

For example, to get the information of the current scene, you can add the following lines to the `joinWhiteboard.js` file:

```javascript
whiteWebSdk.joinRoom(joinRoomParams).then(function(room) {

    room.bindHtmlElement(document.getElementById("whiteboard"));

    // Add the following code to get the path, name, and index of the current scene.
    var sceneState = room.state.sceneState;
    console.log("scene path:", sceneState.scenePath);
    console.log("scene name:", sceneState.sceneName);
    console.log("scene index:", sceneState.index);

}).catch(function(err) {

    console.error(err);
});
```

Save the changes, refresh the `index.html` page, and open the console of your browser. You can see the following information on the console:

```json
[White] join room success
scene path: /init
scene name: init
scene index: 0
```

In a newly created whiteboard room, there is only one default initial scene, whose path is `/init`, name is `init`, and index is `0`.

### Add scenes [#add-scenes]

The Whiteboard SDK provides the `putScenes` method to insert new scenes in a specified scene directory and display images or web pages on scenes.

When calling `putScenes`, you need to pass in the following parameters:

* `path`: The path of a scene directory, which must start with `/` and cannot be the path of a scene.

* `scenes`: An array of scenes. A single scene contains the following fields:

  * `name`: Name of the scene.
  * `ppt`: (Optional) The image or web page to be displayed in the scene. Each scene can display only one image or web page. You can also use [`PptDescription`](/en/api-reference/whiteboard/web).

* `index`: (Optional) The index number of the first scene to be inserted in the scene directory. The index numbers of subsequent scenes increase sequentially. The index number of a scene starts from 0.

For example, add the following lines to the `joinWhiteboard.js` file to insert two new scenes in the root scene directory (`new-page5`, which has an image, and `new-page6`, which is blank):

```javascript
whiteWebSdk.joinRoom(joinRoomParams)
	.then(function(room) {

		room.bindHtmlElement(document.getElementById("whiteboard"));
		// Create new scenes and insert them to the specified scene directory.
		var scenes = [{
				name: "new-page5",
				ppt: {
					width: 720,
					height: 640,
					src: "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"
				}
			},
			{
				name: "new-page6"
			},
		]
		room.putScenes("/", scenes);

		// Output a list of all scenes in the room.
		var scenemap = room.entireScenes();
		console.log("scene map:", scenemap);

	})
	.catch(function(err) {

		console.error(err);
	});
```

Save the changes and refresh the `index.html` page. You can see the following information on the browser's console:

```json
{
    "/": [
        {name: "init", ppt: undefined},
        {name: "new-page5", ppt: {width: 720, height: 640, src: "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"}},
        {name: "new-page6", ppt: undefined},
    ],
}
```

However, after calling `putScenes` to insert new scenes, the SDK does not directly switch to the newly inserted scene. You need to call `setScenePath` or `setSceneIndex` to switch to a specified scene.

### Switch scenes [#switch-scenes]

The Whiteboard SDK provides the following methods to switch scenes:

* `setScenePath`: Switches to a scene by specifying the path of the scene. This method can switch to any scene in the current room.
* `setSceneIndex`: Switches to a scene by specifying the index number of the scene. This method can only switch to a scene in the current scene directory.

Now you can call the two methods to switch to the new scenes inserted in the [Add scenes](#add-scenes) section.

To switch to `new-page5` by specifying its path, add the following line after `room.putScenes("/", scenes);` in the previous example code:

```javascript
room.setScenePath("/new-page5");
```

After saving the changes and refreshing the `index.html` page, you can see the new scene with an image on the whiteboard. The information of the current scene output on the console is as follows:

```json
[White] join room success
scene path: /new-page5
scene name: new-page5
scene index: 1
```

You can call `setSceneIndex` and pass in index number `2` to switch to scene `new-page6`:

```javascript
room.setSceneIndex(2);
```

Save the changes and refresh the `index.html` page. You can see the blank new scene display in the whiteboard room. You can also check the current scene information on the console to verify the switch is successful.

### Move scenes [#move-scenes]

You can call `moveScene` and pass in the original scene path and the target scene path to move a scene or rename a scene.

For example, to move the `new-page5` scene to a new scene directory, `SceneC`, add the following code after `room.putScenes("/", scenes);`:

```javascript
room.moveScene("/new-page5", "/sceneC/new-page5");
```

After saving the changes and refreshing the `index.html` page, you can see the following information under the `scene map` section on the browser's console:

```json
{
    "/": [
        {name: "init", ppt: undefined},
        {name: "new-page6", ppt: undefined},
    ],
    "/sceneC": [
        {name: "new-page5", ppt: {width: 720, height: 640, src: "https://docs-test-xxx.oss-cn-hangzhou.aliyuncs.com/staticPic/2fdxxx67e/1.jpeg"}},
    ],
}
```

This information shows that `new-page5` is successfully moved to `sceneC`.

To rename a scene, keep the scene directories unchanged and only change the scene name in the target scene path. For example, to rename `new-page5` to `new-page7`, add the following code:

```javascript
room.moveScene("/new-page5", "/new-page7");
```

### Clear the contents of a scene [#clear-the-contents-of-a-scene]

You can call `cleanCurrentScene` to clear all contents on the current scene. This method does not clear the image or web page displayed on the scene by default, however. If you need to clear the image or web page as well, call `cleanCurrentScene(false)`.

For example, add the following code in the `joinWhiteboard.js` file to clear the current scene:

```javascript
room.cleanCurrentScene();
```

After saving the changes and refreshing the `index.html` page, you can see the scene is cleared.

### Delete scenes [#delete-scenes]

You can call `removeScenes` and pass in the path of a scene or a scene directory to delete a scene or all scenes under a scene directory.

For example, to remove all scenes under the root scene directory, add the following code in the `joinWhiteboard.js` file:

```javascript
room.removeScenes("/");
```

Save the changes and refresh the `index.html` page. Check the `scene map` information output on the browser's console and you can see there is only one scene with the path `/init` in the room. This is the scene the SDK creates automatically after all scenes in the room are deleted.

## Reference [#reference]

Once you grasp the basic operations of scenes, you can refer to [Display Files](./display-files-white) for instructions on creating a set of scenes to display a complete file.