win-media-control

Node.js package for controlling Windows media playback. Works with Spotify, browsers (Chrome, Firefox, Edge), and any other app that integrates with Windows media controls.

Uses PowerShell to interact with Windows' System Media Transport Controls API.

Installation

npm install win-media-control

Requires Windows 10/11 and Node.js 14+.

Usage

import { play, pause, next, previous, stop, togglePlayPause, listSessions } from 'win-media-control';

List active sessions

const sessions = await listSessions();
console.log(sessions);
// Output:
// [
//   {
//     appName: 'Spotify',           // Friendly name
//     appId: 'Spotify.exe',          // Windows source ID  
//     title: 'Song Title',
//     artist: 'Artist Name',
//     playbackStatus: 'Playing'
//   },
//   {
//     appName: 'Mozilla Firefox',
//     appId: 'firefox.exe',
//     title: 'Video Title',
//     artist: '',
//     playbackStatus: 'Paused'
//   }
// ]

Firefox tabs are automatically detected even when they use cryptic session IDs.

Control playback

// Control specific apps
await play('Spotify');
await pause('Firefox');
await stop('Chrome');

// Track navigation
await next('Spotify');
await previous('Spotify');

// Toggle play/pause
await togglePlayPause('Firefox');

// Multiple apps
await play(['Spotify', 'Firefox']);
await next(['Spotify', 'Chrome']);

// Control all sessions (use "all")
await play('all');
await pause('all');

// Control current session (omit parameter)
await play();         // Control current session
await pause();        // Control current session
await next();         // Control current session
await previous();     // Control current session
await stop();         // Control current session
await togglePlayPause(); // Toggle current session

When you call functions without arguments, they control the current/focused media session directly through Windows' GlobalSystemMediaTransportControls API. This is more reliable than simulating keyboard input. If no current session is available, it automatically falls back to using SendKeys to simulate media key presses.

Use "all" to explicitly control all active sessions.

Functions return a result object with success and failed arrays:

const result = await pause(['Spotify', 'NonExistentApp']);
console.log(result);
// {
//   success: ['Spotify'],
//   failed: [{ app: 'NonExistentApp', reason: 'Session not found' }]
// }

CLI

# Control specific apps
npx win-media-control play Spotify
npx win-media-control pause Firefox Chrome
npx win-media-control next Spotify

# Control all sessions
npx win-media-control play all
npx win-media-control pause all

# Control current session (omit app parameter)
npx win-media-control play
npx win-media-control pause
npx win-media-control next
npx win-media-control toggle

npx win-media-control list

Install globally to drop the npx:

npm install -g win-media-control
win-media-control next
win-media-control pause Spotify

Debug

Set DEBUG=win-media-control to see what PowerShell commands are being run:

$env:DEBUG="win-media-control"
node your-script.js

TypeScript

Type definitions are included:

import { MediaSession, ControlResult, play, next } from 'win-media-control';

const sessions: MediaSession[] = await listSessions();

// Control specific app
const result: ControlResult = await next('Spotify');

// Control all sessions
await play('all');

// Control current session
await next();

How it works

Uses Windows' GlobalSystemMediaTransportControls API via PowerShell. Works with any app that integrates with Windows media controls (Spotify, VLC, browsers, etc).

When controlling specific apps, the library finds the matching session by app name and sends control commands directly to that session.

When no app is specified, the library uses GetCurrentSession() to control the currently focused media session. This is the most reliable method. If that fails (e.g., no current session), it falls back to using System.Windows.Forms.SendKeys to simulate media key presses (MEDIA_PLAY_PAUSE, MEDIA_NEXT_TRACK, etc.).

App names are resolved by checking the running process's FileDescription metadata.

Firefox quirk

Firefox uses dynamic session IDs like 308046B0AF4A39CB instead of a standard app identifier. When we see a cryptic ID that doesn't match a process, we check if Firefox is running.

Issues

If an app doesn't work, open an issue with the app name and what npx win-media-control list shows.

Troubleshooting

No sessions found: Make sure something is actually playing media.

App not found: Run npx win-media-control list to see available apps. Names are case-insensitive and partial matches work.

PowerShell errors: You might need to allow script execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Coming Later

These features could be added if there's interest:

• Seek/scrub to specific position
• Fast forward/rewind
• Playback rate adjustment
• Shuffle toggle
• Repeat mode control
• Volume control
• Get current position/duration
• Album art retrieval
• Timeline properties

Open an issue if you'd like any of these features.

License

MIT