# One-projector projection mapping with PHASE//VOID

Canonical guide: https://phasevoid.com/guides/projection-mapping/
Updated: 2026-10-25

## Start with one output

Use one computer and one connected projector display. Up to eight mapped surfaces share one raster and audio source. Public tools are free with no account. Loxone is optional separate room automation.

## Get one surface working

1. In Output choose the display ratio and resolution.
2. Open projector window, move it to the intended display and double-click for fullscreen. Keep Studio visible.
3. Enable Mapping, select one surface, calibrate its corners and turn the pattern off.
4. Choose Program for the complete composition or an independent world with its own look/FX.
5. Rehearse real sound and Freeze/Blackout, save/reopen the map or session and inspect the physical result. Settings do not package the music or video.

[Open Mapping without replacing settings](https://phasevoid.com/studio/?panel=mapping). Browser permissions remain independent: [window.open](https://developer.mozilla.org/en-US/docs/Web/API/Window/open), [fullscreen](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullscreen).


## Fit the final picture to one projector

Open [Studio → Mapping](https://phasevoid.com/studio/?flow=live&panel=mapping). Up to **eight surfaces share one final output**, each choosing **Program** (the complete composition) or its own procedural world and surface effects. They share one audio source and raster output, rather than independent clip decks or physical projector routes. Program includes global effects, title and artwork before mapping.

![Actual Studio Mapping inspector with a numbered-grid calibration pattern and surface corner handles](https://phasevoid.com/media/examples/projector-mapping-studio.png)

This real local screenshot from the initial mapping release shows the geometry editor and calibration image. Independent source and surface-effect controls were added afterward. It is not a photograph of a physical projector or proof of venue alignment. Corner and mask handles are Studio controls; they are absent from the final projector/recording image.

### Choose what each surface plays

![Two independent procedural worlds and their surface controls](https://phasevoid.com/media/examples/independent-surface-visuals.png)

First-party browser capture: Rave fan with surface FX on the left, Chrome knot on the right, both driven by the same WAV.

In **Mapping → Surface visual → Visual source**, select **Program · shared final picture** or one of the 108 procedural worlds. Program is the default: it includes the single-world or A/B base, video clips, global output effects, title and artwork. An independent world has its own palette, Audio response, Motion speed and Glow, plus Detail, Zoom, Rotation, Symmetry, Grain and Chromatic light under More visual controls, excluding Program clips, overlays and global effects. Motion speed changes visual movement, not a separate audio track or detected BPM. **Use current studio look** copies the current procedural world and look into the surface; **Reset visual look** restores that world's defaults.

Each surface has a **Surface FX** rack with **Kaleidoscope → Pixelation → RGB split**, **FX amount**, **Link amount to audio**, **Bypass surface FX** and **Reset surface FX**, working inside its selected source crop, before corner geometry and masks, in that fixed order. The global Effects rack still belongs to Program. Every surface uses the same connected audio and selected pulse; **Freeze, Blackout and Gentler motion** remain global. Calibration patterns replace all sources and bypass the surface racks.

Maps, sessions, duplicate and undo/redo preserve source, look and surface effects. Older maps default to Program with neutral surface effects. Live independent-world rendering uses one additional reusable renderer context, a budget of **4,194,304 source pixels** and **1920-pixel edge limit**; sources downsample with Render detail when needed. A larger output does not imply native-resolution sources or guaranteed frame rate.

### Preview a surface look before taking it live

Select the surface in **Mapping**, then choose **Browse & tune world**. **Surface Look Studio** names its destination. Search the existing library and tune a copied world look and **Surface FX** off air. **Reset draft** restores the opening draft; **Cancel** discards your edits.

The muted moving preview uses current audio analysis, scene clock and selected pulse when available. It shows **only the procedural source and its surface FX**: no source crop, calibrated corners, masks, opacity/blend, clips, title/artwork or master FX. It starts no audio and requests no input permission. A reference still and status remain if moving preview is unavailable; a still does not prove the tuned result.

**Take to [surface name]** changes only that surface's visual and effects, keeping geometry, masks, crop, opacity, blend, visibility, order and all other surfaces. **Mapping Undo** restores the earlier take. Check the final mapped picture, then save your map/session or capture the look in a cue. Draft opening and Take are blocked during recording, cue playback/preparation, transitions and active A/B mixing. Moving preview stops during recording and when closed or hidden.

1. Set output dimensions and aspect ratio for the intended display. Open the projector window, allow the popup, move it to that display and double-click for fullscreen. Keep Studio visible. Recheck alignment after output-size, projector-placement or display-layout changes.
2. Enable mapping and use the grid, checkerboard, color or white test pattern. Select a surface and adjust its four corners through Studio handles or numeric positions. The corners must form a convex non-crossing quadrilateral inside the frame. The projective transform changes perspective across the whole surface.
3. Choose a rectangle, ellipse or simple non-crossing polygon mask with **3–16 vertices**. Source crop chooses part of the composed image; the mask controls its visible shape on that surface. Use undo/redo to recover an earlier edit.
4. Add, name, hide and reorder surfaces. Tune opacity and **Normal, Screen, Add, Multiply or Difference**. Feather softens local mask edges; it does not correct projector brightness or provide multi-projector edge blending.
5. Use Save map to download JSON, or include the map in a session; configuration is also remembered locally. Stop recording before Import map. Import checks format, limits and geometry. A map contains configuration, not audio, artwork or video bytes; selected media is not uploaded. Reattach media after restoring. Reloading does not restart calibration patterns.
6. Choose **Off · show visuals**, then switch from Mapping to Layers or Effects. Studio-only corner/mask handles never enter the final image. **Stage, projector and real-time recording receive the same mapped output.** Record, download and reopen a short take with sound. Check shape, crop and absence of handles, then test Freeze and Blackout.

**Freeze** holds the complete mapped frame. **Blackout** masks every surface, title and calibration pattern. Patterns are intentional output images: disable them before an ordinary set or recording. Loading configuration does not start audio or grant browser permissions.

This is single-projector raster mapping. There is no multi-projector routing, 3D mesh, projector edge blending, automated room calibration or native OSC/NDI/Spout/Syphon/DMX output. Browser popup, fullscreen, tab visibility and GPU limits still apply. Saved geometry does not establish physical alignment or hours-long performance. [MCP](https://phasevoid.com/connect/mcp/) describes the capability; its read-only projection planner returns starter map JSON; it cannot apply or calibrate a map.


## Diagnose and rehearse

Blackout, Freeze, calibration and hidden surfaces are separate checks. Look edits the main world; independent sources need their own Mapping controls. [Check my setup](https://phasevoid.com/guides/troubleshooting/#setup-check) reads current states without changing them. [Original three-surface show](https://phasevoid.com/guides/live-visuals/#mapped-show-kit). A browser recording is not physical alignment, latency, brightness-matched edge blending or long-show proof.

## Choose a starter layout

Use the existing planner to review screen, triptych, corner or booth geometry, sources, frame and audio. Choose File for your own soundtrack. The optional show builder is not needed for a single surface. Normalized geometry still needs real calibration.

## One-projector starter planner

[Build a projection setup](https://phasevoid.com/guides/projection-mapping/#projection-starters) in the existing live guide. Choose One screen (1 surface), Triptych (3), Room corner (2) or DJ booth + wings (3). These are editable normalised corner maps, not measured room geometry or automatic physical calibration.

Select Program or independent procedural worlds. Program Triptych crops the composed picture into equal left/centre/right thirds; Program Corner uses its left/right halves. Screen and Booth repeat the complete Program picture. Independent surfaces use the full selected world with a fixed editable starter look, rather than a crop of Program. All surfaces share one sound input and one output raster.

Choose 16:9, 4:3, 9:16 or 1:1; short edge 540, 720, 1080 or 2160; gentler/full motion; and a demo, local-file or live starting path. At 720 these frames are 1280×720, 960×720, 720×1280 and 720×720. Match the projector's working raster and test actual output capacity.

Download customised map JSON locally or follow the Studio link. Studio opens Mapping and shows the planned recipe, keeping the previous map and canvas until **Apply layout & canvas**. That explicit action adds the previous map to Mapping Undo and applies the planned output dimensions/motion. Mapping Undo restores map geometry/sources, not the earlier canvas dimensions. Audio and input permission still require a separate click. A calibration pattern is not started by the link or layout application.

Map JSON is compatible with Mapping → Import map, includes geometry/crops/source looks and no media, and does not include audio/canvas settings. A setup link adds those public starting choices for review; it does not contain songs, private surface names or files. Copying a link does not publish it to another person.

Static downloads work without JavaScript:
- One screen: [Program map](https://phasevoid.com/media/maps/screen-program.json), [Independent-world map](https://phasevoid.com/media/maps/screen-independent.json)
- Triptych: [Program map](https://phasevoid.com/media/maps/triptych-program.json), [Independent-world map](https://phasevoid.com/media/maps/triptych-independent.json)
- Room corner: [Program map](https://phasevoid.com/media/maps/corner-program.json), [Independent-world map](https://phasevoid.com/media/maps/corner-independent.json)
- DJ booth + wings: [Program map](https://phasevoid.com/media/maps/booth-program.json), [Independent-world map](https://phasevoid.com/media/maps/booth-independent.json)

After applying: connect sound, align the corners to real surfaces, check a numbered grid and switch calibration Off, then save/restore a map and make a short checked recording. Multiple independent worlds and high output dimensions are not a sustained-FPS guarantee. The diagram only explains the layout; it is not live output or evidence of physical projector alignment.


### Build and reopen a mapped show

After applying and aligning the map, Mapping → Surface show can append four Manual-hold cues: Intro captures the current look; Build, Drop and Breakdown use different procedural worlds per surface while keeping your surface FX. It does not replace existing cues or start playback. Add current look captures Program and surface looks when Mapping is enabled. Edit cue → Recapture current Program & surfaces updates a cue after tuning, keeping its name and hold.

Surface cues can Cut, Dissolve, Dip or Wipe. Recall restores visuals, surface FX, crops, visibility, opacity and blend, while preserving current corners, masks, canvas and Mapping enable. Program-only cues may dissolve. Missing surface IDs stop the sequence without changing the output: reopen its session or recapture the cue. Manual, seconds and manual-BPM bar holds remain available.

Save full session contains the map, canvas, cues, timing and mixer. A map JSON file or starter recipe does not contain the later cue show. Audio, artwork and video remain separate; reattach media after reopening. The queue never starts automatically. Current Freeze, Blackout and Gentler motion remain global. Global Program rack effects and video clip switching are not per-cue controls.

## Build your own complete mapped show

Use the [existing one-projector planner](https://phasevoid.com/guides/projection-mapping/#projection-starters) to create a complete session, rather than choosing a fixed four-act example. Map-only downloads and their separate Studio handoff remain available.

1. Choose **One screen**, **Triptych**, **Room corner** or **DJ booth + wings**. Use **Program** for one world per act, or **independent worlds** for one world per surface, up to three. Choose the canvas shape, short-edge size, motion and demo/file/live audio starting path.
2. Create **2–8 acts** with worlds, palette and surface FX: **Off**, **Kaleidoscope**, **Pixelation** or **RGB split**. Choose **Cut**, or **Dissolve**, **Dip** or **Wipe** lasting **0.25–4 seconds**. Holds are **Manual**, **0.25–3600 Seconds** or **1–64 Bars**. Bars use an entered whole **30–300 BPM** and **4/4 timing**, not automatic audio-tempo detection. Select two different acts for the saved **A** and **B** picture banks.
3. Follow **Review my show in Studio**. Generating or copying a link does not open Studio. Opening the review link does not replace settings, run cues, start the mixer, play audio or request input permission. Review the plan, stop recording or an active mix, then press **Load planned show**. **Undo planned show** restores the replaced settings in this tab, until reload. Save a session before leaving; media files need reattaching.
4. Click **Open test audio**, choose your own local MP3/WAV, or connect a live input. The test WAV is **160 BPM**; changing the planned BPM changes bar timing, not playback speed. Align the map's corners and masks to real surfaces and switch calibration **Off**. Fire acts in **Show sequence**, or perform with the saved banks in **Live mixer**. Cue recall and mixing preserve current mapping geometry.
5. Download the planned **full Session JSON**, or use **Save full session** after editing in Studio. Import does not start the cue queue or mixer; audio transport is separate. Reconnect media when reopening. Run the [output check and a short recording](https://phasevoid.com/guides/troubleshooting/) before a performance.

### What the file and link contain

**Full Session JSON** includes map geometry, canvas, cues, timing and saved A/B settings. It contains no audio, artwork or video bytes. A **map-only JSON** contains its map and looks, without the show's canvas, timing or acts.

**Copy show setup link** shares a public recipe of IDs, choices and numbers. Fixed act labels are Intro, Build, Drop, Breakdown and Act 5–8; rename them locally in Studio. Private names, titles, files, later room calibration and subsequent show edits are not included. Recipients and normal hosting requests can read the public choices. Copying a link does not send it to another person. Use a saved full session to retain later Studio edits.

The diagram and scene references are static aids, not moving previews or physical projector evidence. All surfaces share one audio input and one output raster; two moving banks share **4,194,304 source pixels**. The planner does not measure a room, route several projectors, edge-blend projectors or generate a 3D mesh. Test the actual setup; short software checks do not establish sustained frame rate or hours-long reliability.