# vizmatic User Guide

## Overview

vizmatic builds music visualizers, lyric videos, and clip montages from local media. A project can contain audio, video clips, visualizer layers, text, lyrics, image overlays, and particle layers. The app provides a live preview for editing and an ffmpeg-backed render pipeline for final MP4 output.

## Glossary

- Stage: The active output canvas where video and layers are composited.
- Preview: The live in-app view of the current playhead frame.
- Timeline: The shared time scale used by the waveform, storyboard, lyrics, and layers.
- Storyboard: The video clip row below the waveform.
- Playhead: The current time indicator.
- Layer: A visual element rendered above video.
- Portable package: A `.vizpkg` file containing a project JSON plus referenced media.

## Quick Start

1. Create a new project with `File > New Project`.
2. Load audio with the Audio button or `Media > Load Audio...`.
3. Add clips with the Video button, `Media > Add Videos...`, or the Media Library.
4. Add visualizer, text, lyrics, image, or particle layers from the element toolbar.
5. Adjust clip timing and layer properties while watching the preview.
6. Save the project, or save a portable package if the project should travel with its media.
7. Render to MP4.

## Project Files

### Standard Save

- `File > Save` writes the current `.json` project.
- `File > Save As...` chooses a new `.json` project path.

### Portable Package

- `File > Save Portable Package...` writes a `.vizpkg` file.
- Portable packages include `project.json` and referenced audio, video, and image media.
- Opening a `.vizpkg` extracts media to a temporary project cache and rewrites paths for the current session.
- The project type indicator beside the project name shows whether the current save target is standard or portable.

### Recent Files

`File > Recent Files` lists the last opened projects. Missing entries are removed when opening fails.

### Default Locations

Advanced Settings controls the default folders used by project, asset, render, and managed-media browse dialogs.

Default Windows locations:

- Projects: `%USERPROFILE%\Documents\vizmatic\Projects`
- Assets: `%USERPROFILE%\Documents\vizmatic\Assets`
- Renders: `%USERPROFILE%\Documents\vizmatic\Renders`
- Managed Media: `%USERPROFILE%\Documents\vizmatic\Managed Media`

## Audio Timeline

- Load or replace audio from the Audio button or `Media > Load Audio...`.
- The overview waveform provides playback, seek, zoom, fit, volume, and mute controls.
- The playhead is hidden until audio is loaded.
- The element toolbar is disabled until an audio file is available.

## Video Storyboard

Each clip appears as a colored segment beneath the waveform.

### Clip Editing

- Drag clips to reorder them.
- Click a clip to select it.
- Drag the bracket grips to adjust timing.
- Use the context menu for rename, duplicate, remove, color, file info, and fill method.
- The Delete key removes the selected clip.

### Fill Method

Fill Method controls how a clip fills timeline space beyond its natural trimmed duration:

- Loop: repeats from start to end.
- Ping-Pong: plays forward, then backward, then repeats.
- Stretch: stretches the source clip over the segment duration.

### Clip Properties

Clip properties include:

- Timeline start/end.
- Trim start/end.
- Width, height, and lock-aspect toggle.
- Blend mode and color/filter adjustments.
- Hue, gamma, saturation, contrast, brightness, intensity, colorize, invert, rotate, flip H, and flip V.
- Motion controls for bounce and camera shake.

## Preview

- The preview can be docked top, bottom, left, or right.
- The preview can also be detached into a separate window.
- Dock controls live in the custom titlebar.
- The preview scales to the available pane while preserving the selected output orientation.
- Landscape output is 1920x1080.
- Portrait output is 1080x1920.

## Layers

Layer rows can be selected, reordered, duplicated, deleted, expanded, collapsed, and hidden. The small visibility/color control toggles layer visibility. Layer editor tabs organize properties by function.

Layer types:

- Visualizer
- Text
- Lyrics
- Image
- Particles

### Shared Layer Controls

Common layer properties include:

- X/Y position.
- Width and height with optional aspect lock.
- Rotation.
- Opacity/transparency.
- Primary/secondary color or gradient where applicable.
- Outline, glow, glow mode, glow blur factor, and shadow.
- Blend mode.
- Layer label color.
- Audio-reactive motion opt-in where supported.

### Profiles

Layer profiles let you reuse settings without duplicating the whole layer.

- Category profiles save one settings group.
- Tab profiles save all supported settings in a tab.
- Selecting a profile applies it immediately.
- If values are changed after selecting a profile, the profile indicator shows that the current controls differ from the saved profile.
- Profiles are stored in global application settings, not in the project file.

## Visualizer Layers

Visualizer layers visualize the loaded audio.

Supported modes:

- Bar
- Line
- Solid
- Dots

Layout and analyzer controls include:

- Straight and circular layouts.
- Bar count, dot count, point count, bar gap, minimum bar height, line width, dot size, and solid fill alpha.
- Frequency scale, amplitude scale, averaging, FFT size, smoothing, minimum decibels, maximum decibels, low cut, and high cut.
- Mirror X/Y, reverse, invert, radial spin, padding, center offset, and base radius ratio.

