Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

webamp

captbaritone2.4kMIT2.1.2TypeScript support: included

Winamp 2 implemented in HTML5 and JavaScript

Winamp, HTML5, audio, web-audio-api

readme

gzip size Discord

Webamp

A reimplementation of Winamp in HTML5 and JavaScript with full skin support. As seen on TechCrunch, Motherboard, Gizmodo, Hacker News (1, 2, 3, 4), and elsewhere.

Screenshot of Webamp

Check out this Twitter thread for an illustrated list of features. Works in modern versions of Edge, Firefox, Safari and Chrome. IE is not supported.

Read the docs

The Webamp Documentation site contains detailed instructions showing how to add Webamp to your site and customize it to meet your needs.

About This Repository

Webamp uses a monorepo approach, so in addition to the Webamp NPM module, this repository contains code for a few closely related projects and some pieces of Webamp which are published as standalone modules:

Community

Join our community chat on Discord: https://discord.gg/fBTDMqR

Related communites:

In the Wild

An incomplete list of websites using Webamp:

Thanks

  • Butterchurn, the amazing Milkdrop 2 WebGL implementation. Built and integrated into Webamp by: jberg
  • Research and feature prototyping: @PAEz
  • Beta feedback, catching many small UI inconsistencies: LuigiHann
  • Beta feedback and insider answers to obscure Winamp questions: Darren Owen
  • Donating the webamp NPM module name: Dave Eddy

Thank you to Justin Frankel and everyone at Nullsoft for Winamp which inspired so many of us.

License

While the Winamp name, interface, and, sample audio file are surely property of Nullsoft, the code within this project is released under the MIT License. That being said, if you do anything interesting with this code, please let me know. I'd love to see it.

Development

This repository uses Turborepo for efficient monorepo management. Turborepo provides intelligent caching and parallel execution of tasks across all packages.

Quick Start

# Install dependencies
pnpm install

# Build all packages (automatically handles dependencies)
npx turbo build

# Build library bundles for packages that need them
npx turbo build-library

# Run all tests
npx turbo test

# Lint and type-check all packages
npx turbo lint type-check

# Work on a specific package and its dependencies
npx turbo dev --filter="webamp"

Package Dependencies

The monorepo dependency graph is automatically managed by Turborepo:

  • ani-cursor and winamp-eqf are standalone packages built with TypeScript
  • webamp depends on both ani-cursor and winamp-eqf for workspace linking
  • All packages are built in the correct topological order
  • Builds are cached and only rebuild what has changed

Available Tasks

  • build - Main build output (Vite for demos, TypeScript compilation for libraries)
  • build-library - Library bundles for NPM publishing (only applies to webamp)
  • test - Run unit tests with Jest
  • type-check - TypeScript type checking without emitting files
  • lint - ESLint code quality checks
  • dev - Development server (for packages that support it)

For more details on individual packages, see their respective README files.

changelog

Upcoming [UNRELEASED] (webamp@next)

No changes yet.

2.1.2 [CURRENT]

Bug Fixes

  • Avoid opening Milkdrop window when no window layout is provided.
  • Work around issue where setImmediate was not accessible to JSZip when parsing skins.

2.1.0

Bug Fixes

  • Fixed "Generate HTML Playlist" feature, which was accidentally broken in 2.0.0.

Improvements

  • Improve skin parsing performance and avoid Chrome console warning by adding willReadFrequently to canvas contexts.
  • Define an explicit IMedia interface for custom media implementations, which allows for better type checking and documentation.
  • Added new Webamp instance methods:
    • webamp.isShuffleEnabled
    • webamp.isRepeatEnabled
    • webamp.setCurrentTrack
    • webamp.getPlaylistTracks

2.0.1

Bug Fixes

Fixed incorrectly built artifacts.

2.0.0

Broken release. Use 2.0.1 instead.

Features

  • Allow a single mouse drag across the EQ to set all values #1180
  • Configure the initial layout of windows -- size, position, openness, shade mode -- when constructing a Webamp instance. See windowLayout in the Usage docs for more information.
  • Configure if "double size mode" should be enabled when constructing a Webamp instance. See enableDoubleSizeMode in the Usage docs for more information.
  • Optically allow users to lazily load heavy dependencies like JSZip and music-metadata-browser with the webamp/lazy entry point.
  • Include source maps for non-minified bundles.

