Prepare video for an immersive media server

A reliable media delivery includes the file, its technical specification and a rehearsal on the intended playback system. Separate projection format, which describes the picture’s geometry, from encoding, which determines how the file is stored and decoded. A file can be correct in one respect and unsuitable in the other.

Use this checklist with a content producer or venue technician before a school visit, installation handover or scheduled show. In TholusOS, continue with media playback after checking the source.

Record what the file actually contains

Record the projection, orientation, video streams and audio layout before choosing an export preset. A filename such as dome-4K-final.mp4 does not specify the field of view, codec profile, colour interpretation or channel order needed to reproduce the intended result.

Property	What to record	What it helps you check
Projection	Flat, domemaster or equirectangular; field of view; front and horizon	Correct geometry and orientation
Frame	Pixel dimensions, pixel aspect ratio and rotation	Framing and proportions
Encoding	Container, video codec, profile, pixel format and bit depth	Whether the target playback path can decode it
Timing	Duration, frame rate and whether timing is constant or variable	Motion and programme timing
Colour	Primaries, transfer characteristics, matrix and signal range	Consistent interpretation through the output chain
Audio	Codec, sample rate, channel count, layout and language	Correct routing and the intended soundtrack
Delivery	File size, version and whether it is a source master or prewarped output	Storage planning and avoiding a second incompatible warp

Ask the producer about missing or ambiguous metadata. A decoder can report stream properties, but it cannot reliably infer the intended front direction or reconstruct a missing delivery specification. See fulldome and 360° formats for the geometry.

Inspect the streams without changing the file

If FFmpeg tools are already installed, ffprobe can report a file’s container, streams, dimensions, timing and audio properties. The following command reads a local file and prints JSON; it does not transcode or modify the video. The available fields depend on the file and probe build. FFmpeg ffprobe documentation.

ffprobe -v error -show_format -show_streams -of json "lesson-master.mp4"

Look for codec_name, profile, width, height, pix_fmt, avg_frame_rate, duration, bit_rate, colour fields and audio channels/channel_layout. Some values can be absent or estimated. Keep the original file unchanged while comparing candidate exports.

Separate storage bandwidth from rendering load

Compressed bitrate estimates the amount of file data that must be read over time. Decoded frame size describes a different stage of the pipeline. Neither figure alone predicts smooth playback: decoding, memory traffic, effects, warping and output timing must work together on the intended machine.

For example, a file with a total average bitrate of 100 Mbit/s requires about 12.5 MB/s of average file reading:

100,000,000 bits/s ÷ 8 = 12,500,000 bytes/s

A 10-minute file at that average rate occupies approximately 7.5 GB, before small container overhead differences. Peaks, other concurrent reads and background work still matter.

By comparison, one hypothetical uncompressed 3840 × 2160 frame with four bytes per pixel occupies about 33.2 MB. At 60 frames per second that is about 1.99 GB/s of frame data for a single pass. This is illustrative arithmetic, not a claim about TholusOS’s internal pixel buffers or a minimum disk specification.

Do not size storage, memory or a Mac from a “4K” label alone. Test the actual files, output resolution, surface mapping and number of simultaneous activities required by the installation.

Test seeking, cuts and loops

A clip that plays smoothly from the beginning can still behave poorly when seeking, looping or changing scenes. Test the actual In/Out points, repeated playback and transitions that the programme will use. Include a return from a manual interruption if the venue uses scheduling.

Inter-frame codecs can depend on earlier frames. Keyframes reset those dependencies, so their spacing affects the work needed around a seek. Apple documents this relationship in its VideoToolbox keyframe interval reference. Choose an export after testing the required operations; do not assume that the smallest file is the most responsive.

Inspect the first and last frames around a loop and listen for an audible discontinuity. If a clip is meant to repeat seamlessly, the source content and audio edit must support that result too.

Rehearse picture and sound on the target system

Play representative sections on the actual machine and output chain, then run the complete programme before an audience session. Check motion, dark scenes, fine detail, text, audio routing and transitions. A successful file inspection or desktop preview covers only part of this acceptance process.

1. Start with one known-good clip and confirm the audience display and sound route.
2. Check the supplied clip’s format, orientation and framing in preview.
3. Inspect the real projection for doubled edges, visible seams and unreadable labels.
4. Confirm language and channel routing; avoid playing an original soundtrack over a final mix that already contains it.
5. Rehearse seeks, loops, pauses, resume and scheduled changes used by the session.
6. Record the file version, Mac/app version, output settings and result so a later replacement can be compared.

If only one file fails, begin with that file’s metadata and encoding. If every source shows the same defect, inspect the common playback or output path. Use TholusOS troubleshooting for app controls and projector calibration for installation-wide geometric or light problems.