Alva Technical Documentation

Overview

Alva is a software module developed by Alva Theaters, designed for use within Blender 2.79's Video Sequence Editor (VSE). It is an addon created to assist lighting designers, particularly those using ETC Eos family lighting consoles or ETCNomad, in the design phase of timecoded light shows. Alva provides timeline-based control as a companion software. It also automates and guides the process of transferring sequencer data to the console's internal hard drive for reliable playback.

The goal of the Alva software is to empower lighting designers to do more art with less technicals.

Documentation Practices at Alva Theaters

This documentation is very light by design, meaning it has a low word count. That is because I don't want my customers to have to learn the software by reading the documentation. I want my customers to learn intuitively by simply interacting with the software. If many customers have the same question and they all answer that question with "read the manual" or "RTDM", and if the manual does its job, then I don't know about it. I don't know where to make the software more intuitive. Excellent customer-facing documentation eliminates opportunities to make the software itself more intuitive. More intuitive software helps artists do more art with less technicals.

Some information-seeking questions I am asked will be answered in a software update, not in the reply message itself. A message only helps one person, but making the software more intuitive helps all. The goal is to make the software so intuitive that all the customer needs to focus on is doing art.

- Jordan

Key Details

• Alva Sequencer: Resides in Blender's Video Sequence Editor (VSE) N tab, aiding in the sequencing of lighting designs. This is the first module. The second module, Alva 3D, is still under development and will be released soon.
• 
  
• Compatibility: Specifically designed for Blender 2.79 due to its simpler Video Sequence Editor (VSE) and compatibility with changing video output viewer channels. Future versions, those including the Alva 3D module, will be designed for newer versions of Blender too since those will rely less on the VSE.

Key Features

• Animation: Add "keyframes", "dope sheet view", "graph editor view", "action editor view", and "motion path constraints" to your vocabulary as a lighting designer on ETC Eos or other consoles
• 
  
• Sequence-based Editing: Use a video editor to edit lighting changes as a lighting designer on ETC Eos or other consoles
• 
  
• Automation Tools: Includes built-in tools to streamline data transfer to ETC Eos lighting consoles and to delete boring, repetitive steps.
• 
  
• Python Scripting: Utilize Blender’s bpy Python API for advanced scripting capabilities.

• Rapid Forward Development: Alva 3D, sister to the current module, Alva Sequencer, coming soon. 

Alva Theaters

Alva Theaters is a startup aiming to mass-produce enhanced live performances with a network of identical theaters across America. Alva stands for Animated Lighting Video & Audio, reflecting its goal to integrate all of these elements into one hyper-intuitive software.

Installation and Setup

• Ensure Blender 2.79 is installed.
• The user must unzip and install Alva addon in Blender.
• Ensure the same network, subnet, and correct ports are used for communication with the ETC Eos console.
• Read the "Not a Useless Readme File" included in the Alva folder for more detailed installation instructions.

Features

1. Strip Types:

   • Animation Strips: Use Blender's animation tools to control parameters instead of cues
   • Macro Strips: Rapidly create basic macros with Magic Mitten and fire them using strips in sequencer
   • Cue Strips: Control cue timing and duration with strips, then build cues.
   • Flash Strips: Rapidly create basic flash effects with strips designed exclusively for flashes
   • Trigger Strips: Send arbitrary OSC strings to anywhere, or create advanced offset effects inside Eos
   • 
     
   • Sound Strips: Manage internal timecode clock and event list timecode events plus the start/stop macros

1. UI Elements:

   • Context-dependent, changes based on strip selections
   • 
     

2. Magic Mitten:

   • Automates rapid command execution on the console. Indicated by a HAND icon in the UI.
   • Allow it to skip the Shift-Update on the console in Alva Settings.
   • 
     

3. House Lights Automation:

   • Automates dipping of house lights during playback.

Cue Builder:

    Assign console groups to sliders by clicking the gear icons. Then, control those groups with the sliders and preset buttons.

    The "Energy" row at the bottom is for something like a strip light that would often have a chase on it.

