Getting Started

Complete installation and setup guide for TouchDesigner Par Hover Control for VSN1.

Installation

Grid Editor Setup (VSN1 Users Only)

1. Install the Grid Package:

Option A - From Package Manager (Recommended for newer Grid Editor versions):

1. Open Grid Editor
2. Go to the Package Manager panel
3. Look for TouchDesigner Par Hover Control in the available packages
4. Click Install

Note: If the package is not available in your Grid Editor version, use Option B below.

Option B - Manual Installation (for older Grid Editor versions or development):

# Clone the repository
git clone https://github.com/function-store/TD_ParHoverMIDI_VSN1.git

# Navigate to the root folder
cd TD_ParHoverMIDI_VSN1

# Install dependencies
npm i

# Build the package
npm run build

Then in Grid Editor:

1. Go to the Package Manager panel
2. Click + Add external package and add the root path (e.g., C:\Users\...\TD_ParHoverMIDI_VSN1)
3. Approve the package when it appears

2. Import VSN1 Configuration:

1. On your VSN1 device in Grid Editor, import TouchDesigner Par Hover Control configuration
2. Keep Grid Editor open at all times when using VSN1 (requires exclusive access to port 9642)

The TouchDesigner component automatically attempts to open Grid Editor on startup

3. Configure Package Preferences (Optional)

In Grid Editor, open the package preferences to customize VSN1 behavior when TouchDesigner disconnects:

• Turn off LCD when TouchDesigner is disconnected - Controls the screen backlight state
  • When enabled: LCD backlight turns off when disconnected (saves power, reduces visual distraction)
  • When disabled: LCD stays on at all times
  • Default: Disabled (LCD stays on)
• Set LEDs to red when TouchDesigner is disconnected - Controls LED indicator state
  • When enabled: All slot button LEDs turn red when disconnected (visual connection status)
  • When disabled: LEDs remain in their last state
  • Default: Enabled (LEDs turn red)

💡 Tip: These are personal preference settings. Many users prefer keeping the LCD on to monitor connection status, while the red LED indicator provides quick visual feedback when disconnected.

TouchDesigner Setup

1. Download Component:

Download ParHoverMIDI_VSN1.tox from the latest release

2. Add to Project:

1. Connect your MIDI controller to your system
2. Drag ParHoverMIDI_VSN1.tox into your TouchDesigner project at root / (recommended location)

⚠️ Important Limitation: Only one component instance is allowed per project file, and only one TouchDesigner project with this component should be open at a time. This is due to communication and architecture limitations. Always place the component at the project root / for best compatibility.

3. Configure MIDI:

1. Set up MIDI Device in TouchDesigner:
   • Open TouchDesigner’s MIDI Device Mapper (Dialogs → MIDI Mapper)
   • Ensure your Grid/VSN1 MIDI device is visible and active and set as both Input and Output
   • Note the Device ID (this is critical for the next step)
2. Configure Component:
   • Open the component’s VSN1/UI parameter page
   • ⚠️ CRITICAL: Set the Device ID parameter to match the device ID from MIDI Mapper
   • This links the component to your physical MIDI controller

Setup for Other MIDI Controllers

If you’re using a different endless/relative MIDI encoder (not VSN1):

1. Download ParHoverMIDI_VSN1.tox from the latest release
2. Drag the .tox into your TouchDesigner project (suggested at root /)
3. Disable VSN1 features:
   • Turn off VSN1 Support parameter in VSN1/UI page to disable screen/LED features
   • No Grid Editor required
4. Set Device ID:
   • Note your device’s ID from TD’s MIDI Device Mapper
   • Set the same ID in component’s VSN1/UI parameter page
5. Configure mappings:
   • Use Learn Mode: Hover over mapping fields and move your MIDI controls
   • Or set MIDI indices manually in the Mapping tab
   • Configure step sizes (default: 0.001, 0.01, 0.1, 1)
   • See Advanced Guide - MIDI Mapping for details
6. Start using: Hover over any parameter and twist your encoder!

Note: Endless/relative encoders are required. Standard potentiometers will not work as intended.

Verify It’s Working

Let’s test that everything is set up correctly:

1. Hover your mouse over any numeric parameter in TouchDesigner (e.g., a tx translate parameter on any operator)
2. Twist your MIDI encoder/knob - the parameter value should change in real-time!
3. Success! Your setup is complete and working

Troubleshooting:

• Parameter not changing? Check Device ID matches in MIDI Mapper and component’s VSN1/UI page
• Verify your controller sends endless/relative MIDI (not standard potentiometer values)
• For VSN1: Ensure Grid Editor is open and the package is loaded on your device

💡 Helpful Tip: Hover over any custom parameter in the component while holding Alt (or Option on Mac) to see detailed help text for that parameter!

What’s Next? Discover All the Features!

You’ve got the basics working - but there’s so much more! This component has powerful features for streamlined parameter control:

🎯 Core Features

• Parameter Slots - Save parameters to buttons for instant recall without hovering
• Multiple Banks - Organize slots into banks (e.g., Bank 0 = lighting, Bank 1 = audio)
• Parameter Shortcuts - Quick button combos: reset, set default, clamp, and more
• Step Sizes & Modes - Adjust precision with Fixed or Adaptive step modes
• ParGroup Control - Control entire parameter groups (RGB, XYZ) simultaneously (requires TouchDesigner 2025.X or later)
• UI Highlighting - Visual feedback in TouchDesigner interface
• Full Customization - Extensive options to tailor behavior to your workflow
• Parameter Recovery - Automatic recovery when operators are moved/renamed
• Undo/Redo - Undo any parameter change with Ctrl+Z / `Cmd+Z

👉 Continue to the User Guide to learn how to use all these features!

---

💡 Quick Tip: Updating the Component

Your work is automatically protected! The component creates external storage for your data on first launch, so updates won’t affect your saved configurations.

To update:

1. The UI icon in TouchDesigner’s top-right turns yellow when updates are available
2. Click it → go to About page → hit Update
3. Done! ✅

Want to use the component across multiple projects? Check out the “Externalize Component” button in the About page - it’s explained in the Advanced Guide.

Next Steps

• User Guide - Learn all features, shortcuts, and customization options
• Quick Reference - Fast lookup tables for controls, parameters, and MIDI mappings
• Advanced - Parameter recovery, MIDI mapping details, troubleshooting

Troubleshooting

MIDI not responding:

• Check Device ID is set correctly in Mapping tab
• Verify MIDI device is active in TD’s MIDI Device Mapper
• Ensure you’re using endless/relative MIDI encoders (not standard pots)

VSN1 screen not updating:

• Ensure Grid Editor is open
• Check Grid Editor has exclusive access to port 9642
• Try pulsing Reset Comm parameter

Grid Editor won’t open automatically:

• Check installation path matches common locations
• Open Grid Editor manually

---

← Home

User Guide →