> For the complete documentation index, see [llms.txt](https://docs.amee.thiennguyen.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amee.thiennguyen.dev/features/visualizer.md).

# Audio Visualizer

Amee draws a real-time, audio-reactive visualizer that responds to whatever's actually playing through your Mac's speakers — not just from whichever app owns "now playing," but your system's actual audio output, so it reacts to anything making sound.

## Permission required

The visualizer needs permission to read system audio output, which macOS will prompt for the first time it's needed. If you don't see the visualizer reacting to sound:

1. Open **System Settings → Privacy & Security**, and look for Amee under the audio/screen-recording permission section for your macOS version.
2. Grant the permission.
3. Restart the visualizer — switching skins or relaunching Amee is enough.

This permission is separate from (and narrower than) Screen Recording, even though macOS may group them together in some versions.

## Building your own

Skin authors can read the same live audio data Amee's own built-in visualizer draws from to build a custom visualization. The SDK gives you explicit control:

* `amee.startVisualizer()` enables the system audio tap that feeds spectrum data — this is what triggers the macOS permission prompt if it hasn't been granted yet. Rejects if permission is denied.
* `amee.onSpectrum(cb)` subscribes to real-time FFT magnitude bins once the tap is running.
* `amee.stopVisualizer()` stops the tap when you no longer need it.

See [the SDK reference](/customization/sdk-reference.md) for full signatures and details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amee.thiennguyen.dev/features/visualizer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.