1. • 
     

2. Livemap:

       Keeps the console in the correct cue state upon playback from any point.

   
   

Motif Linking:

    Link identical strips together so that changing one automatically changes the others.

Select Magnetic:

    Select all strips with properties that match active strip's "magnetic" properties. 

    Also use Rapid Select and Copy buttons unique to each property. 

    Refer to tooltips to understand Filtering.

Command Line:

    Select strips and type in "C" followed by channel number you wish to move strips to followed by Enter

"O" Key:

    Press "O" to add strip on down-stroke and enable up-stroke to add 2nd strip on up-stroke in Settings

Rapid Selections:

    Type channel number to select all strips in channel. Shift to add 10, 0 is 10. "D" to deselect.

Bumping:

    "L" to bump selection Left 1 frame, "R" to bump right. Hold shift for x5. "U" to go up, hold Shift for down.

Scale & Extrude:

    Select 2 like strips and type "E" to extrude them out with matching space in between.

    Select many strips and type "S" to scale the spaces in between them. Works best for shorter operations.

Motion Paths:

    Use path constraints in Blender's 3D view to make real moving lights trace paths in CGI world. Refer to UI.

Offset Friends:

     Automate Start Trigger syntax to multiple channels with an offset where offset length is strip length

    Create sets using tools like "-", "thru", "through", " ", "+", ",", etc.

    Place simultaneous sets inside "()" if channel quantity is the same between sets.

Color Palette Generator:

    Rapidly create numerous color palettes on the console using Magic Mitten. Refer to the tooltips.

Animation Presets:

    Forget about the OSC syntax by letting these tools add/update the syntax for you. Refer to the tooltips.

Animation Tools:

    Tools for baking animation to cues and updating console values.

Macro Searching:

    Press the magnifying glass button to pre-fill macro numbers that aren't already taken in Alva's sequencer.

"Not a Dumb Chatbot"

• If you have a ChatGPT Plus account with OpenAI, you can talk to our Not a Dumb Chatbot GPT. It is trained on proprietary Alva documentation as well as the source code itself. It even wrote parts of this documentation. Here is a sample conversation that can be viewed without an account. When interacting with the chatbot, please understand that it can make mistakes. If the chatbot says something particularly unhelpful (or even dumb), feel free to report the incorrect statement so we can make it less dumb.
• 
  
• If you are unfamiliar with ChatGPT or similar Large Language Models (LLM's), just chat with it like you would a human. Unlike the chatbots you may be used to, like Siri, this is not a dumb chatbot. However, it may occasionally pretend like it's a dumb chatbot like Siri. If it says something like, "I'm sorry, I didn't understand that.", it's just trying to be funny.

Known Issues

• Packet dropping issues during data transmission, mitigate with USITT ASCII or by simplifying sequences
• Occasional malfunction of the "house down on play" command.
• Scale feature behaving inversely to mouse movements.
• "Disable all clocks" button creates event lists 1-100 on console if they don't already exist.
• Issue with motif linking populating more than one warning when multiple animation strips try to link
• Magic Mitten doesn't build Flash macros correctly if the "interpreted" text labels are empty on that strip.
• "Help" button on Animation UI doesn't actually help much yet.
• Blender UI occasionally stops updating on slower machines during animation baking.
• 
  

Best Practices

• Do not have Alva running during a real show with audience. Migrate data to console first.
• Use whole number frame rates to avoid calculation errors. Set this in Blender's Properties, not Alva.
• Regularly check console connectivity and network settings.
• Utilize USITT ASCII files to mitigate packet loss issues.
• Follow tooltips for more detailed instructions on each feature.

Conclusion

Alva is a robust tool designed to integrate seamlessly into the Blender environment, offering advanced capabilities for lighting design in theatrical productions. Its functionalities are tailored to enhance the efficiency and creativity of lighting designers in the time-coding process, particularly those using ETC Eos family lighting consoles.