Projects

In the scope of the Visual Stage app, a Project is a folder containing all the required assets and preset files for a given show/set/play.

Project folder structure

A project folder must have the following structure:

• Directory<project_name>

  • Directoryassets

    • … Any custom hierarchy of media files and folders. They will be available for the Media player and Torrent modules. Accepted media files are images, videos and audio files (see Media player module for more detailed list). Aliases (symlinks) are also supported.
    • Directoryexample_asset_subfolder

      • example_audio.wav
    • example_media.mov
  • Directorypresets

    • blackbox.json Blackbox preset file
    • fx.rack.json FX rack preset file
    • modules_default_macro.json Default macro assignment for each type of module. Can be edited through the Default macros editor
    • performer_1.json performer + platform preset files
    • performer_2.json
    • performer_3.json
    • performer_4.json
    • presets.grid.json: Stores the content of the Presets grid module
    • scenic.json Scenic preset file
    • setup.json Project settings preset file
    • track_macro_mappings.json Macro control presets for the Mixer tracks
  • Directorystage

    • Directoryequirectangulars

      • … any number of image file to be used as an equirectangular map for the stage’s skybox and environment
      • example_equirectangular.jpg
    • Directorypaths

      • … any number of.json path files to be used by the Path Creator module present in the stage’s camera and peformers
      • example_path.json
    • Directorypbr

      • … any number of folder containing image files for albedo, normal, roughness, ambient, heightmap, mettalic and/or emission textures. See below for the patterns identifying each texture type. Can be used by the performer’s platforms
      • Directoryexample_pbr_folder

        • example_AmbientOcclusion.jpg must match ‘ao|occ|amb’
        • example_Color.jpg must match ‘diff’ or ‘col’ or ‘alb’ or ‘base’
        • example_Displacement.jpg must match ‘disp’ or ‘hei’
        • example_Emission.jpg must match ‘emis’
        • example_Metalness.jpg must match ‘spec’ or ‘met’
        • example_NormalGL.jpg must match ‘nor’
        • example_Roughness.jpg must match ‘rou’

This structure also allows the user to:

• Replace or update presets for a specific show
• Swap out media sources while preserving preset architecture
• Recycle assets like videos or paths across multiple projects using aliases/symlinks

If the project folder doesn’t respect this structure and/or has missing preset files, it won’t open.

But luckily we have the Default_project folder which contains all the required folders and files for a good template project. Duplicate that Default_project folder and rename it to your liking to start working on a new project.

Tip

If you want to reuse the same assets in multiple projects, you can create aliases/symlinks for them instead of having a copy in each project. Aliases will work with single files as well as folders.

Create a new project

To create a new project, you have to:

1. Duplicate an existing project folder. Use telematic-theater/Telematic-Theater/projects/Default_project as a template if you don’t know where to start.
2. Rename the duplicate folder to your projects name
3. The location of your new Project folder can either be
   • telematic-theater/Telematic-Theater/projects/ which will allow you to load it from the Project menu in the main patch. The “projects” folder is ignored by git, so won’t be uploaded on github.
   • Or, anywhere you want on your computer. You can then create an alias (or symlink) of that folder and put it into telematic-theater/Telematic-Theater/projects/ to make the project accessible from the Project menu in the main patch.
4. After creating, renaming or deleting a project folder, the Project menu in the Dashboard will be updated automatically.

Once your new project folder is created and appearing in the Project menu, you can then load it.

Caution

If you duplicate a project other than the Default project to use it as your starting point, make sure it has been created with the same version of the Visual Stage app, otherwise there might be some compatibility issues. This has to be done manually for now, but automatic fail-safe checks will be added soon.

Load an existing project

To load a project, simply select it from the menu in the Dashboard.

When you load a project, and assuming the Startup button is already on, the app will automatically (in this order):

• Check if the selected project has the correct folder structure and all required preset files
• List available assets, paths, pbr maps and preload avaiable equirectangular maps
• Load preset files
• Recall preset 1 of all preset types. So you can think of preset 1 as the base state of things.

Setting up a project

Thinking a project

Although it is quite flexible, the Visual Stage app has some hard limitations that must be taken into account when creating a project: there is a finite number of each type of module (4 stage performers+platforms, 6 players, 6 torrents, 8 external sources, 12 layers, 2 groups), and the computer it runs on has limited power, so you’ll want to enable modules according to the maximum number of those you are going to use at any time. For example, if you want to set a piece involving dozens of video materials, but you only need to have 4 of them playing at most, then you can just use four players instead of one for each video (you wouldn’t have enough players for that anyway). If you set a piece with four characters, but they are always two at most on stage, then you can configure the project to use two performers instead of four, saving up resources and potentially delivering a smoother output.

Before even touching a computer, you can start setting up your project on the drafting board by asking yourself a few questions:

• Do I need to use the 3D stage for dynamic scenes with lighting and camera movements?
• How many performers and/or platform do I need on stage?
• How many videos/images/torrents do I want to display simultaneously?
• How many external sources do I need?
• How should I organize my layers from bottom to top?
• Do I want to manage multiple layers as one composited layer (group)?

Although those questions don’t necessarily need to be answered definitively from the beginning, it’s good to have some overall idea and direction for the next step.

Preparing files

This step consists of creating the actual project folder by following the steps from the Create a new project section. If all your projects follow a similar setup and/or reuse same assets, you can use one of your own projects as a template instead of relying on the Default project (assuming it was done on the same version of the app).

Then you can start populating the assets, stage/equirectangular, stage/pbr and stage/path with you own content, by following recommendations from the Project folder structure section.

Setting up

Once your new project folder is created and loaded into the app, it’s time to go to the Setup layout and start the actual set-up process!

The three crucial parts of the Project setup you need to take care of are:

1. Modules settings, where you define which modules are enabled and how they are routed
2. Interface, where you can automatically configure the Mixer tracks and layout according to your modules settings
3. Setup preset, where you can eventually save your configuration.

Backing up a project

To backup your project, just create a copy of that project folder and put it in a safe place. If you use aliases, make sure to also backup the original files/folders too.

Since updates of the app tend to break compatibility with projects made with a previous version (at least until v4.2), if you want to be extra safe, it is recommended to also backup the Telematic-Theater folder to keep the corresponding version of all the required Max files that match the time by which the project backup has been made. If you do so, just be careful of the Telematic-Theater/projects/ folder as it might already contain your project folder (or some other project folder).

Sharing projects

One of the most powerful features of the Project system is its support for shared development and distributed performance:

• A project folder can be placed in a shared Google Drive (or other cloud-based directory)
• Collaborators can download the folder and place it into their local system
• Once installed, the project can be fully loaded into the Visual Stage app
• Preset states, media assets, and visual elements remain fully intact across systems

This enables decentralized collaboration, testing, and live performance from different locations, so long as each user is running the current version of the Visual Stage app.