# Nexa for macOS

Beta version: 0.1.0

Nexa is the Nexus voice assistant for After Effects. It turns spoken or typed creative instructions into safe, confirmable After Effects actions. This beta installs a CEP panel plus the Nexa Electron voice overlay.

The current beta works with local command matching. No ChatGPT, Claude, OpenAI key, or Anthropic key is required to install it or use the included Skills.

## What You Get

- A Nexa CEP extension for After Effects.
- A macOS voice overlay that lets you speak or type commands.
- Local Skills for project cleanup, text animation helpers, expression presets, keyframe mirroring, 3D scene setup, and production utilities.
- Install and uninstall scripts for macOS.

## Install

1. Quit After Effects.
2. Unzip the download.
3. Control-click `INSTALL-macOS.command`, choose `Open`, then confirm if macOS blocks it.
4. Reopen After Effects.
5. In After Effects, open `Window > Extensions > Nexa`.
6. Start the overlay from `~/Applications/Nexa.command` if it is not already open.

The installer places the CEP extension here:

```text
~/Library/Application Support/Adobe/CEP/extensions/Nexus AE Voice Assistant Beta
```

The installer also enables local CEP beta loading so After Effects can run the extension.

## macOS Permissions

macOS may ask for permissions the first time Nexa, After Effects, Terminal, Python, or the overlay tries to listen or automate an action. The exact app name shown by macOS can vary by machine and macOS version.

### Microphone

Go to `System Settings > Privacy & Security > Microphone`.

Allow any app that is running the Nexa voice capture path, such as:

- Nexa
- Electron
- After Effects
- Terminal, iTerm, or Python if you are running a local speech server

If Nexa hears nothing, quit and reopen Nexa and After Effects after enabling Microphone permission.

### Dictation And Speech Recognition

Go to `System Settings > Keyboard > Dictation` and turn Dictation on.

If macOS also shows `System Settings > Privacy & Security > Speech Recognition`, allow the app that is capturing speech.

Dictation is used only to turn your spoken command into text. You can always type the same command directly in the overlay.

### Accessibility

Go to `System Settings > Privacy & Security > Accessibility`.

Allow After Effects and the app running Nexa if macOS blocks keyboard shortcuts, focus changes, or automation-style actions. If you launch from a `.command` file, macOS may also ask for Terminal permission.

### Automation Or Input Monitoring

If macOS shows an Automation or Input Monitoring prompt, allow it for Nexa, After Effects, Terminal, or Electron only when you are intentionally using Nexa. This helps the overlay communicate with the local After Effects extension and respond to shortcuts.

### If macOS Blocks The App

Control-click the blocked `.command` file, choose `Open`, then confirm. This is the normal macOS flow for beta tools that are not yet distributed through the App Store.

## How To Use Nexa

1. Open an After Effects project.
2. Open `Window > Extensions > Nexa`.
3. Open the Nexa overlay.
4. Select the layer, comp, or property you want Nexa to work on when the command needs a selection.
5. Speak or type a command.
6. Review the matched Skill and the confirmation summary.
7. Confirm to apply it, or cancel and rephrase.
8. Use After Effects `Edit > Undo` if you want to reverse the last action.

The safest way to work is to select the thing you mean first, then command Nexa. For example, select text layers before saying `apply soft wiggle`, or select animated layers before saying `mirror keyframes for out animation`.

## Commands That Work

These examples can be spoken or typed. Nexa accepts close variations, so you do not need to say the wording perfectly.

### Organize Project Folders

Say:

- `organize project folders`
- `clean up my project panel`
- `sort the After Effects project`
- `tidy project assets`

What it does:

- Sorts common project assets into folders.
- Helps keep comps, solids, media, and presets easier to scan.
- Works at the project panel level.

### Mirror Keyframes For Out Animation

Say:

- `mirror keyframes for out animation`
- `duplicate intro keyframes to the out point`
- `make the outro from my in animation`
- `copy position and scale keys to the layer out point`
- `mirror all animated properties for out animation`

What it does:

- Reads the intro or selected animated properties.
- Creates a matching exit animation near the layer out point.
- Can target position, scale, rotation, opacity, anchor point, selected properties, or all animated properties.

