# Create an immersive school lesson

Build an immersive school lesson in TholusOS Studio with scenes, age groups, languages, video, audio, reliable sources and practical facilitator instructions.

Canonical: https://docs.theusualnext.com/en/tholusos/schools/create-lesson/
Updated: 2026-10-22
Publisher: the usual neXt

TholusOS Studio organizes an immersive school lesson into scenes, media and facilitator actions. One project can serve different school groups and languages, combining films, observation, questions and choices. Save the resulting `.tholus` project, check its active version and rehearse it before preparing the room session.

Guided Studio currently carries a **Beta** label. Complete its story checks and rehearsal before using a lesson at an event.

## What to prepare first

Define your audience, learning objective, timing and available materials. A lesson becomes easier to build when you know what pupils should observe or do, and what action ends each activity.

You need TholusOS with Studio access, a writable project location and the files you plan to use. Local rehearsal requires a licence that enables Event Runtime. An account project also requires your Tholus Account; local files can be used for initial authoring.

Prepare a short brief covering:

- the school group, prior knowledge and language;
- a central question and a few observable learning objectives;
- film duration, discussion time, and time for entering and leaving the room;
- images, video, audio, their sources and permitted uses;
- the facilitator’s words and actions, expected responses and progressive hints.

For example, a lesson about shadows might ask pupils to predict a change, observe two lighting conditions and explain the difference. Each moment needs a recognizable visual and a clear instruction. This planning method also works in planetariums and immersive classrooms using other presentation systems.

## Open and save the project

Open **Studio → Guided experiences → Open the Studio**. The dedicated Studio window contains the project; its **Studio** menu provides creation, opening and saving commands.

1. Choose **Studio → New experience**, or **New experience for each audience group** to choose a school group first.
2. Select the initial group: **P1 · Primary school, years 1–2**, **P2 · Primary school, years 3–5**, **S1 · Lower secondary school**, or **S2 · Upper secondary school**.
3. Give the project a recognizable title that identifies its subject and version.
4. Use **Studio → Save** or `⌘S` and choose the location for the `.tholus` package.
5. To continue existing work, use **Open experience…**, or **Account projects…** for projects associated with your Tholus Account.

The default school groups follow the Italian school structure. Manage the project’s profiles to adapt them to your audience. Adding a profile establishes a selectable version; the author supplies its teaching content.

## Build scenes and phases

A scene is a complete moment in the lesson. A phase separates behaviours within a scene, such as showing a stimulus, waiting for a response and revealing an explanation.

Use **Add scene** to insert a **Story**, **Comparison**, **Choice with two paths**, or another appropriate scene type. Check the destination of every choice and how each route ends.

Start with a short structure: introduction, observation, question, comparison and conclusion. **Scene** contains the scene’s visible content and instructions. **Live control** defines actions, choices and progression. **Materials** manages files; **Notes and sources** keeps descriptions, references and author notes.

A simple scene can use one timeline. When an activity needs separate steps, choose **Organize in phases… → Add the first phase**, then **Add phase**. Assign each material to its intended phase. A clip that starts two seconds into a phase is timed from that phase’s entry, rather than necessarily from the start of the lesson.

An editing cut inside a finished film does not itself need a phase. Create phases when the application must wait for a different action, show a different stage, or offer different facilitator controls.

## Write for pupils and facilitators

Public text helps the class observe and act. Facilitator instructions explain how to lead the activity and what to say, including when the facilitator is unfamiliar with the subject.

For each scene, write the complete instruction, the expected response or action, progressive hints and a transition to the next moment. Keep operational notes separate from text displayed to the class. In the conclusion, return to what the group actually observed.

For example: “Look at the edge of the shadow. We will move the light in a moment. First, point to where you think the shadow will move.” Private instructions can explain when to reveal the comparison, what to listen for in responses and when to continue.