Style controls include:

- Primary and secondary colors.
- Gradient direction and solid/gradient behavior.
- Amplitude-reactive fill and outline colors.
- Outline width.
- Inner or outer glow, glow amount, blur factor, and opacity.
- Shadow color and distance.

Effects:

- Flame/smoke-style edge effect with intensity and detail controls.
- Audio-reactive bounce and camera shake when enabled.

## Text Layers

Text layers provide static text overlays with:

- Text content.
- Font family.
- Font size.
- Text alignment.
- Width and height bounding controls.
- Outline, glow, shadow, opacity, and blend controls.

Fonts are loaded from the app font folder and listed alphabetically in the font dropdown.

## Lyrics Layers

Only one lyrics layer is allowed per project.

Lyrics features:

- Lyrics timeline row below the video storyboard.
- Click empty lyric space to create a cue.
- Select a cue to show resize grips.
- Drag cue grips to adjust start/end times.
- Hold and drag a cue body to move it.
- Double-click or context-menu edit to change lyric text.
- Import `.lrc` or `.srt` files from the Lyrics tab.
- Optional single style for all cues, or per-cue styling.
- Left, center, and right text alignment.

When playback enters a cue, the lyric text appears. When the cue ends and no adjacent cue exists, the lyric layer becomes invisible.

## Image Layers

Image layers support:

- Image file selection.
- Width, height, position, and rotation.
- Mask radius for circular or rounded masking.
- Hue, gamma, saturation, contrast, brightness, intensity, colorize, invert, and reverse.
- Outline, glow, shadow, opacity, blend, and audio-reactive motion opt-in.

## Particle Layers

Particle layers support:

- Direction.
- Speed.
- Size minimum and maximum.
- Opacity minimum and maximum.
- Particle count.
- Audio-responsive behavior.
- Motion participation where available.

## Media Library

The Media Library opens in its own window and can add assets to the active project.

Current capabilities include:

- Reusable media items.
- Add to Project workflow.
- Labels, tags, folders, and metadata.
- Missing-file indication and relocation workflow.
- Managed media path support.
- Stock video search/download support when a Pexels API key is configured in Advanced Settings.

## Advanced Settings

Open `File > Advanced Settings` to manage global app settings.

Available settings include:

- Default Projects path.
- Default Assets path.
- Default Renders path.
- Managed Media path.
- Stock media API settings.

The Advanced Settings window uses the same custom titlebar styling as the main app and saves changes to the global application settings file.

## Menus and Shortcuts

The custom titlebar menus mirror the major toolbar actions. Unavailable actions are disabled, and mutually exclusive view/theme options show their selected state.

Important menu areas:

- File: new, open, recent files, save, save as, save portable package, advanced settings, render, cancel render.
- Media: load audio, add videos, add from library, open media library.
- Layers: add visualizer, text, lyrics, image, particles, and show/hide lyrics timeline.
- View: zoom controls, preview docking, detach/reattach preview, theme.
- Help/About: product information and in-app help.

## Render

- Start render from the project toolbar or File menu.
- Trial mode blocks render until activated.
- Choose an output path when render starts.
- Render progress, ETA, and logs are shown in the app.
- Cancel render from the toolbar or File menu.
- Default render folder is controlled by Advanced Settings.

## Licensing

The activation modal shows the machine ID in shortened form with copy and full-view controls. Purchase links pass the machine ID to the licensing site automatically when opened from the app.

License keys use a `payload.signature` format and verify offline in the desktop app.

Trial mode allows exploration and preview, but licensed activation is required for restricted launch features such as full rendering and saved output workflows.

## Tips

- Use portable packages when sharing a project between workstations.
- Use Fill Method from the clip context menu for quick clip timing changes.
- Use profiles for repeated layer looks, FFT settings, or frequency ranges.
- Use detached preview when tuning layers on a second monitor.
- If a short clip is hard to grab, zoom in on the waveform/storyboard.
- Use Advanced Settings before a large project so browse dialogs open in the right folders.

## Troubleshooting

### A portable project opens but media is missing

Save the package again from a project where all referenced media files are available. Portable save will fail if required media cannot be found.

### A clip does not fill its segment as expected

Open the clip context menu and check Fill Method. Use Loop for repeated playback, Ping-Pong for forward/reverse cycles, or Stretch for a single stretched playback.

### Visualizer is not visible

Verify audio is loaded, a visualizer layer exists, and the layer is not hidden. Check opacity, color, low/high cut filters, and layer order.

### Lyrics do not appear

Verify a lyrics layer exists, the lyrics timeline is visible, and the current playhead time overlaps a lyric cue.

### Render fails with font errors

Confirm the selected font exists in the app font folder and appears correctly in the font dropdown.

### A recent project fails to open

The file may have moved or been deleted. Open it manually from its new location, or remove the stale recent-file entry by attempting to open it and letting the app forget it.