audio-spatial — правило для Claude Code: что делает и как установить
Правило audio-spatial для Claude Code задаёт шаблоны настройки 3D-звука в Three.js: позиционирование источников, затухание и реакцию на действия пользователя.
MIT ★ 4 719 обновлён 2026-10-24
.claude/rules/audio-spatial.mdЧто делает audio-spatial
Правило задаёт шаблоны кода для подсистемы звука Three.js: подключение AudioListener к камере, фоновый звук через Audio и пространственный звук с PositionalAudio. Включены параметры дистанции (linear, inverse, exponential), панорамирование через HRTF и расчёт направленности звукового конуса.
Внутри также собраны инструкции по загрузке файлов через AudioLoader, использованию анализатора AudioAnalyser для визуализаций и переиспользованию аудиобуферов.
Браузерная политика блокирует автовоспроизведение: без клика или нажатия пользователя метод listener.context.resume() не сработает и звук останется заглушённым.
Какие задачи решает
- привязать пространственный звук PositionalAudio к 3D-объектам сцены
- настроить затухание звука по моделям inverse, linear или exponential
- обойти блокировку автовоспроизведения через возобновление AudioContext
- подключить AudioAnalyser для создания визуализаций под частоты трека
Примеры запросов агенту
- Добавь пространственный звук шагов к мешу персонажа с затуханием по модели inverse
- Настрой запуск фоновой музыки по клику на кнопку через AudioContext resume
- Сделай визуализатор частот для аудиофайла с помощью Three.js AudioAnalyser
Как установить audio-spatial
Вручную: положить файлы
.claude/rules/audio-spatial.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/audio-spatial.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/audio-spatial.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/audio-spatial.mdВручную: положить файлы
.clinerules/audio-spatial.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы об audio-spatial
Как установить audio-spatial в Claude Code?
Добавьте файл правила по пути .claude/rules/audio-spatial.md в корень вашего репозитория.
Что делает правило audio-spatial?
Оно даёт ассистенту примеры реализации пространственного звука в Three.js, включая PositionalAudio, расчёт дистанции и конусов направленности.
Почему звук в браузере не играет автоматически?
Политика браузеров требует явного действия пользователя, поэтому запуск воспроизведения и вызов listener.context.resume() нужно привязывать к событию клика.
Исходный текст
audio-spatial.md · MIT
# Spatial Audio
Three.js audio system for 3D positional sound.
## Components
```javascript
import * as THREE from 'three';
// AudioListener - represents user position (attach to camera)
const listener = new THREE.AudioListener();
camera.add(listener);
// Audio - non-positional (background music)
const sound = new THREE.Audio(listener);
// PositionalAudio - 3D spatial sound
const positionalSound = new THREE.PositionalAudio(listener);
mesh.add(positionalSound);
```
## Loading Audio
```javascript
const audioLoader = new THREE.AudioLoader();
audioLoader.load('sound.mp3', (buffer) => {
sound.setBuffer(buffer);
sound.setLoop(true);
sound.setVolume(0.5);
sound.play();
});
```
## PositionalAudio Configuration
```javascript
const positionalAudio = new THREE.PositionalAudio(listener);
// Reference distance (max volume distance)
positionalAudio.setRefDistance(1);
// Maximum distance
positionalAudio.setMaxDistance(100);
// Rolloff model: 'linear', 'inverse', 'exponential'
positionalAudio.setRolloffFactor(1);
positionalAudio.setDistanceModel('inverse');
// Panning model: 'HRTF' (realistic) or 'equalpower'
positionalAudio.panner.panningModel = 'HRTF';
// Directionality (cone)
positionalAudio.setDirectionalCone(180, 230, 0.1);
// innerAngle, outerAngle, outerGain
```
## Distance Models
| Model | Behavior |
|-------|----------|
| `linear` | Linear decrease from ref to max distance |
| `inverse` | Inverse relationship (realistic) |
| `exponential` | Exponential falloff |
## Audio Controls
```javascript
// Play/pause
sound.play();
sound.pause();
sound.stop();
// Volume
sound.setVolume(0.5); // 0.0 to 1.0
// Playback rate
sound.setPlaybackRate(1.5);
// Loop
sound.setLoop(true);
// Check state
if (sound.isPlaying) { }
// Duration
const duration = sound.buffer.duration;
// Current time
sound.offset; // read
```
## Audio Analyzer
```javascript
const analyser = new THREE.AudioAnalyser(sound, 32);
function animate() {
const data = analyser.getAverageFrequency();
// Use data for visualizations
mesh.scale.setScalar(1 + data / 256);
}
```
## Multiple Audio Sources
```javascript
// Background music
const bgMusic = new THREE.Audio(listener);
audioLoader.load('music.mp3', (buffer) => {
bgMusic.setBuffer(buffer);
bgMusic.setLoop(true);
bgMusic.setVolume(0.3);
});
// Spatial sounds on objects
objects.forEach((obj, i) => {
const sound = new THREE.PositionalAudio(listener);
audioLoader.load(`sound${i}.mp3`, (buffer) => {
sound.setBuffer(buffer);
sound.setRefDistance(5);
sound.setLoop(true);
});
obj.add(sound);
});
```
## User Gesture Requirement
Audio requires user interaction to start (browser policy):
```javascript
const startButton = document.getElementById('start');
startButton.addEventListener('click', () => {
// Resume AudioContext
if (listener.context.state === 'suspended') {
listener.context.resume();
}
sound.play();
startButton.style.display = 'none';
});
```
## Best Practices
1. **HRTF**: Use `panningModel: 'HRTF'` for realistic 3D audio (best with headphones)
2. **User Gesture**: Always require user interaction before playing audio
3. **Dispose**: Call `audio.disconnect()` when removing sounds
```javascript
sound.stop();
sound.disconnect();
```
4. **Mobile**: Audio consumes significant battery on mobile devices
5. **Buffer Reuse**: Reuse audio buffers for repeated sounds
```javascript
const sharedBuffer = await loadBuffer('shoot.mp3');
function playShot(position) {
const sound = new THREE.PositionalAudio(listener);
sound.setBuffer(sharedBuffer);
sound.position.copy(position);
scene.add(sound);
sound.play();
sound.onEnded = () => {
scene.remove(sound);
sound.disconnect();
};
}
```
6. **Volume Levels**: Keep sound effects around 0.3-0.7, music around 0.2-0.4
7. **Ref Distance**: Set refDistance to the size of the emitting object
## Audio Formats
| Format | Browser Support | Notes |
|--------|-----------------|-------|
| MP3 | All | Good compression, universal |
| OGG | Chrome, Firefox | Better quality at same size |
| WAV | All | Uncompressed, large files |
| AAC | All | Good for music |
## References
- [Three.js Audio](https://threejs.org/docs/#api/en/audio/Audio)
- [Three.js PositionalAudio](https://threejs.org/docs/#api/en/audio/PositionalAudio)
- [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
© zebbern · MIT · zebbern/claude-code-guide