Get started with TholusOS

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. 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.

Open Media library and inspect the current content folder. Use its folder control if the library points at the wrong collection.
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.
Select the video. Check that the preview and duration match the file you intended to use.
Check the source format. An incorrectly interpreted domemaster or 360° clip can be distorted even when decoding works normally.
Choose Prepare in Live control. Inspect the selected content and the audience output as separate states.
Check the playback range and audio controls. A deliberately short rehearsal clip makes problems easier to reproduce.
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.
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 covers playback ranges, temporary playlists, ambient audio and common faults. The format guide 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 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 and content formats.
A multi-projector venue: Calibration, edge blending and black level.
A class visit: Create a guided lesson, then run the session.
An AI-assisted workflow: Connect an MCP assistant, then use the supported authoring tools.
An interactive activity: Games and room controls.

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 to narrow the cause and prepare a support bundle, or the settings guide to locate the relevant app and room controls.