Skip to main content
Winamp is a fully functional music player that embeds the Webamp library to provide an authentic Winamp 2.9 experience.

​
Features

  • Authentic Winamp UI: Classic skins and interface
  • Playlist Management: Add, remove, reorder tracks
  • Audio Playback: Play WAV, MP3, OGG files
  • Equalizer: 10-band graphic equalizer
  • Visualizer: Oscilloscope and spectrum analyzer
  • Skin Support: Classic Winamp skins
  • Playlist Editor: Full playlist editing capabilities

​
Component Structure

Location: src/WinXP/apps/Winamp/index.jsx 
function Winamp({ onClose, onMinimize }) {
  const ref = useRef(null);
  const webamp = useRef(null);
  
  useEffect(() => {
    const target = ref.current;
    if (!target) return;
    
    webamp.current = new Webamp({
      initialTracks,
    });
    
    // Render Webamp directly into the target container
    webamp.current.renderWhenReady(target);
    
    // Cleanup function
    return () => {
      if (webamp.current) {
        webamp.current.dispose();
        webamp.current = null;
      }
    };
  }, []);
  
  useEffect(() => {
    if (webamp.current) {
      webamp.current.onClose(onClose);
      webamp.current.onMinimize(onMinimize);
    }
  });
  
  return <div style={{ width: '100%', height: '100%' }} ref={ref} />;
}

​
Configuration

​
App Settings

From apps/index.jsx: 
Winamp: {
  name: 'Winamp',
  header: { icon: winampIcon, title: 'Winamp', invisible: true },
  component: Winamp,
  defaultSize: { width: 0, height: 0 },
  defaultOffset: getCenter(0, 0),
  resizable: false,
  minimized: false,
  maximized: false,
  multiInstance: false,
}
Note: The header is set to invisible: true because Webamp provides its own window controls.

​
Initial Tracks

From config.js: 
const album = 'N/A';

export const initialTracks = [
  {
    url: `${import.meta.env.BASE_URL}music/addiction.wav`,
    duration: 288,
    metaData: {
      title: 'Addiction',
      artist: 'Jogeir Liljedahl',
      album,
    },
  },
  {
    url: `${import.meta.env.BASE_URL}music/youwillknow.mp3`,
    duration: 161,
    metaData: {
      title: 'You Will Know Our Names (Definitive Edition ver.)',
      artist: 'Kenji Hiramatsu',
      album,
    },
  },
  {
    url: `${import.meta.env.BASE_URL}music/man.ogg`,
    duration: 11,
    metaData: {
      title: 'man',
      artist: 'Toby Fox',
      album,
    },
  },
  {
    url: `${import.meta.env.BASE_URL}music/robocop.mp3`,
    duration: 118,
    metaData: {
      title: 'robocop.mp3',
      artist: 'Kombat Unit',
      album,
    },
  },
  {
    url: `${import.meta.env.BASE_URL}music/MIKEtheBOARDpleasey.wav`,
    duration: 118,
    metaData: {
      title: 'MIKE, the BOARD, please! (Skillz Productions Remake)',
      artist: 'Toby Fox',
      album,
    },
  },
];

​
Webamp Library

Webamp is a JavaScript implementation of Winamp 2.9 in the browser. It’s maintained at webamp.org.

​
Installation

npm install webamp

​
Basic Usage

import Webamp from 'webamp';

const webamp = new Webamp({
  initialTracks: [
    {
      url: '/music/track.mp3',
      duration: 180,
      metaData: {
        title: 'Track Title',
        artist: 'Artist Name',
        album: 'Album Name',
      },
    },
  ],
});

webamp.renderWhenReady(containerElement);

​
Track Format

Tracks must follow this structure: 
interface Track {
  url: string;           // Path to audio file
  duration: number;      // Duration in seconds
  metaData: {
    title: string;       // Track title
    artist: string;      // Artist name
    album: string;       // Album name (optional)
  };
}

​
Event Handlers

Webamp provides event handlers for integration: 
webamp.current.onClose(onClose);       // When user closes Winamp
webamp.current.onMinimize(onMinimize); // When user minimizes Winamp

​
Cleanup

Proper cleanup is essential to prevent memory leaks: 
return () => {
  if (webamp.current) {
    webamp.current.dispose();
    webamp.current = null;
  }
};

​
Adding Custom Tracks

To add more tracks, update the config.js file: 
export const initialTracks = [
  // Existing tracks...
  {
    url: `${import.meta.env.BASE_URL}music/newtrack.mp3`,
    duration: 240,
    metaData: {
      title: 'New Track',
      artist: 'New Artist',
      album: 'New Album',
    },
  },
];

​
Supported Audio Formats

  • MP3: MPEG Audio Layer 3
  • WAV: Waveform Audio File Format
  • OGG: Ogg Vorbis
Format support depends on browser capabilities.

​
Features Overview

​
Main Window

  • Play/Pause/Stop controls
  • Previous/Next track buttons
  • Volume control
  • Balance control
  • Time display (elapsed/remaining)
  • Track position scrubber
  • Shuffle and Repeat buttons
  • Equalizer toggle
  • Playlist toggle

​
Equalizer Window

  • 10-band graphic equalizer
  • Preamp slider
  • Preset dropdown
  • Auto/On/Off buttons

​
Playlist Window

  • Track list with title/artist/duration
  • Add files button
  • Remove track button
  • Shuffle list button
  • Sort options
  • File info display

​
Skins

Webamp supports classic Winamp skins (.wsz files). To use a custom skin: 
const webamp = new Webamp({
  initialTracks,
  initialSkin: {
    url: '/skins/custom.wsz',
  },
});

​
Usage Example

import { Winamp } from 'src/WinXP/apps';

function Desktop() {
  return (
    <Window 
      title="Winamp" 
      invisible={true} // Let Webamp control its own window
    >
      <Winamp 
        onClose={handleClose}
        onMinimize={handleMinimize}
      />
    </Window>
  );
}

​
Limitations

  • Window controls are managed by Webamp, not the parent window system
  • Cannot resize the Winamp windows (by design)
  • Only one Winamp instance allowed (multiInstance: false)
  • Audio playback requires user interaction (browser autoplay policies)

​
Advanced Configuration

Webamp supports many additional options: 
const webamp = new Webamp({
  initialTracks,
  initialSkin: { url: '/skins/custom.wsz' },
  availableSkins: [
    { url: '/skins/skin1.wsz', name: 'Skin 1' },
    { url: '/skins/skin2.wsz', name: 'Skin 2' },
  ],
  enableHotkeys: true,
  zIndex: 1000,
});
For full documentation, see Webamp Documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us