User Manual

1. Installation and Initial Configuration

1.1 Hardware Requirements

• Processor: Apple Silicon (M1, M2, M3 recommended) or Intel Core i5 with native Metal support.
• RAM: Minimum 8 GB (16 GB or higher recommended).
• Storage: Solid State Drive (SSD) required to prevent stutters during real-time video loading.
• Network: Wired Ethernet adapter for Pioneer hardware synchronization (Pro DJ Link).

1.2 Installation on macOS

1. Move the application to the system applications folder (/Applications).
2. If macOS blocks execution because this is an unsigned beta build:
   • Navigate to System Settings > Privacy & Security.
   • Under the Security section at the bottom, click "Open Anyway".
   • Alternatively, if an "App is damaged" error is shown, open the Terminal and execute the following command to remove the quarantine flag:

   xattr -d com.apple.quarantine /Applications/Visual\ Buddy.app

1.3 Beta Expiration Period

This beta version is time-restricted and fully functional only within the following dates:

• Start date: May 1, 2026.
• Expiration date: September 1, 2026.

Once the expiration date is reached, the application will prompt for a license update or a newer version.

2. Interface and Workflow

The user interface is divided into three main sections: top preview monitors, the central mixer/configuration dashboard, and the bottom integration and effect rack.

2.1 Deck Management (Decks A and B)

The application handles two independent video channels, designated as Deck A and Deck B.

• Preview Monitors: Each Deck has a dedicated 16:9 canvas showing the real-time rendered video output with active effects applied.
• Progress Bars: Located below each preview monitor, these display the timeline of the currently loaded audio track. Vertical lines overlaying the progress bar represent the Hotcue positions (1 to 8) retrieved from the DJ software database.
• Metadata Display: Shows the track title, artist name, exact playback BPM, elapsed/remaining time, and speed multiplier.

2.2 File Explorer and Loading Lists

Clicking the "LIST A" and "LIST B" buttons opens sidebars to select the root folder containing video loops.

• Recommended Folder Structure: Organizing video clips into subfolders numbered 1 to 8 is recommended. This allows the application to automatically load a video clip corresponding to the specific Hotcue number triggered on the DJ hardware or software.
• Smart Video Matching: When active, the application scans the audio track metadata (such as comment fields or filename strings) for keyword matches with video filenames to load matching content automatically.
• Played History: Previously triggered video files are displayed with reduced opacity in the sidebar to prevent accidental duplicate playback.

3. Hotcue & TimeTrigger Logic

Visual Buddy features a rule-based hotcue and timecode trigger engine. When a Hotcue is pressed or the track reaches a specified timecode, the app processes the event to perform dynamic parameter modifications and media loading.

3.1 Metadata-Driven Configuration

The application reads commands parsed from the track's comment or metadata fields using formatting patterns like [Index]:[Action] [VFX] (e.g., 1:zoomon red, 2:shakeon load"clip.mp4").

• Color Assignment: Colors specified in the metadata (e.g., red, orange, blue) are translated to hex codes to color-code corresponding hotcue pads in the user interface.
• VFX Parameter Injections: Hotcues can trigger specific visual effects switches, such as zoomon, zoomoff, shakeon, shakeoff, grayscaleon/grayscaleoff, posterizeon/posterizeoff, pixelateon/pixelateoff, edgeson/edgesoff, or opacityon/opacityoff.
• Direct File Loading: Using the keyword load"filename", a hotcue can bind a specific video loop to be loaded immediately upon activation.

3.2 Dynamic Playhead Range Triggering

In addition to receiving direct trigger events from DJ software, Visual Buddy performs playhead jump detection.

• Jump Detection: If the playhead location jumps suddenly and lands within a tight threshold of an established hotcue coordinate, the system automatically fires the corresponding hotcue actions.
• Backward Jump Support: Range triggering handles backward playhead jumps (e.g., jumping from the chorus back to a previous verse hotcue), triggering the bound visual state unconditionally.

3.3 Target Media Loading Priority

