# Get started with TholusOS

Set up your first TholusOS workflow on Mac, find the library and control room, preview content and prepare an immersive venue for operation.

Canonical: https://docs.theusualnext.com/en/tholusos/getting-started/
Updated: 2026-10-22
Publisher: the usual neXt

TholusOS is a Mac application for media playback, venue scheduling, immersive projection and guided experiences. Start by learning the separation between **Media library**, where you organise content, **Live control**, where you prepare and run it, and **Room**, where you configure the installation.

## What do you need before you start?

You need a compatible Mac, an installed copy of TholusOS and local media that you have permission to use. To run a venue, you also need the appropriate displays or projectors, audio equipment and a configuration that has been checked on that installation.

- Check the macOS requirement of the version you install. This guide set accompanies TholusOS **1.1.16**; its application bundle requires **macOS 26.2 or later**.
- Keep a copy of your original media. Choose a dedicated content folder with enough space for the material you intend to use.
- Know whether your source is a normal flat video, a domemaster or an equirectangular 360° image. Container names such as `.mp4` describe a file container, not the shape of its picture.
- For a live installation, identify the audience output and audio route before starting playback. A connected display alone does not establish that the room is correctly mapped.
- Check the edition and feature availability in the app. Multiple outputs, interactive features and connected services can have additional requirements.

For distribution and the current offer, see the [TholusOS product page](https://www.theusualnext.com/en/apps/tholusos). Use the app's licence status for the installation you are operating.

## How is the app organised?

The sidebar separates daily operation, preparation and room setup. You can move between these areas without treating every selection as a command to start a show.

| Area | Use it for |
| --- | --- |
| Live control | Prepare a selection, inspect the preview and control audience playback. |
| Media library | Find videos, audio and experiences; organise playlists and check source formats. |
| Schedule | Plan time slots and inspect the venue's schedule. |
| Studio | Create and revise guided stories and school experiences. |
| Games | Inspect available games, requirements and preparation controls. |
| Room | Configure and inspect projection, audio and room equipment. |
| Settings | Manage general preferences, content storage, account and network settings. |

The app can display translated labels. For example, **Live control**, **Media library** and **Schedule** appear as **Regia**, **Libreria** and **Programmazione** in Italian. A feature marked beta in the app should be rehearsed on the intended installation before audience use.

## How do you prepare your first video?

Import or locate a short, familiar clip in Media library, prepare it in Live control, and check its format and destination before issuing a live playback command. Preparing a video is a useful checkpoint between choosing content and showing it to an audience.

1. Open **Media library** and inspect the current content folder. Use its folder control if the library points at the wrong collection.
2. Add a video through the app's import workflow, or use a video already available in the configured content folder. Refresh the library if you have changed files outside the app.
3. Select the video. Check that the preview and duration match the file you intended to use.
4. Check the source format. An incorrectly interpreted domemaster or 360° clip can be distorted even when decoding works normally.
5. Choose **Prepare in Live control**. Inspect the selected content and the audience output as separate states.
6. Check the playback range and audio controls. A deliberately short rehearsal clip makes problems easier to reproduce.
7. When the room is ready, choose **Start in room**. If playback is already active, the action is **Replace room playback**. Check the actual audience display and sound.
8. End the rehearsal through the playback controls. If you interrupted a programme, check whether you need to resume scheduling explicitly.

The room-output switch shows or hides projection while playback and scheduling continue. Use **Pause** or **Stop** for transport control, and check background audio separately in the mixer.

The [media-server guide](/en/tholusos/media-server/playback/) covers playback ranges, temporary playlists, ambient audio and common faults. The [format guide](/en/learn/fulldome-360/) explains which source interpretation to choose.

## How do you move from a video to a daily programme?

Create a playlist when several clips belong together, then assign the video or playlist to a time slot in Schedule. A reliable programme needs a decision about what happens both inside a slot and between slots.

Start with one short future slot and inspect the chosen days, start time and end time. Saving a slot that covers the current time can start its content immediately when scheduling has control. Check overlap warnings before expanding the schedule. Decide whether content repeats and prepare the waiting video or event fill behaviour where the workflow calls for it. Test a transition at the actual venue before leaving a recurring programme unattended.

Read [Schedule videos, playlists and experiences](/en/tholusos/media-server/scheduling/) for overnight slots, manual overrides and the return to scheduling.

## Which path should you follow next?

Choose the guide that matches your immediate outcome. Room commissioning and story authoring have different prerequisites, so it helps to finish one small workflow before combining them.

- **A single screen or dome film:** [Media playback](/en/tholusos/media-server/playback/) and [content formats](/en/learn/fulldome-360/).
- **A multi-projector venue:** [Calibration](/en/tholusos/projection/calibration/), [edge blending](/en/tholusos/projection/edge-blending/) and [black level](/en/tholusos/projection/black-level/).
- **A class visit:** [Create a guided lesson](/en/tholusos/schools/create-lesson/), then [run the session](/en/tholusos/schools/run-session/).
- **An AI-assisted workflow:** [Connect an MCP assistant](/en/tholusos/mcp/connect/), then [use the supported authoring tools](/en/tholusos/mcp/workflows/).
- **An interactive activity:** [Games and room controls](/en/tholusos/games/overview/).

## What should you record when something goes wrong?

A useful report identifies the operation, the file or configuration involved, the app version and the point where the observed result differs from the expected one. This is more actionable than a screenshot of an unexplained error alone.

Record the source format, resolution and frame rate when relevant; whether the problem appears in preview, audience output or both; and whether it occurs with a second known-good file. For projection, include which surface or overlap is affected. Keep account credentials, access tokens and private classroom material out of shared reports. Use [Troubleshoot playback and sessions](/en/tholusos/settings/troubleshooting/) to narrow the cause and prepare a support bundle, or the [settings guide](/en/tholusos/settings/configure/) to locate the relevant app and room controls.