universal-media 🎵

A Node.js native module for controlling media playback and system audio. Built with Rust and OS specific APIs.

Example app built using @ultimateshadsform/universal-media:

Please always refer to GitHub README for the most up to date information.

Features 🚀

Media Control 🎮

• Get current media info (title, artist, album, albumArtist) 📝
• Get media thumbnail 🖼️
• Play/Pause/Stop control ⏯️
• Next/Previous track navigation ⏭️
• Get playback status 📊
• Event-based media state changes 🔄

Volume Control 🔊

• Get/Set system volume 🎚️
• Get/Set system mute status 🔇
• [TODO] Control individual application volumes 🎛️

Installation 📦

[!NOTE] This is a work in progress. API might change rapidly between releases. Right now only Windows is supported.

npm install @ultimateshadsform/universal-media

Usage 📖

Basic Usage

import { MediaController } from '@ultimateshadsform/universal-media';

// Create a media controller instance
const media = new MediaController();

// Get media info
const mediaInfo = await media.getMediaInfo();
console.log(mediaInfo);
// {
//   title: 'Song Title',
//   artist: 'Artist Name',
//   album: 'Album Name',
//   albumArtist: 'Album Artist',
//   playbackStatus: 'playing',
//   hasThumbnail: true,
//   thumbnailData: 'base64...'
// }

// Control playback
await media.play();
await media.pause();
await media.next();
await media.previous();
await media.stop();

// Control system audio
await media.setSystemVolume(0.5); // 0.0 to 1.0
await media.setSystemMute(true);

const volume = await media.getSystemVolume();
const isMuted = await media.getSystemMute();

Event System

Subscribe to media and system audio events:

const subscription = media.subscribeToEvents((event) => {
  switch (event.eventType) {
    case EventType.MediaChange:
    case EventType.PlaybackChange:
      console.log('Media Info:', event.mediaInfo);
      break;
    case EventType.VolumeChange:
      console.log('Volume:', event.volume);
      break;
    case EventType.MuteChange:
      console.log('Muted:', event.muted);
      break;
  }
});

// Clean up subscription when done
subscription.stop();

If you're still not sure how to use you can check out the testing directory on how I have implemented it in a Vue.js project.

Extras

Why does Spotify logo appear and why does it look so weird?

We grab image data directly from the system, so we cannot control how it looks. Try using some external tool such as sharp to process it.

Contributing 🤝

See CONTRIBUTING.md

License 📄

This project is licensed under the MIT License. See the LICENSE file for details.