When a hotcue or time trigger reloads a video (and the deck's smart match lock is inactive), the engine determines the video choice using the following hierarchy:

1. Specific Filename Target: If a load"filename" string was mapped in the metadata, the engine queries the global video pool for a matching file and loads it directly.
2. Subfolder Randomization: If no specific file is target-mapped (and it is a Hotcue trigger), the engine navigates to the subfolder corresponding to the triggered hotcue index (1 to 8) under the selected video directory, picking a random loop.
3. Played History Management: To ensure variety, the engine prioritizes clips that have not been played yet. If all clips in the target folder have been played, the history cache is reset for that folder, allowing fresh cycles.
4. Cooldown Protection: Hotcue trigger actions are throttled with a 150ms cooldown timer to prevent double-triggering or stuttering during fast playhead scrubbing or button mashing.

3.4 TimeTrigger Logic

In addition to hardware-bound Hotcues, Visual Buddy automates visual events at precise track positions (timecodes).

• Metadata Syntax: Defined in the comments or metadata fields using either [MM:SS]:[actions] (minutes and seconds) or [SS]s:[actions] (absolute seconds) formats (e.g., 02:10:zoomon red load"laser.mp4" or 45s:shakeon).
• Trigger Execution: When the playhead passes the defined timestamp in a forward direction, the bound color preset, VFX state switches, or video file loads are automatically executed.
• Scrubbing/Jumping Resilience: If the playhead performs a backward jump or a large scrub (delta < -1.0s or > 5.0s), the trigger execution history is cleared to ensure the events fire correctly when the timestamp is crossed again.

3.5 Supported Commands and Colors Reference

The following table details all commands and parameters that can be assigned to both Hotcues and TimeTriggers:

4. Central Mixer (Tab Mixer)

The MIXER tab controls the interaction between both video layers, providing standard DJ mixer controls adapted for image processing.

4.1 Channel Equalization (EQ)

Each channel features a dedicated set of knobs to modulate visual responses based on audio frequencies or mapped controls:

• HI (High): Modulates the visual opacity or transparency of high frequencies.
• MID (Mid): Controls the response of mid-range frequencies.
• LOW (Low): Modulates opacity or effect response based on low frequencies.
• FILTER: Visual filter sweep that modifies the image based on luminance or contrast.
• FX AMT (Dry/Wet): Adjusts the mix level between the raw video stream and the active effects rack.

4.2 Channel Faders and Crossfader

• Volume Faders (A and B): Control the master opacity level of the respective deck.
• Crossfader: Horizontal slider that blends the output between Deck A and Deck B.
• Assignment Buttons (A and B): Assign or unassign each deck from the crossfader control.
• Crossfader Curve (Curve): Adjusts the crossfader transition curve, ranging from sharp cuts (ideal for fast transitions) to smooth linear crossfades.

4.3 Composition Blending Modes

Selects the mathematical formula used to composite the two video layers:

• ADD (Lighter): Adds pixel values together, brightening overlapping areas.
• MULTIPLY: Multiplies pixel values, darkening the image and showing only overlapping bright areas.
• OVERLAY: Combines Multiply and Screen modes depending on the background color, preserving highlights and shadows.
• HARD LIGHT: Simulates a harsh light source shining directly on the composite.
• COLOR DODGE / COLOR BURN: Brightens or darkens colors based on the luminance of the layers.
• DIFFERENCE / EXCLUSION: Subtracts color values of the top layer from the bottom layer, creating color-inversion and high-contrast effects.

5. Audio Reactive Engine (Tab Audio)

The audio engine processes incoming sound and splits it into three frequency bands to automate effect parameters in real time.

5.1 3-Band Frequency Analysis (Bass, Mid, High)

Each band features an interactive spectrum visualizer and individual parameters:

• Gain: Amplifies or attenuates the frequency input to increase or decrease effect sensitivity.
• Fall: Decay or smoothing time. High values result in a slow decay, while low values provide sharp, immediate reactions to transients.
• Frequency Selectors: Interactive range handles on the spectrum canvas allow defining the exact frequency range analyzed by the band (for example, isolating sub-bass frequencies between 30Hz and 80Hz).

5.2 Built-in and Custom Envelopes

The filtered audio signal is processed through mathematical envelope curves to modify the output response:

• Punch: Fast attack with exponential decay, ideal for kicks and transients.
• Gate: Noise gate behavior; the output triggers to 100% only if the signal crosses the set volume threshold.
• Linear: A direct 1:1 relationship between audio volume and effect strength.
• Exponential / Logarithmic: Non-linear curves for smooth transitions or emphasized peaks.
• Inverted: Reverses the reaction; peak volumes decrease effect intensity, while silence sets it to maximum.
• Draw (Custom): Allows drawing custom envelope curves by clicking and placing control points on the envelope editor canvas.

6. Visual Effects Rack (VFX)

The VFX Rack functions independently for Deck A and Deck B. All rendering is executed via native Metal shaders on the GPU.

6.1 Static and Filter Effects

• Pixelate: Reduces the visual resolution by grouping pixels into blocks, adjustable from 0% to 100%.
• Opacity: Directly controls the alpha channel of the layer, allowing manual or reactive fading.
• Posterize: Limits the color palette to flat, distinct tones for a poster-like look.
• Edges: Applies a Sobel edge-detection filter, highlighting contours on a dark background.
• RGB -> B&W: Converts the video stream to grayscale.
• Tint Color: Overlays a color wash using a palette of 16 presets, selectable via buttons or MIDI triggers.

6.2 Motion Effects (Zoom and Shake)

• Zoom: Modulates the video scale rhythmically.
• Shake: Applies high-frequency horizontal and vertical translations (earthquake effect) with adjustable intensity.
• 16-Step Sequencers: Both Zoom and Shake are governed by a 16-step grid synchronized with the musical beat. Each active step triggers the effect at the corresponding subdivision of the bar.

7. Integration and Network Protocols (Tab Settings)

7.1 Traktor Integration

• Playhead Synchronization: Maps playback position directly from Traktor Pro.
• D2/S8 Screen Mod (QML Mod): Copies custom files to the Traktor folder to transmit high-resolution screen data.
  • Automatic Installation: Navigate to Settings > INSTALL D2 QML FOLDER and click "INSTALL QML FILES (D2/S8)".
  • Traktor Configuration: In Traktor, go to Settings > Controller Manager > Add... > Pre Mapped > Traktor Kontrol > D2.
• HTTP Port: Sets the local port (default is 7001) for receiving data.

7.2 Rekordbox Integration (Pro DJ Link)

Visual Buddy emulates a CDJ hardware device on the network to communicate with physical Pioneer DJ equipment:

• CDJ Discovery: Listens for status packets (keep-alive) on UDP port 50000 to identify hardware players.
• TCNet: Receives real-time telemetry (BPM, playhead position, playback state, and metadata) via UDP broadcast on ports 60000, 60001, and 65032.
• DBSERVER: Connects to the host CDJ via TCP port 12523 to query track databases, retrieving advanced metadata and Hotcue arrays (supporting NXS2 extended commands and Legacy CDJ queries).
• NFSv2 Client: Automatically downloads the track database (export.pdb) from USB drives inserted into the players into local RAM, facilitating instant metadata lookups (O(1)) during track changes.

7.3 Output and Display Configuration

• Render Resolution: Sets the project rendering output size (1280x720, 1920x1080, 2560x1440, 3840x2160).
• Projector Output Screen: Dropdown menu to assign the fullscreen output to a connected monitor or projector.
• Display Mode: Toggles between windowed mode and borderless fullscreen mode.
• Hide Cursor: Automatically hides the mouse cursor when positioned inside the video projection window.
• Syphon Output: Routes the final composition frame to external media servers (such as Resolume Avenue, MadMapper, or OBS Studio) with zero latency via shared GPU textures.