Use short public text, recognizable shapes and sufficient contrast. Check apparent size from the audience position: readable text on the Mac can become too small on the projection surface. See [fulldome and 360° video](/en/learn/fulldome-360/) for image formats and projection terminology.

## Choose video and audio playback

Playback mode determines whether a scene uses a timeline, a finished film with its audio mix, or a video that waits for the facilitator. Choose the required behaviour, then check the assigned materials.

Select a media-based scene, such as **Story**, and, when applicable, its phase. Use the **Playback mode** selector in the scene workspace. For finished sequences and waiting loops, **Import media…** adds the files; **Video** chooses the picture, and **Add final mix** or **Add soundtrack version** chooses its audio. The available modes are:

| Mode | Practical use |
|---|---|
| **Timeline** | Arrange media and timing within the scene or phase. |
| **Finished video and mix** | Play a shared video with the complete audio mix for the selected language and school group. |
| **Loop video until Continue** | Keep an environment visible while pupils observe or discuss. Its independent soundtrack plays once. |

For a finished sequence, prepare the video and final mix with the same start and duration. Assign the mix’s language and school group explicitly. Turn off **Play the original video audio** when the separate final mix already contains the narration or complete soundtrack. Enable it only when you intentionally need the video's embedded audio as well.

A video can also supply the complete soundtrack through its embedded audio when that track has been measured successfully. For this setup, enable **Play the original video audio** and leave the final-mix assignments empty, then run **Check story**.

For a waiting loop, set **Final fade (seconds)** as required. After the independent soundtrack ends, the video continues until progression; turn off embedded video audio too if the waiting scene should then be silent. Dedicated playback retains the authored timeline data and uses its selected video and audio assignments; other ordinary tracks are inactive.

In a finished sequence, **Wait for the video and mix to finish before Continue** protects the ending from an early advance. Select **Preview** to rehearse the current sequence, or **Try story** to test the complete route. **Materials** remains available for managing files and assigning them with **Add to step…**.

## Adapt school groups and languages

The audience and language selector, marked with a sliders icon, determines the active version. Common content and explicit customizations let you reuse media while adapting questions, text and timing to each group.

Use **Manage audience groups…** and **Manage languages…**, then select the combination to prepare. Read a field’s scope before changing it: common content may be inherited by several versions, while a customization applies to its specified selection.

Adapt the intellectual task. Younger pupils might identify a change; older pupils might compare measurements or examine a source. A language listed in the project does not mean its recordings are ready. Check text, audio and duration for every combination you intend to use.

## Check and hand over the lesson

Use **Check story** to check the active version, then **Try story** to walk through it in the local preview. Save the checked copy and prepare facilitator sheets before the session.

Resolve missing media, route destinations and timing problems reported by the check. Repeat for every school group, language and route you will use. **Open in window** opens a separate preview and does not itself start playback.

Use the message to correct the relevant assignment:

| Message or symptom | What to change |
|---|---|
| **The final mix is missing for this selection** | Add the intended mix and assign its audience and language. Another language's mix is not selected automatically. |
| **Multiple audio versions match this selection** | Narrow the audio assignments so only one mix or soundtrack matches this audience, language and variant. |
| **The final mix and video must share their start and duration** | Check both start offsets and the actual media durations. Export a matching pair rather than shortening speech to conceal the mismatch. |
| **The waiting soundtrack is missing for this selection** | Assign the intended soundtrack to this version. A deliberately silent loop has no soundtrack assigned. |

When the source video has a valid measured frame rate, the finite-pair duration check permits a difference of at most one source frame. For example, one frame at 30 fps is approximately 0.033 seconds. The start positions must still match; matching file names do not establish synchronization.

**Studio → Facilitator sheets…** exports or prints the operational material. Continue with [Prepare and run a school session](/en/tholusos/schools/run-session/) to distinguish local rehearsal, Live control preparation and room playback. To work with an AI assistant, see the [MCP authoring workflows](/en/tholusos/mcp/workflows/).