Best selection:

- Select the layer or properties that already have the intro animation.

### Expression Presets

Say:

- `apply soft wiggle`
- `apply hard pulse`
- `apply bouncer`
- `apply sway`
- `apply neon flicker`
- `apply hover`
- `apply spin`
- `apply random jitter`
- `I need inspiration`

What it does:

- Applies a local expression preset to the selected layer or property.
- Includes wiggle, hover, random jitter, opacity flicker, auto rotation, move forever, random position box, bouncer, pulse scale, and sway rotation.
- `soft`, `middle`, and `hard` can change the intensity for supported presets.

Best selection:

- Select the layer or property you want to animate.

### Fade Opacity Keyframes

Say:

- `fade in opacity keyframes`
- `fade out selected layers`
- `fade in and fade out opacity over 0.5 seconds`
- `add opacity keys at the in point and out point`

What it does:

- Adds simple opacity keyframes for a fade in, fade out, or both.
- Uses the layer in point and out point.

### Shake Or Wavy Adjustment Layer

Say:

- `add camera shake adjustment layer`
- `create quick hit shake`
- `add wavy distortion layer`
- `make a shake adjustment for 0.2 seconds`

What it does:

- Creates a short adjustment-layer style effect for impact, shake, jitter, wave, ripple, or glitch looks.
- Can understand duration, shake amount, frequency, rotation, wave amount, wave size, and wave speed.

### Center Parent Anchor

Say:

- `center null object`
- `center parent`
- `center parent anchor`
- `center null on child`
- `center child anchor point`

What it does:

- If a child layer is selected, Nexa moves its parent/null to the child's visual center while preserving the visible layout.
- If a parent/null has one child, Nexa can use that child automatically.
- If a parent/null has multiple children, Nexa asks which child to use.

### AE 3D World Scene Setup

Say:

- `set up 5 3d scenes`
- `create a 3d world with 4 scenes: intro, problem, proof, CTA`
- `build an AE 3D world with text intro, product demo, result and include image placeholders`
- `make 8 scene precomps in a 3d world called Nexus Pitch`

What it does:

- Creates a master 3D world composition.
- Adds scene precomps, text placeholders, optional image placeholders, camera target nulls, camera controls, and scene markers.
- Gives you a structured scene base that you can polish manually after generation.

### Animated Text Lines

Say:

- `create 6 animated text lines`
- `make compact text slides with lines "Hook" "Problem" "Solution"`
- `animated text lines slide in from top and out left`
- `add 3 more text lines`
- `refresh animated text lines`

What it does:

- Builds or updates a stack of animated text lines.
- Supports line count, font size, line spacing, horizontal repeats, stagger, duration, slide direction, fill/stroke style, opacity, and color.

### Infinite Text Rows

Say:

- `create infinite text sliders`
- `make repeating text rows saying NEXUS`
- `fill the frame with moving text`
- `create sliding text background with filled and stroke rows`
- `use this selected text layer for infinite rows`

What it does:

- Creates moving repeated text rows for backgrounds and graphic layouts.
- Can use provided text or a selected text layer as the source.
- Supports row spacing, speed, shift offset, fill color, stroke color, stroke width, opacity, and direction.

### Replace Project Text

Say:

- `replace text "OLD TITLE" with "NEW TITLE"`
- `change text Intro to Welcome`
- `update text "Sale" to "Launch"`

What it does:

- Searches project text and replaces matching layer text.
- Useful for template customization and batch changes.

### Replace Expression Text

Say:

- `replace expression text "wiggle(2,20)" with "wiggle(4,40)"`
- `batch replace expressions from speed to 120`
- `change expressions in selected layers from amp to amplitude`
- `replace expression text in active comp 4 levels deep`

What it does:

- Searches expression code and replaces matching snippets.
- Can work on selected layers, the active comp, nested precomps, or the active project depending on the command.

Use carefully:

- Expression replacement is powerful. Review the confirmation before applying it.

### Open Placeholders

Say:

- `open placeholders`
- `find logo placeholders`
- `show all placeholders in the active project`
- `open placeholders 6 levels deep`