Bug Fixes

  • Fix bug where track position slider could get stuck on mobile. PR

Internal Improvements:

  • Upgrade to React 18, React Redux, 8 and Redux 4.1
  • Bundle with Rollup instead of Webpack
  • Build public Typescript directly from source annotations.
  • We no longer transform object spreads since they have broad support in browsers.

1.5.0

Features

  • Support .ani cursors in skins #1035, blog post.
  • Improved support for mobile/touch screen interaction: volume, balance and position sliders, marquee, playlist and window dragging/resizing/focusing. #1098/#1099

Bug Fixes

  • Fix a number of edge cases where the close and minimize buttons in the equalizer window could render the wrong sprite #1046
  • Fix a bug where unminified bundle was accidentally minified.
  • Treat skin files with forward slashes in their filename as directories #1052
  • Fix a bug where the Milkdrop window could not be moved in some cases #1068
  • Fix a bug where the visualizer in the Playlist window was not hidden when audio was stopped. #1072
  • Fix a bug where the marquee was one pixel too narrow #1087
  • Fix a bug that was preventing the "Misc options" playlist submenu from opening. c9fe24
  • Rename the .status class to .webamp-status to avoid potential conflicts with host site. #1116

1.4.2

Bug Fixes

  • Add webamp.close() method to public TypeScript types.

1.4.1

Features

  • New Webamp instance method: .setSkinFromUrl(url). See usage.md for more details.
  • New Webamp instance method: .close(). See usage.md for more details.

Bug Fixes

  • Fix a bug where skins missing some images would fail to load 2e8392
  • Clicking on the lightning icon in the main window now correctly opens our about page in a new tab #794
  • Skin .ini files can use = as a comment separator 577b5e3
  • We nolonger cycle Milkdrop presets when media is not playing #799
  • Guard against some kinds of malformed region.txt files 0bd8b0

1.4.0

Features

  • Added optional configuration option handleTrackDropEvent which lets you decide how drop events get converted into tracks.
  • New Webamp instance methods: .stop(), .getMediaStatus(), and .seekToTime(seconds). See usage.md for more details.
  • Windows are now layered in the order in which they were focused (5ee1a4)
  • When focusing something other than Webamp, it's now possible for no windows to be selected (6132ac)

