MusicUiPlugin

MusicUiPlugin is the built-in transport UI for NMMusicPlayer. Drop it in when you want a ready-made album art display, track info block, seekable progress bar, and playback controls without building the DOM yourself. The plugin mounts a self-contained overlay inside the core-managed .nomercyplayer container and wires itself to player events automatically. State classes on the container (.playing, .paused, .muted, .buffering) are applied by the player core; the plugin reads them via CSS selectors so no extra toggling is needed.

TypeScript

import nmMPlayer from '@nomercy-entertainment/nomercy-music-player';
import { MusicUiPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';
import type { MusicUiOptions } from '@nomercy-entertainment/nomercy-music-player/plugins';

Plugin id: 'music-ui'

What it does

The plugin builds and inserts a .nmmusic-ui element into the player container on use(). It subscribes to player events (play, pause, ended, time, duration, volume, mute, repeat, shuffle, current, crossfadeStart, crossfadeComplete) and updates the overlay in response. Clicking the seek bar calls player.time(time) with the target position to perform the seek, and emits a seek event for observation. Volume slider orientation adapts to container width and touch capability unless you lock it with the volumeSlider option. Styles are injected once into the document on first use.

Options

Option	Type	Default	Description
`showAlbumArt`	`boolean`	`true`	Show the album art section.
`showTrackInfo`	`boolean`	`true`	Show the title, artist, and album block.
`showProgress`	`boolean`	`true`	Show the progress and seek bar row with current time and duration.
`showVolume`	`boolean`	`true`	Show the volume button and slider.
`showShuffle`	`boolean`	`true`	Show the shuffle toggle button.
`showRepeat`	`boolean`	`true`	Show the repeat mode button.
`showSpeed`	`boolean`	`false`	Show the playback-speed button. Most music listeners do not want speed control, so opt in explicitly.
`volumeSlider`	`'horizontal' \| 'vertical' \| 'auto'`	`'auto'`	Volume slider orientation. `'horizontal'` keeps an always-visible inline slider. `'vertical'` shows a popup slider above the mute button, toggled on click. `'auto'` switches to vertical when container width is 520 px or less, or on a touch-only device.

You can also update options after setup by calling player.getPlugin(MusicUiPlugin)!.options({ showSpeed: true }).

Events

Event	Payload	Description
`seek`	`{ time: number }`	Fires when the user drags or clicks the seek bar. `time` is the target position in seconds. The plugin calls `player.time(time)` internally to perform the seek, so this event is for observation only.

TypeScript

player.on('plugin:music-ui:seek', ({ time }) => {
  console.log('seeked to', time);
});

Methods

MusicUiPlugin exposes one public method beyond the base plugin API.

TypeScript

const ui = player.getPlugin(MusicUiPlugin)!;

// Read current options:
const currentOptions = ui.options();

// Apply a partial options update at runtime:
ui.options({ showSpeed: true, volumeSlider: 'vertical' });

DOM structure

Selector	Parent	Notes
`.nmmusic-ui`	player container	Root overlay element
`.nmmusic-art`	`.nmmusic-ui`	Album art section
`img.nmmusic-art-img`	`.nmmusic-art`	Album art image
`.nmmusic-art-placeholder`	`.nmmusic-art`	Shown when no cover is available
`.nmmusic-track-info`	`.nmmusic-ui`	Title, artist, and album block
`p.nmmusic-track-title`	`.nmmusic-track-info`	Track title
`p.nmmusic-track-artist`	`.nmmusic-track-info`	Artist name
`p.nmmusic-track-album`	`.nmmusic-track-info`	Album name
`.nmmusic-progress-row`	`.nmmusic-ui`	Seek bar and time labels
`span.nmmusic-time.nmmusic-current-time`	`.nmmusic-progress-row`	Elapsed time label
`.nmmusic-seek-bar [role=slider]`	`.nmmusic-progress-row`	Interactive seek bar
`.nmmusic-seek-buffer`	`.nmmusic-seek-bar`	Buffered range fill
`.nmmusic-seek-fill`	`.nmmusic-seek-bar`	Played range fill
`.nmmusic-seek-thumb`	`.nmmusic-seek-bar`	Drag handle
`span.nmmusic-time.nmmusic-duration-time`	`.nmmusic-progress-row`	Total duration label
`.nmmusic-controls-row`	`.nmmusic-ui`	Transport controls
`.nmmusic-btn[data-action=shuffle]`	`.nmmusic-controls-row`	Shuffle toggle, priority 3
`.nmmusic-btn[data-action=previous]`	`.nmmusic-controls-row`	Previous track, priority 2
`.nmmusic-btn.nmmusic-play-btn`	`.nmmusic-controls-row`	Play/pause, priority 0 (always visible)
`.nmmusic-btn[data-action=next]`	`.nmmusic-controls-row`	Next track, priority 2
`.nmmusic-btn[data-action=repeat]`	`.nmmusic-controls-row`	Repeat mode, priority 3
`.nmmusic-btn.nmmusic-speed-btn`	`.nmmusic-controls-row`	Speed button, hidden unless `showSpeed: true`
`.nmmusic-volume-group`	`.nmmusic-controls-row`	Volume button and slider wrapper
`.nmmusic-btn[data-action=mute]`	`.nmmusic-volume-group`	Mute toggle, priority 0 (always visible)
`input.nmmusic-vol-slider`	`.nmmusic-volume-group`	Horizontal volume slider
`.nmmusic-vol-slider-vertical`	`.nmmusic-volume-group`	Vertical mode popup
`input.nmmusic-vol-slider-vertical-input`	`.nmmusic-vol-slider-vertical`	Vertical slider input
`button.nmmusic-vol-popup-mute`	`.nmmusic-vol-slider-vertical`	Mute button inside vertical popup

Override the visual appearance by targeting these class names. The plugin injects minimal default styles, so you can override any property without specificity fights.

Responsive priority

Controls collapse at narrow widths via CSS container queries. Lower number means higher priority, meaning that control stays visible longest.

`data-priority`	Controls	Behaviour
`0` (none set)	Play, pause, mute	Always visible
`2`	Previous, next	Hide at narrower widths
`3`	Shuffle, repeat	Hide at narrowest widths

Registration

TypeScript

import nmMPlayer from '@nomercy-entertainment/nomercy-music-player';
import { MusicUiPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const player = nmMPlayer('main')
  .addPlugin(MusicUiPlugin)
  .setup({
    baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Music',
    playlist: [
      {
        id: 1,
        name: 'Thaw You Out',
        url: '/D/Derek Clegg/[2010] KJC/01 Thaw You Out.mp3',
        cover: '/D/Derek Clegg/[2010] KJC/cover.jpg',
      },
    ],
  });

With options:

TypeScript

const player = nmMPlayer('main')
  .addPlugin(MusicUiPlugin, {
    showAlbumArt: true,
    showTrackInfo: true,
    showProgress: true,
    showVolume: true,
    showShuffle: true,
    showRepeat: true,
    showSpeed: false,
    volumeSlider: 'auto',
  })
  .setup({ playlist: myTracks });

i18n

MusicUiPlugin registers its translation strings at load time under the plugin.music-ui.* namespace. All tooltip labels are in the plugin.music-ui.tooltip.* sub-namespace.

To override a label or add a new language, pass the keys through the player’s translations config:

TypeScript

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

player.setup({
  language: 'fr',
  translations: {
    ...defaultTranslations,
    fr: {
      'plugin.music-ui.tooltip.play': 'Lecture',
      'plugin.music-ui.tooltip.pause': 'Pause',
      'plugin.music-ui.tooltip.previous': 'Précédent',
      'plugin.music-ui.tooltip.next': 'Suivant',
      'plugin.music-ui.tooltip.shuffle': 'Aléatoire',
      'plugin.music-ui.tooltip.repeat': 'Répéter',
      'plugin.music-ui.tooltip.repeatOne': 'Répéter un',
      'plugin.music-ui.tooltip.mute': 'Muet',
      'plugin.music-ui.tooltip.unmute': 'Activer le son',
      'plugin.music-ui.tooltip.speed': 'Vitesse de lecture',
    },
  },
  playlist: [/* ... */],
});

To switch language at runtime:

TypeScript

await player.language('fr');