What it does:

- Finds placeholder comps or layers so you can replace template content faster.
- Can search nested precomps.

### Deep Duplicate Composition

Say:

- `deep duplicate this comp`
- `duplicate composition with precomps`
- `copy the selected comp recursively`
- `duplicate preset with precomps`

What it does:

- Duplicates a composition and its nested precomps so the copy is more independent from the original.
- Useful when making multiple template versions.

### Preset Library And Saved Presets

Say:

- `open preset library`
- `browse presets`
- `save this comp as preset`
- `save selected comp as preset`
- `save this animation as preset`
- `apply my animation preset`

What it does:

- Opens the local preset/template browser.
- Saves selected comps or animation setups as reusable presets.
- Applies matching saved presets when available.

### Markers, Quality, Color, And Pointer Helpers

Say:

- `propagate parent markers`
- `sync markers from parent comp`
- `increase quality`
- `make this vector`
- `change this layer to red`
- `change fill and stroke color to blue`
- `add pointer proximity scale`
- `insert mouse cursor with hover color`

What it does:

- Copies useful timeline markers into child comps.
- Helps with vector/SVG quality workflows where supported.
- Changes selected layer colors.
- Adds pointer/cursor helper behavior for proximity-style motion graphics.

### Match Cuts And Transitions

Say:

- `add match cut`
- `slide match cut left`
- `slide jump cut right`
- `rotation match cut`

What it does:

- Applies local transition logic for supported match cut styles.

## Why Add ChatGPT Or Claude Later

Nexa is already useful because it converts common After Effects tasks into fast, confirmable actions. Adding an LLM such as ChatGPT or Claude would make it feel more like a creative assistant instead of a strict command menu.

An LLM can help because it can:

- Understand messy human language like `make this intro feel punchier and exit clean at the end`.
- Convert long creative requests into a structured Nexa command.
- Ask a follow-up question when the request is missing an important detail.
- Support different languages and non-perfect dictation.
- Explain what it is about to do before After Effects is changed.
- Chain multiple safe local Skills into one plan.

The safest architecture is:

1. User speaks or types a request.
2. The LLM interprets the request into a strict JSON plan.
3. Nexa validates that the plan only uses allowed actions.
4. Nexa shows a confirmation summary.
5. The user confirms before After Effects is changed.

For a commercial product, do not put your secret prompts, license logic, or private API keys inside the downloadable app. Keep the important LLM logic on your server when possible. The local app should send the user's request to your backend, receive an allowed command plan, and then run only approved local Skills.

If you let users enter their own ChatGPT or Claude API key, store it locally and make it optional. That is useful for power users, but it protects your product idea less than a backend-controlled LLM workflow.

## Troubleshooting

### The Installer Will Not Open

Control-click `INSTALL-macOS.command`, choose `Open`, then confirm.

### Nexa Does Not Hear My Voice

1. Check `System Settings > Privacy & Security > Microphone`.
2. Turn on `System Settings > Keyboard > Dictation`.
3. Check `System Settings > Privacy & Security > Speech Recognition` if it exists on your macOS version.
4. Quit and reopen Nexa and After Effects.
5. Type the command in the overlay to confirm the Skill itself works.

### The Extension Does Not Show In After Effects

1. Quit After Effects.
2. Run `INSTALL-macOS.command` again.
3. Reopen After Effects.
4. Open `Window > Extensions > Nexa`.

### A Command Does The Wrong Thing

Cancel the confirmation and rephrase with the selection and action included. For example:

```text
apply soft wiggle to the selected text layer
```

or:

```text
mirror selected position keyframes to the layer out point
```

### After Effects Blocks The Action

Check Accessibility, Automation, and Input Monitoring permissions in `System Settings > Privacy & Security`, then restart Nexa and After Effects.

## Uninstall

Run `UNINSTALL-macOS.command`, then restart After Effects.

## Beta Notes

- This beta is local-command based.
- ChatGPT or Claude interpretation is not required in this build.
- Always review the confirmation before applying project-wide, expression, cleanup, duplicate, or replacement commands.
- Keep a backup of important After Effects projects before testing beta automation tools.