Bug Fixes:

  • Fix a bug where context menus could appear in the wrong location (95db2d)
  • Fix a bug where pressing next/previous when stopped would play the track (#740)
  • Fix a bug where webamp.dispose would error if the #webamp node had been reparented to anything other than document.body.
  • Fix a bug where tracks dropped in the main window were not autoplayed (f8167d)

Internal Improvements:

1.3.1

Bug Fixes:

  • Fix issue where music-metadata-browser was not imported correctly, and id3 tags could not be read. (324fc2)

1.3.0

This release is far overdue. In the last six months we've made a huge number of improvements to Webamp.

We've fixed multiple longstanding bugs and continued to inch closer to pixel-perfect parity with Winamp. We've added several methods which make it easier to use Webamp in your project. In addition, we've continued to invest in the code by refactoring code to make it more maintainable, and converting the entire project from vanilla JavaScript to TypeScript which should help reduce the number of "dumb" bugs.

See a full list below:

Features:

  • Added methods to the webamp instance to control playback. See the Usage Docs for more information:
    • webamp.play()
    • webamp.pause()
    • webamp.previousTrack()
    • webamp.nextTrack()
    • webamp.seekForward(seconds)
    • webamp.seekBackward(seconds)
  • Our ID3 parsing library jsmediatags has been replaced by music-metadata-browser. This means we now support a broader range of media types, and also that the bitrate and sample rate displayed are now functional
  • The default skin is now included in the Skins section of the options menu by default
  • Implemented the "Options" sub context menu. Click the "O" in the "clutter bar" or select "Options" from the main context menu to see it
  • The equalizer graph is nolonger antialiased. It is now pixelated like real Winamp
  • Added a .reopen() method to reopen Webamp after you've closed it (47ba520)
  • Stip diacritic marks from song description so it displays better in the marquee (2b2598)

Bug Fixes:

  • Fixed a longstanding bug where mono audio files would only play in the right channel (4fd802)
  • Fixed a bug (#687) where webamp.appendTracks() would cause currently playing media to pause.
  • Avoid sticking a file <input> into the global DOM (343686)
  • Fix a bug where tracks dragged into the playlist were added at the wrong location (b074e0)
  • Fix a bug where skin cursors were not being shown for the equalizer sliders (65bb59d)
  • The Marquee text is nolonger blury when in "Double Size" mode (4b5320)
  • Scrolling in the Equalizer window nolonger changes the volume (48a937)
  • Clicking anywhere in a equalizer slider now makes the button depress (20e681
  • Parsing of the viscolor.txt file in skins is now more permissive, allowing us to support more skins (0d29ff)
  • The hotkeys to seek forward/backwards 10 tracks now works properly (7d9ef4)
  • Fix a bug where the preamp level was not applied until you changed it (f03c88)
  • Fix a bug where .eqf values were encoded incorrectly (c634cd)
  • Preamp and EQ now boost/attenuate the same way original winamp 2 did (#748)

Internal Improvements:

1.2.0

Features

  • Users can register an onWillClose callback, which is passed a cancel function. The cancel function can be called to prevent Webamp from closing. #655

Internal changes

1.1.2

Changes

Webamp is no-longer rendered into the DOM node you pass into webamp.renderWhenReady(). Instead, Webamp is rendered as a direct child of the <body> tag. The passed DOM node is still used for positioning. Webamp will attempt to center itself within that DOM node when it renders.

Features

  • Allow consumers to specify a z-index when constructing Webamp.

Fixes

  • Fixes positioning of context menus in context menu targets when they are spawned while scrolled.
  • Improve performance of CharacterString, which gets rendered on every marquee step.

1.1.1

Fixes

  • Fixes the marquee text when the host page globally sets box-sizing.
  • Fixes the initial layout when the container is not at the top of the page.
  • Fixes the positioning of context menus created when scrolled down the page.

1.1.0

Breaking

  • Webamp will attempt to center itself within the node it is rendered into, rather than within the entire page.
  • Webamp now includes the default skin directly in the JS bundle, so you don't need host it separately, or pass a URL as part of the initialization.

Features

  • Equalizer sliders now "stick" slightly at zero.
  • Context menus on all windows.
  • Toggle window visibility via context menus.
  • Users can now hard code the duration of initial tracks. This saves Webamp from having to make an HTTP request to check the duration.

Fixed

  • Marquee now displays one additional character: https://github.com/captbaritone/webamp/issues/543
  • Track numbers in playlist are now padded to the length of the longest track number.
  • Fix close buttons in Playlist and Equalizer in shade mode.
  • Skins that omit assets will now fallback to using the default version of that asset.
  • Fix seeking forward via hotkeys.

1.0.0

Important: The NPM module as moved from winamp2-js to webamp. You will need to update your package.json to point to the new module.

Breaking

  • Project renamed from "Winamp2-js" to "Webamp".
  • UMD module exports as window.Webamp instead of window.winamp2js. When used via <script> tag.
  • Deprecated: The misspelled Webmap construction option avaliableSkins has been deprecated in favor of availableSkins. avaliableSkins will continue to work, but will log a deprecation warning. #533 by @remigallego

Added

  • Instance method to be notified when Webamp is closed webamp.onClose(callback).
  • Instance method to be notified when Webamp is minimized webamp.onMinimize(callback).
  • Support for skins that use .png sprite sheets instead of .bmp. This saves 15kb for the default skin on the demo page. (b88e87)
  • We now attempt to detect mono audio files. Previously mono files would report as stereo and play only in the left channel.

Fixed

  • Shrink visualizer by one pixel to match Winamp. #536 by @The1Freeman
  • Remove Google Analytics tracking module from NPM module. (aeb9522)

0.0.6

  • Added: winamp.appendTracks().
  • Added: winamp.setTracksToPlay().
  • Changed: We no-longer try to center on window resize.
  • Meta: Added real documentation!
  • Meta: Remove lots of garbage from the NPM build.

Prehistory

In all older versions, the API was not stable enough to merit a changelog.