# Quickstart

Goal: get media into the matrix, trigger it, put it on a second display, and save your work. About
ten minutes.

Everything in this walkthrough uses the state a **new set** starts in, so it works whether you just
installed the app or just pressed **⌘N**.

## 1. What you are looking at

A new set opens with **one bank** called **Bank 1**, **four layers**, and **ten columns**. Open it
with **⌘N** (or **File → New set**).

- The first six columns arrive populated with generator clips; columns seven through ten are empty.
- Layers are named `Layer 4` down to `Layer 1`, top row first, and the third layer is selected.
- The composition is **1280 × 720** and tempo starts at **120 BPM**.
- The window opens at 1600 × 980 and can shrink to 1180 × 760.

The window has four working areas: the **library** sidebar on the left, the **clip matrix** filling
the middle, the row of **Preview / Inspector / Output** panels along the bottom, and the **footer**
of transport controls at the very bottom.

For the full map of the window, see [Interface tour](../using-ultimate-vj/interface-tour.md).

## 2. Trigger a clip

Click any populated tile. It starts playing on its layer.

One habit matters before anything else: **the right-hand 40% and top 50% of a tile is its preview
zone.** Clicking there auditions the clip in the Preview monitor instead of sending it to output.
Click the rest of the tile to trigger it live. There is a visible divider marking the boundary.

Generator clips loop by default, so they will keep playing until you trigger another clip on the
same layer or clear the layer.

## 3. Import your own media

Press **⌘I**, click **Import media** in the library sidebar, or click an empty tile.

Select one or more files. Multiple files land in **successive columns** on the selected layer, so
dropping in six clips fills six columns. Insertion can grow the grid and append an empty trailing
column. Explicitly removing the last empty column can leave the last column occupied; use
**Add column** in the Composition structure editor when needed.

Original files are never moved or copied. A set stores **paths** to your media.

Newly imported media triggers automatically on the first import. That setting —
**Trigger newly imported media** — is on by default and can be turned off in **Settings → General**.

Supported formats are broad: anything AVFoundation can read, plus a whitelist handled by the
bundled LGPL FFmpeg build. See [Media formats](../reference/media-formats.md).

## 4. Look at the Inspector

Click a clip once to select it. The bottom row becomes active: the **Preview** monitor on the left,
the **Inspector** in the middle, and the **Output** monitor on the right.

The Inspector is scoped. Pick **Clip**, **Layer** or **Master** at the top, and the tabs below change:

- **Clip** scope offers **Transform**, **Color**, **Effects**, **Audio** and **Transport**.
  **Source** appears additionally for native text or shader clips.
- **Layer** and **Master** scopes offer **Transform**, **Color**, **Effects** and **Layer**.

Try it: with a clip selected, open **Effects**, click **Add**, choose **Color correction**, and
drag **Saturation**. Trigger that clip to see its changes in program output. Use the eye for independent Preview audition.

See [The effect stack](../effects/effect-stack.md) for how ordering and blending work.

## 5. Put it on a real screen

Choose **Performance → Fullscreen output**, then pick your display.

Each entry reads `DISPLAY NAME · WIDTH × HEIGHT`. A menu entry with
`· current composition` appended means that display's native mode cannot be matched — either the
mode is not verifiable, or one of its dimensions exceeds 4096 pixels. In that case the composition
keeps its own size and is scaled to the display.

The fullscreen output window is video-only and covers the entire chosen screen including menu and
Dock. The console stays usable on any other display; **Escape** closes the output.

For building the set up before showtime without a second display, use **Performance → Open windowed
output** instead — same picture, resizable window.

## 6. Save your set

Press **⌘S**. The first save asks for a location and writes a `.uvj` file. Afterwards **⌘S** saves
in place.

Recovery is built in and on by default:

- Ultimate VJ **autosaves every 30 seconds** to
  `~/Library/Application Support/ULTIMATEVJ/Autosave.uvj` whenever there are unsaved changes.
- It restores that autosave on launch. Launch once with `--fresh` to skip the restore.
- Opening or creating another set while you have unsaved changes writes a recovery copy into
  `~/Library/Application Support/ULTIMATEVJ/Recovery/` first.

## 7. Two things worth switching on now

**File audio is off by default.** If you want sound from your clips, enable it in
**Settings → Clip audio → File playback → Enable file audio**. It stays off by design because it
changes the audio footprint of the app; see [File audio](../audio/file-audio.md).

**Nothing listens to your microphone by default.** If you want music-driven visuals, go to
**Settings → Audio input → Enable audio input**. The app will then request microphone permission.

## 8. Turn on the extras when you need them

Three subsystems are opt-in and start disabled:

| Feature | Where | Notes |
|---|---|---|
| Ableton Link | **Settings → Ableton Link → Enable Ableton Link** | Syncs tempo and bar phase only |
| Local control API (REST/OSC/WebSocket/MCP) | **Settings → Connections → Start local control** | Binds to `127.0.0.1` only |
| MIDI input | **Settings → MIDI → Connect MIDI** | Always starts disconnected |

## Where to next

- [Sets, banks, layers and clips](../using-ultimate-vj/sets-banks-layers-clips.md) — the mental model
- [Clips and transport](../using-ultimate-vj/clips-and-transport.md) — cue points, trim, playback modes
- [Tempo, Link and quantization](../timing/tempo-link-and-quantization.md) — beat-syncing everything
- [Output mapping](../output/output-mapping.md) — projecting onto angled or irregular surfaces