Overview

Volume methods control output level and mute state. The scale is 0–100 (not 0–1) to match the v1 API. The player translates to the 0–1 range internally when routing to the backend.

volume(level?)

Read or write the playback volume.

Read: volume() returns the effective level (0–100). Returns 0 when muted regardless of the stored pre-mute level.

Write: volume(level) clamps level to [0, 100], persists it, and routes the new value to the active backend. Fires beforeMutation (cancellable) then volume. No-op when the mutation is cancelled.

Returns: number | void

Events emitted: volume with { level: number }

// read
const current = player.volume(); // e.g. 75

// write
player.volume(50);

Persisting volume is a plugin concern, so use the namespaced storage adapter (this.storage), not raw localStorage. The adapter is auto-scoped per player, async-compatible, and swappable via setup({ storage }):

import { Plugin } from '@nomercy-entertainment/nomercy-player-core';

class VolumeMemoryPlugin extends Plugin {
  static readonly id = 'volume-memory';

  async use() {
    const saved = await this.storage.getJSON<number>('level');
    if (saved !== null) this.player.volume(saved);
    this.on('volume', ({ level }) => this.storage.setJSON('level', level));
  }
}

player.addPlugin(VolumeMemoryPlugin);

mute()

Silence output without discarding the current volume level. Persists the current level so unmute() can restore it. No-op when already muted.

Events emitted: mute with { muted: true }

unmute()

Restore output after mute. Reinstates the level saved by the last mute() call. No-op when already unmuted.

Events emitted: mute with { muted: false }

toggleMute()

Flip between muted and unmuted. Delegates to mute() or unmute().

button.addEventListener('click', () => player.toggleMute());

player.on('mute', ({ muted }) => {
  muteButton.setAttribute('aria-pressed', String(muted));
});

volumeUp(step?)

Raise volume by step percentage points. Delegates to volume().

volumeDown(step?)

Lower volume by step percentage points. Delegates to volume().

// keyboard volume controls
document.addEventListener('keydown', (event) => {
  if (event.key === 'ArrowUp') player.volumeUp();
  if (event.key === 'ArrowDown') player.volumeDown();
  if (event.key === 'm') player.toggleMute();
});

See also

• Events Reference: volume, mute
• Playback State: volumeState()