Sound descriptors

Описание звуков, categories, fallback formats и preload.

Практическая схема

• Документация: NovaUIKit.
• Раздел: Motion и Sound.
• Тема страницы: Sound descriptors.
• Переключатель TypeScript / DSL находится в панели навигации; вкладка Код в примере показывает файлы выбранного подхода.

Исполняемый примерSound mixerИнтерактивные pads и Sound Engine lifecycle.

import { Nova, NovaNode, type NovaSchema } from '@endge/nova'

// Документационный сценарий: nova-sound-mixer
class ExampleNode extends NovaNode<Record<string, Event>> {
  render(): void {
    const schema: NovaSchema = [
      {
        type: 'rect',
        x: 24,
        y: 24,
        width: this.width - 48,
        height: this.height - 48,
        styles: { background: '#0d2745' },
      },
      {
        type: 'text',
        x: 44,
        y: 44,
        width: this.width - 88,
        height: 32,
        text: 'Sound mixer',
        styles: { color: '#e8f5ff' },
      },
    ]

    this.renderer.schema(schema)
    this.setRenderBoundsFromSchema(schema)
  }
}

export function mountExample(canvas: HTMLCanvasElement) {
  const app = Nova.createApp({
    target: canvas,
    size: { width: canvas.clientWidth, height: canvas.clientHeight, maxDpr: 2 },
    scheduler: { loop: false },
  })
  const surface = app.surface({ id: 'sound-mixer' })
  surface.createNode(ExampleNode)

  return () => app.destroy()
}

interface · @endge/nova

NovaSoundEngine

App-level сервис для загрузки, кеширования и воспроизведения коротких UI/game sounds.

class NovaSoundEngine

Lifecycle

Поле	Тип	Описание
load(descriptor | descriptor[])	Promise<void>	Нормализует descriptors, выбирает source format и кеширует decoded resource по id.
preload(...)	Promise<void>	Алиас для фоновой загрузки sounds до первого interaction.
unlock()	Promise<void>	Разблокирует Web Audio context после пользовательского жеста.
destroy()	void	Останавливает handles, очищает кеши и освобождает backend resources.

Playback

Поле	Тип	Описание
play(id, options)	NovaSoundHandle	Запускает one-shot или loop playback и возвращает управляемый handle.
stop(handle | id?)	void	Останавливает конкретный handle, все handles asset id или весь активный playback.
scope(name)	NovaSoundScope	Создает lifecycle-bound scope для scene/component sounds.
stats()	NovaSoundStats	Возвращает loaded/active/played/skipped/decoded и текущие mute/volume flags.

Mix

Поле	Тип	Описание
setMuted(muted)	void	Переключает master mute без изменения renderer state.
setVolume(volume)	void	Меняет master volume в диапазоне 0..1.
setCategoryVolume(category, volume)	void	Меняет GainNode категории: ui, fx, ambient или custom category.

interface · @endge/nova

NovaSoundDescriptor

Описание sound asset: id, source fallback, category, volume и ограничения playback.

interface NovaSoundDescriptor

Asset

Поле	Тип	Описание
idrequired	string	Публичный ключ asset для app.sound.play(id).
srcrequired	string | string[]	URL, data URI, nova-tone source или список format fallback.
category	string'default'	Mixer category для отдельной громкости.
preload	booleanfalse	Маркер намерения фоновой загрузки descriptor.

Playback defaults

Поле	Тип	Описание
volume	number1	Базовая громкость asset.
loop	booleanfalse	Default loop flag для play().
cooldownMs	number0	Минимальный интервал между playback одного dedupe key.
maxInstances	number	Лимит одновременных instances одного asset.
priority	number0	Приоритет при вытеснении из voice pool.

interface · @endge/nova

NovaSoundPlayOptions

Runtime overrides одного playback: mix, rate, pan, loop, dedupe и limits.

interface NovaSoundPlayOptions

Mix

Поле	Тип	Описание
volume	number	Громкость конкретного playback.
category	string	Переопределяет descriptor category.
pan	number	Stereo pan от -1 до 1, если backend поддерживает StereoPannerNode.

Behavior

Поле	Тип	Описание
rate	number1	Playback rate/pitch для коротких feedback sounds.
loop	boolean	Запускает loop playback, который нужно остановить handle/scope lifecycle.
dedupeKey	string	Останавливает предыдущий active playback того же key.
cooldownMs	number	Локальный cooldown для rapid hover/click.
priority	number	Приоритет вытеснения из maxVoices pool.

Как применять

Используйте страницу как короткую рабочую заметку: сначала определите границу ответственности, затем откройте пример и сравните TypeScript-реализацию с DSL-описанием. Runtime-код остается в Nova-слое, а Vue отвечает только за mount, layout shell и cleanup.