Mirrors/webamp
1
0
Fork 0
mirror of https://github.com/captbaritone/webamp.git synced 2026-01-23 02:15:01 +00:00
Code Issues Projects Releases Wiki Activity

Start adopting Yarn workspaces (#985)

Browse source 
* Start adopting Yarn workspaces

My plan is to move the existing package into a workspace and then split
out the things that really ought to be their own packages. For example,
the demo site and the experiments really ought to be separate.

Fix lint command

* Use workspaces in CI

* Fix deploy for monorepo
This commit is contained in:
Jordan Eldredge 2020-05-17 22:12:17 -07:00 • committed by GitHub
parent 50b25433fc
commit 975d712662
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
634 changed files with 3747 additions and 4198 deletions
Download patch file Download diff file Expand all files Collapse all files

111
docs/architecture.md
View file

@ -1,111 +0,0 @@
# Architecture
## Library/Application
This repository contains both an NPM module, and a demo page, found at <https://webamp.org>. The NPM module's goal is to provide a widget which can be embedded in any website, where as the demo page depends upon the library, and provides the canonical usage. You can find more information about the library's API in the [usage](./usage.md) document.
- The entry point for the demo page is [demo/js/index.js](../demo/js/index.js)
- The entry point for the NPM modules is [webamp.js](../js/webamp.js)
## Redux
Within the core library, state is managed by [Redux]. In fact, Redux's own docs mention Webamp in the [Apps and Examples](https://redux.js.org/introduction/learning-resources#apps-and-examples) section of their docs!
Our reducers, and the states they control, can be found in the [reducers](../js/reducers/) directory.
Async actions are handled using the [redux-thunk]. You can find all of the actionCreators in the [actionCreators](../js/actionCreators/index.ts) file. This is the most complex portion of the app, as it contains all the coordination of our many async actions.
Any non-trivial value derived from state is computed inside a [selector](../js/selectors.ts). Care has been taken to ensure that the structure of the state allows for most common selectors to be a constant time operation. For selectors that are `O(n)`, we use [reselect] to ensure the calculation is only done when dependent values change.
Coordination between the playing media (which is inherently stateful, and changes over time) and Redux is handed in the [mediaMiddleware](../js/mediaMiddleware.ts). This basically listens for events, and triggers the correct methods on our `Media` instance. It also listens events emitted by the media instance, and dispatches the corresponding actions.
## React
We use [react-redux] to bind Redux state into our [React components](../js/components/). Any component which is not reusable, and even some that are, are connected using [connect]. This works well for us, since most components are "one off", and connecting most components allows for state changes to result in a mininmal set of react components needing to re-render. This does, however, require that our selectors be performant.
In some places we use [rc-slider](https://github.com/react-component/slider) instead of `<input type='range'>` since it gives us more precise control over styling. This is particualarly true for the vertial sliders in the equalizer window. As far as I can tell, there is no way to style the handle of a vertical `<input type='range'>` in a way that gives pixel-level accuracy.
## Media
Media (audio files) is managed by our [Media](../js/media/index.ts) class. It encapsulates the Web Audio API complexity. Audio manipulation (volume, balance, EQ) is handled in the main `Media` class, but the audio source is managed in [elementSource.ts](../js/media/elementSource.ts). This class tries to encapsulate some of the complexity required to get the playing of audio files working across all browsers seamlessly. We handle playing audio from a URL source (subject to CORs) and from a local file. Both of these are normalized to a URL before they are passed into our audio aparatus. For local files, we convert the `ArrayBuffer` we get, into a Blob url using `URL.createObjectURL()`. This transformation is handlded inside our Action Creators (see the Redux section above).
The `Winamp` class instantiates a single `Media` instance and passes it's [AnalyserNode](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode) down through the tree of React components to the visualizer.
## Skins
Winamp skins (`.wsz`) are, under the hood, just `.zip` files which contain `.bmp` sprite sheets, and some config files. We use [JSZip] to unpack the zip archive, and then some clever canvas slicing to extract the individual sprites out of each `.bmp`. We get these sprite images as [data URIs] which are dispatched to Redux. We then have a [Skin](../js/components/Skin.tsx) component which renders a `<style>` tag into the `<head>` using [React Portals](https://reactjs.org/docs/portals.html). You can read more about this in a [blog post](https://jordaneldredge.com/blog/how-winamp2-js-loads-native-skins-in-your-browser/) I wrote.
In addition to the sprite sheets there are some config files in various formats, mostly `.ini` (although with different names). We have a very simple `.ini` parser, for these files. Finally, there is a `region.txt` which defines some vectors which define the transparent areas of a skin. We have a custom parser for this file format, and then dispatch the data to Redux.
From there, our `Skin` component has a `ClipPaths` sub component which ouputs a series of `<svg>`s representing the clip path for each window into the DOM. Finally, CSS `clip-path` rules representing each window are dynamically generated and added to the injected style sheet.
The parsing of skin files is handed in [skinParser.js](../js/skinParser.js). Rendering the `<svg>` and `<style>` tags is done in [Skin.js](../js/components/Skin.tsx). The definitions for all the individual sprites live in [skinSpirtes.js](../js/skinSprites.ts), and the mapping of skin spirtes to CSS rules lives in [skinSelectors.js](../js/skinSelectors.ts).
## CSS
CSS style sheets are imported by the components which use them. Each rule is individually prefixed with the id `#webamp` to prevent our style rules from "leaking" out onto other potential elements. For example, [98.js.org], includes Webamp on a page along with many other elements, and we want to be sure our rules for `.selected` elements do not apply to any elements outside of `#webamp`.
The nature of Winamp skins is such that most elements are absolutely positioned, and have an explicit size. There are a few down sides to our current approach:
1. Much of the size data for the individual sprites is duplicated in the items CSS rules and in [skinSprites.js](../js/skinSprites.ts).
2. Style data is lives far away from the individual component, and it can be hard to know where to look for the CSS that corresponds to an individual component.
All windows are rendred with `image-rendering: pixelated;` (or equivilant) so that high density displays don't blur the pixel art UI. This is especially important for "Double" mode, where the main and equalizer windows are twice as large. This doubleing is achived with the CSS: `transform: scale(2)`.
## Visualizer
The visualizer in the main window is a React component [Visualizer.tsx](../js/components/Visualizer.tsx) that gets passed skin data from the Redux store, an [analyser node](https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode) and some various user settings (which visualizer should be shown? are we playing?). All computation is done such that it works both in the "regular" mode, but also in shade mode. In shade mode the dimension values are just different.
To improve performance, two off-screen canvases are pre-rendered whenever the skin changes. These are then used as components of the per-frame rendering:
- The textured background.
- A single vertical bar for the bar graph analyser.
The actual canvas is rendered at twice the visible size so that "high density" or "retina" displays will not look blury.
## Equalizer
The audio portion of the equalizer is handed in the Media class (see above) but the visual representation of the current equalizer settings is created using [spline.js] which calculates the curved line for us.
The coloring of the curved line is achived by extracting the single-pixel-wide, many-pixel-tall sprite from the skin file, passing it through the Redux state to the graph component, and then drawing the splined line with [CanvasRenderingContext2D.createPattern()
](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/createPattern).
You can see the implementation of the equalizer graph in [EqGraph.tsx](../js/components/EqualizerWindow/EqGraph.tsx).
The equalizer window can also load/geneate `.eqf` files. The loading and parsing of these has been extracted into its own NPM module: [winamp-eqf](https://www.npmjs.com/package/winamp-eqf).
## Playlist
**TODO**
- Windowing
- Resizing
- Menus
## Window management
Window position is managed in the [WindowManager.tsx](../js/components/WindowManager.tsx) React component. It handles:
- Dragging windows around (windows can add a `.draggable` class to any node to make it a drag handle)
- Snapping windows to eachother
- Snapping windows to the browser edges
- Creating the initial layout of the windows
Moving windows when their neighbors are resized via "double" or "shade" mode toggles is handled by the `withWindowGraphIntegrity()` higher order action creator in [actionCreators](../js/actionCreators/index.ts). It works by:
1. Computing a graph where each window is a node, and the edges are where those windows are "touching".
2. Dispatching the passed in action.
3. Looking at the new sizes, and dispatching another event to move the windows to new locations where the original edeges are all still touching.
## Dropping files
Webamp allows you to drag files (media files, skins and `.eqf` equalizer presets) onto various windows to load them. This behavior is manged by the [`<DropTarget>`](../js/components/DropTarget.tsx) component. The component expects to be passed a `handleDrop` handler which will be called with the drop event, and also the `{x, y}` coordinates of the drop within the component. This is needed to allow us to insert dropped tracks at the correct place in the playlist.
[redux]: https://redux.js.org/
[redux-thunk]: https://github.com/gaearon/redux-thunk
[reselect]: https://github.com/reactjs/reselect
[connect]: https://react-redux.js.org/api/connect
[jszip]: https://stuk.github.io/jszip/
[data uris]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
[98.js.org]: https://98.js.org
[spline.js]: ../js/components/EqualizerWindow/spline.js

9
docs/music-credits.md
View file

@ -1,9 +0,0 @@
# Credits
## Music
Music courtesy of [blocSonic](https://blocsonic.com) and all included netBloc artists. [Download your free copy of "netBloc Volume 24 (tiuqottigeloot)"](https://blocsonic.com/releases/bscomp0024).
## Milkdrop Visualization
The Milkdrop visualization window is provided by the [Butterchurn](https://butterchurnviz.com/) project which was built and integrated, by [Jordan Berg](https://twitter.com/jnberg16).

306
docs/press.md
View file

@ -1,306 +0,0 @@
## Articles (notable)
- [Gizmodo](https://gizmodo.com/winamp-2-has-been-immortalized-in-html5-for-your-pleasu-1655373653)
- [Vice Motherboard](https://motherboard.vice.com/en_us/article/qvebbv/winamp-2-mp3-music-player-emulator)
- [Tech Crunch](https://techcrunch.com/2018/02/09/whip-the-llamas-ass-with-this-javascript-winamp-emulator/)
- [Mashable](https://mashable.com/2018/02/09/winamp-web-version-llama/)
## Podcast Interviews
- [Zeal Interesitngs](http://podcast.codingzeal.com/114820/657488-winamp-js)
- [Changelog](https://changelog.com/podcast/291)
- [JavaScript Jabber](https://devchat.tv/js-jabber/jsj-319-winamp2-js-with-jordan-eldredge/)
- [React Roundup](https://devchat.tv/react-round-up/rru-024-webamp-with-jordan-eldredge/)
## Newsletters
- [JavaScript Weekly](http://javascriptweekly.com/issues/353) (issue 353)
- [JavaScript Weekly](http://javascriptweekly.com/issues/372) (issue 372)
- [W3 "weekly digest of W3C news and trends"](https://www.w3.org/blog/2014/11/this-week-html5-is-a-recommendation-w3c20-winamp-in-html5js-etc/)
- [Front End Focus](https://frontendfoc.us/issues/309)
- [Web Audio Weekly](http://www.webaudioweekly.com/86)
## News Aggregators
- [/r/InternetIsBeautiful](https://www.reddit.com/r/InternetIsBeautiful/comments/2lh3ob/winamp_2_preserved_in_html5/)
- [Hacker News](https://news.ycombinator.com/item?id=17583997) (Jul. 2018)
- [Hacker News](https://news.ycombinator.com/item?id=16333550) (Feb. 2018)
- [Hacker News](https://news.ycombinator.com/item?id=15314629) (Sept. 2017)
- [Hacker News](https://news.ycombinator.com/item?id=8565665) (Nov. 2014)
- [Waxy.org](https://waxy.org/2018/02/winamp2-js-now-supports-all-three-windows/)
- [The Useless Web Index](https://www.theuselesswebindex.com/most-useless-websites/2018/17/)
- [Product Hunt](https://www.producthunt.com/posts/winamp2-js) (2014)
- [Product Hunt](https://www.producthunt.com/posts/webamp) (2018)
## Documentation
- [Redux Documentation](https://redux.js.org/introduction/learning-resources#apps-and-examples)
## Podcast Mentions
- [React Round Up](https://devchat.tv/react-round-up/rru-003-advanced-component-patterns-and-downshift-with-kent-c-dodds) (0:59:00)
- [Grumpy Old Geeks](http://gog.show/ep-248-side-hustle/) (1:37:30)
- [User Error](https://www.youtube.com/watch?v=qlm_G0xgK8Q&feature=youtu.be&t=309)
- [Important if True](https://youtu.be/6B6E2Kv-w04?t=3295)
- [Binärgewitter](http://blog.binaergewitter.de/2018/02/16/binaergewitter-talk-number-192-bitcoinheizung#t=1:52:13.216) (German)
- [The Changelog - State of the "log" (2018)](https://changelog.com/podcast/328#t=00:07:200.07) (00:07:40)
- [Freak Show](https://freakshow.fm/fs214-hoert-euch-doch-mal-zu?t=1:59:05,2:10:51) (German)
- [Apparatus Pogovori](https://apparatus.si/095apg/) (Slovenian)
## Forum Posts
- [Yaplakal.com](http://www.yaplakal.com/forum1/topic1737838.html)
- [Straight Dope](https://boards.straightdope.com/sdmb/showthread.php?t=836828)
## Twitter Endorsements
- [Scott Hanselman](https://twitter.com/shanselman/status/966129035649564677)
- [Jake Rodkin](https://twitter.com/ja2ke/status/961279058507063296)
- [Changelog](https://twitter.com/changelog/status/911957655392006145)
## Articles (continued)
### English
- http://entertainment.ie/trending/news/Remember-Winamp-Now-theres-a-web-browser-version-of-it/402141.htm
- http://newsvire.com/get-some-media-player-nostalgia-with-this-web-version-of-winamp/
- http://osxdaily.com/2018/02/10/run-winamp-web-browser/
- https://www.ghacks.net/2018/02/08/winamp2-js-is-a-web-based-version-of-audio-player-winamp/
- https://uk.news.yahoo.com/media-player-nostalgia-version-winamp-070022687.html
- https://thenextweb.com/shareables/2018/02/09/bring-nostalgia-browser-winamp-emulator/
- https://www.follownews.com/winamp2js-is-a-webbased-version-of-audio-player-winamp-43icg
- https://www.gizmodo.com.au/2018/02/someone-remade-winamp-so-it-runs-in-your-browser/
- https://changelog.com/news/winamp-29-in-htmljs--PJr
- https://www.howtogeek.com/343813/re-live-90s-computing-in-your-browser-right-now/amp/
- https://techcaption.com/run-winamp-web-browser/
- https://www.trishtech.com/2018/02/javascript-version-of-winamp-runs-in-any-web-browser/
- https://ourcodeworld.com/articles/read/685/winamp2-js-a-reimplementation-of-winamp-2-9-in-html5-and-javascript
- http://whazupnaija.com/whip-the-llamas-ass-with-this-javascript-winamp-emulator/
- http://cashrange.com/run-winamp-in-web-browser-and-play-mp3s/
- https://coolmaterial.com/media/winamp-emulator/
- http://www.redferret.net/?p=57922
- https://hackernoon.com/50-popular-javascript-open-source-projects-on-github-in-2018-469c11b48b8d (mention)
- https://mashable.com/2018/08/01/old-ways-to-listen-to-music-ranked/ (mention)
- https://www.thewindowsclub.com/webamp-online-music-player-winamp
- https://www.techspot.com/news/58728-winamp-recreated-html5.html
### Russian
- http://altervision.org/2018/02/winamp-zapustili-v-vashem-brauzere/
- http://droider.ru/post/emulyator-dlya-nostalgii-po-winamp-09-02-2018/
- http://fornote.net/2018/02/winamp2-js-legendarny-j-winamp-dostupny-j-pryamo-v-brauzere/
- http://internetua.com/programmist-voskresil-legendarni-pleer-winamp
- http://oane.ws/2018/02/10/legendarnyy-pleer-winamp-vozrodili-v-brauzernoy-versii.html
- http://www.belursus.info/soft/i.php?c=winamp2js
- https://esquire.ru/articles/42012-winamp/
- https://lifehacker.ru/2018/02/09/browser-winamp-emulator/
- https://itc.ua/blogs/kaliforniyskiy-razrabotchik-vozrodil-legendarnyiy-muzyikalnyiy-pleer-winamp-nu-pochti/
- https://meduza.io/shapito/2018/02/09/kaliforniyskiy-razrabotchik-vossozdal-winamp-v-brauzere
- https://nplus1.ru/news/2018/02/09/winamp
- https://rg.ru/2018/02/09/programmist-voskresil-legendarnyj-pleer-winamp.html
- https://tjournal.ru/66060-brauzernyy-emulyator-kultovogo-muzykalnogo-pleera-winamp
- https://trashbox.ru/topics/115521/winamp-zhivee-vseh-zhivyh
- https://tech.onliner.by/2018/02/09/winamp-5
- http://fonotekaelektrika.com/2018/02/winamp-%D0%B2-%D0%B1%D1%80%D0%B0%D1%83%D0%B7%D1%8A%D1%80/
- https://toocha.me/winamp-web/
- https://manjaro.ru/soft/poyavilsya-reliz-winamp2-js-desktop.html (forum post)
- https://mixed.news/news/1123379
- https://banana.by/index.php?newsid=269984
- https://zen.yandex.ru/media/apple-iphone.ru/legendarnyi-winamp-teper-mojno-polnocenno-ispolzovat-iz-liubogo-brauzera-5a8280f4a936f46fea003489
### Spanish
- http://datainfox.com/2018/02/lanzan-version-web-winamp/
- http://html5facil.com/noticias/winamp-web/
- http://omicrono.elespanol.com/2014/11/winamp-2-en-html5-es-nostalgia-pura/
- http://www.microsiervos.com/archivo/musica/winamp-html5-javascript-codigo-abierto.html
- http://www.tecnofanatico.com/winamp-el-popular-reproductor-de-audio-llega-en-version-web/
- https://emisorasunidas.com/winamp-2-vuelve-a-la-vida-con-una-version-para-la-web/
- https://es.gizmodo.com/ahora-puedes-viajar-al-pasado-y-volver-a-usar-el-mitico-1822850658
- https://hipertextual.com/archivo/2014/12/port-winamp-html5-javascript/
- https://ohmygeek.net/2018/02/09/winamp-2-js/
- https://www.softzone.es/2018/02/08/winamp2-js-nueva-version-famoso-reproductor-formato-web/
- https://www.tekcrispy.com/2018/02/08/winamp2-js-la-version-web/
- https://www.softandapps.info/2014/11/07/resucita-winamp-en-version-html5-y-javascript/
- https://www.neoteo.com/winamp2-js-version-web-del-legendario-winamp/
- https://www.taringa.net/posts/musica/20127134/Ahora-podes-revivir-el-Winamp-desde-tu-navegador.html
- https://www.xataka.com/aplicaciones/winamp-se-hace-inmortal-gracias-a-la-magia-del-html5
- https://www.sweclockers.com/nyhet/25215-kor-klassikern-winamp-i-webblasaren
- https://www.rocambola.com/winamp2-js-la-nueva-version-del-famoso-reproductor-en-formato-web/
- https://www.genbeta.com/web/viaja-a-1998-con-esta-version-web-de-winamp
- https://codigoespagueti.com/noticias/winamp-navegador/
- https://wwwhatsnew.com/2018/02/09/lanzan-una-version-web-del-mitico-winamp/
- https://abertoatedemadrugada.com/2018/02/winamp-completamente-funcional-em.html
- https://www.ardilu.com/software/winamp2-js-reproductor-winamp-html-5
- http://computerhoy.com/noticias/internet/recuerdas-winamp-puedes-volver-utilizarlo-esta-web-75669
### Chinese
- http://baijiahao.baidu.com/s?id=1592074295875163282
- http://blog.csdn.net/souhugirl/article/details/43907469
- http://m.sohu.com/a/221750379_549015
- http://news.cnblogs.com/n/589654/
- http://top.jobbole.com/16031/
- http://www.apprcn.com/winamp2-js.html
- http://www.cnbeta.com/articles/soft/697983.htm
- http://www.linuxidc.com/Linux/2018-02/150869.htm
- https://news.aotu.io/a/5a7ebbfd0b61600038184eec
- https://unwire.hk/2018/02/11/winampemu/mobile-music/
- https://www.appinn.com/winamp2-js/
- https://www.waerfa.com/winamp2-js
- https://www.techapple.com/archives/19899
- https://ezone.ulifestyle.com.hk/article/2010877
- https://www.minwt.com/life/19526.html
- http://www.xia1ge.com/winamp2-js.html
- https://www.techbang.com/posts/56800-do-you-miss-the-days-when-you-used-winamp-to-listen-to-music-now-you-can-go-back-to-this-page-and-relive-that-time
### German
- http://de.engadget.com/2018/02/09/retro-winamp-emulator-fur-deinen-browser/
- http://www.chip.de/news/Winamp-ist-zurueck-Kult-Player-ueber-Browser-nutzen_124413881.html
- http://www.intro.de/life/mit-winamp-zuruck-in-die-vergangenheit-nostalgische-browser-version-des-media-players
- https://futurezone.at/digital-life/entwickler-baut-winamp-fuer-den-browser-nach/400003172
- https://t3n.de/news/winamp-javascript-open-source-863217/
- https://www.smartdroid.de/winamp2-js-laesst-den-klassiker-im-browser-wieder-aufleben/
- https://www.morgenpost.de/web-wissen/web-technik/article212250123/Surftipp-Kultiger-MP3-Player-im-Browser.html
- https://eay.cc/2017/winamp2-js/
- https://www.maennersache.de/winamp-simulator-neues-browser-plugin-befoerdert-dich-zurueck-ins-jahr-1999-aol-webamp-jordan-eldredge-9063.html#
- https://www.abendblatt.de/ratgeber/multimedia/article212250123/Surftipp-Kultiger-MP3-Player-im-Browser.html
- https://www.techbook.de/entertainment/sound/surftipp-kultiger-mp3-player-im-browser
- https://seeseekey.net/archive/124127/
### Polish
- https://www.antyradio.pl/Technologia/Internet/Winamp-powrocil-jako-strona-internetowa-17497
- http://innpoland.pl/137663,kultowy-winamp-powraca-w-nowej-formie-uderza-tam-gdzie-jest-juz-spotify
- http://www.instalki.pl/aktualnosci/software/30055-winamp-przegladarka.html
- https://mobirank.pl/2018/02/10/emulator-winamp-przeniesie-cie-do-1999-roku/
- https://www.dobreprogramy.pl/Kultowy-odtwarzacz-muzyki-Winamp-powrocil-w-przegladarce-internetowej,News,86017.html
- https://dailyweb.pl/pamietacie-jeszcze-winampa-poznajcie-jego-webowa-reinkarnacje/
- https://www.wykop.pl/link/4432835/winamp-w-przehttps://www.producthunt.com/posts/webampgladarce-www/
- http://android.com.pl/news/98936-winamp-online/
### French
- http://www.phonandroid.com/winamps-lecteur-multimedia-retour.html
- http://www.lemonde.fr/pixels/breve/2014/11/07/winamp-en-html_4520190_4408996.html
- https://korben.info/winamp-en-html-javascript.html
- https://www.geekzone.fr/2018/02/09/winamp2-sinvite-navigateur/
- https://www.lesnumeriques.com/vie-du-net/winamp-est-retour-enfin-presque-n71341.html
- https://www.macg.co/logiciels/2018/02/revivez-les-glorieuses-annees-winamp-avec-votre-navigateur-101345
- https://www.byothe.fr/2018/05/avis-aux-nostalgiques-un-emulateur-de-winamp-dans-votre-navigateur-web/
- https://fr.softonic.com/articles/winamp-revient-sous-la-forme-de-lecteur-web
### Italian
- https://tech.everyeye.it/notizie/il-ritorno-winamp-storico-player-riappare-in-una-versione-web-320373.html
- https://www.hwupgrade.it/news/web/winamp-arriva-su-qualsiasi-browser-web-nostalgici-gioiscono_74100.html
- https://www.wired.it/internet/web/2018/02/09/winamp-rinasce-sul-web/
- https://www.macitynet.it/winamp-nostalgici-un-clone-utilizzabile-via-web/
- https://www.windowsblogitalia.com/2018/02/ascoltare-la-musica-edge-firefox-chrome-winamp2-js/
- https://www.amicopc.com/software-5/winamp-debutta-sul-web-versione-browser/
### Thai
- http://www.flashfly.net/wp/208175
- https://www.aripfan.com/bring-winamp-emulator-in-web-browser/
- https://www.beartai.com/news/itnews/221530
- https://men.kapook.com/view188468.html
### Hungarian
- http://hvg.hu/tudomany/20180212_winamp_zenelejatszo_letoltes_bongeszoben
- http://www.karpatinfo.net/cikk/tudomany/2567147-feltamadt-winamp-90-es-evek-kedvenc-zenelejatszoja-hasznalhatja
- https://www.gamestar.hu/hir/winamp-html5-verzio-243839.html
- https://pcworld.hu/pcwlite/feltamad-a-winamp-raadasul-bongeszoben-243841.html
- https://24.hu/tech/2018/02/11/ezernyi-emlek-onti-fogja-elonteni-a-szivet-ettol-a-hirtol/
- https://888.hu/article-visszatert-minden-idok-legjobb-zenelejatszoja-a-winamp
### Bosnian
- https://www.b92.net/tehnopolis/vesti.php?yyyy=2018&mm=02&nav_id=1357852
- https://www.benchmark.rs/vesti/novi_winamp_emulator_budi_nostalgiju_na_stara_vremena-74941
### Turkish
- http://www.bursateknikpc.com/winamp-2nin-html5-de-yazilmis-versiyonu-cikti/
- https://www.log.com.tr/winamp-efsanesini-yeniden-kullanima-sunan-site/
### Japanese
- http://jp.techcrunch.com/2018/02/10/2018-02-09-whip-the-llamas-ass-with-this-javascript-winamp-emulator/
- https://gigazine.net/news/20180213-winamp2-js/
- https://www.gizmodo.jp/2014/11/90winamp_2html5.html
- https://www.softantenna.com/wp/review/winamp2-js/
- http://mantiddesign.com/archives/15468
- https://jp.sputniknews.com/science/201802104563738/
### Portuguese
- http://abertoatedemadrugada.com/2018/02/winamp-completamente-funcional-em.html
- https://canaltech.com.br/musica/desenvolvedor-ressuscita-winamp-em-emulador-com-javascript-108112/
- https://itovnp.blogspot.com/2018/07/winamp-atraves-de-um-simples-browser.html
- https://pplware.sapo.pt/software/chegou-winamp-funciona-um-browser/
- https://www.techtudo.com.br/noticias/2018/03/oito-curiosidades-sobre-o-winamp-player-que-era-sucesso-nos-anos-2000.ghtml (mention)
- https://tecnoblog.net/234125/winamp-versao-web-navegador/
### Swedish
- http://gaffa.se/nyhet/125537/klassisk-musikspelare-nu-pa-webben/
- https://www.idg.se/2.1085/1.697529/mp3-winamp-webblasare
### Armenian
- http://www.armblog.net/2018/02/github-winamp.htm
### Dutch
- https://tweakers.net/geek/135087/ontwikkelaar-bouwt-winamp-29-in-javascript.html)
- https://p-magazine.be/nostalgisch-luisterplezier-slechts-muisklik-verwijderd/
### Romanian
- https://zonait.tv/va-era-dor-de-winamp/
- https://playtech.ro/2018/macos-windows-95-winamp-paint-software-vechi-browser/
### Czech
- https://www.zive.cz/clanky/zpatky-do-minulosti-winamp-muzete-pouzivat-primo-v-prohlizeci/sc-3-a-191743/default.aspx
- https://www.zive.cz/clanky/prehistoricky-winamp-se-konecne-docka-navratu-unikla-betaverze/sc-3-a-195099/default.aspx (mention)
### Croatian
- http://idesh.net/tech-i-web/internet/winamp-se-vratio-nostalgija-na-najjace/
### Vietnamese
- http://vnreview.vn/tin-tuc-xa-hoi-so/-/view_content/content/2421915/song-lai-thap-nien-90-voi-trai-nghiem-nhung-phan-mem-nay-ngay-tren-trinh-duyet
- http://genk.vn/trang-web-gia-lap-trinh-phat-nhac-winamp-nay-se-dua-ban-tro-lai-hoi-uc-nhung-cuoi-the-ky-20-20180212175238851.chn
### Indonsian
- https://www.trentech.id/masih-ingat-winamp-kamu-bisa-nostalgia-dengan-winamp-di-situs-ini/
### Persian
- http://www.1pezeshk.com/archives/2018/07/webamp.html
### Korean
- http://funtenna.funshop.co.kr/article/11801
### Dutch
- https://freshgadgets.nl/nostalgie-je-kunt-winamp-in-je-browser-gebruiken
## Internet Archive
On October 2nd, 2018 the Internet Archive announced Webamp integration. Here are some articles covering that annoucement.
- https://blog.archive.org/2018/10/02/dont-click-on-the-llama/
- https://www.ghacks.net/2018/10/04/internet-archive-releases-winamp-skins-collection/?utm_source=dlvr.it&utm_medium=twitter
- https://www.pcactual.com/noticias/actualidad/internet-archive-no-quiere-olvidarse-winamp_14008
- https://www.guaripetesolutions.us/internet-archive-releases-winamp-skins-collection/
- https://www.softzone.es/2018/10/04/internet-archive-coleccion-skins-winamp/
- https://tugatech.com.pt/t26972-internet-archive-disponibiliza-colecoes-de-skins-para-winamp
- https://www.bardtech.com/internet-archive-releases-winamp-skins-collection/

410
docs/usage.md
View file

@ -1,410 +0,0 @@
# Usage
Here's how to use Webamp in your own project. If you get stuck, or need help, please either file an issue, or reach out on [Discord](https://discord.gg/fBTDMqR).
## Examples
If you would like to look at some examples check out the [examples directory](../examples/) where you will find:
- [Minimal](../examples/minimal/) - An example that just uses a `<script>` tag that points to a CDN. No install required.
- [Webpack](../examples/webpack/) - An example that installs Webamp via NPM, and bundles it into an application using Webpack.
Each example has a README which explains it in more detail.
## Install
```
npm install --save webamp
```
Or, you can include it via a script tag:
```html
<!-- You can use this URL, or download it and check it into your own project -->
<script src="https://unpkg.com/webamp@1.4.0/built/webamp.bundle.min.js"></script>
```
## Create a container
Create a DOM element somewhere in your HTML document. This will be used by Webamp to find it's initial position.
```html
<div id="winamp-container"></div>
```
## Initialize the JavaScript
```JavaScript
import Webamp from 'webamp';
// Or, if you installed via a script tag, `Winamp` is available on the global `window`:
// const Winamp = window.Webamp;
// Check if Winamp is supported in this browser
if(!Webamp.browserIsSupported()) {
alert("Oh no! Webamp does not work!")
throw new Error("What's the point of anything?")
}
// All configuration options are optional.
const webamp = new Webamp({
// Optional.
initialTracks: [{
metaData: {
artist: "DJ Mike Llama",
title: "Llama Whippin' Intro",
},
// Can be downloaded from: https://github.com/captbaritone/webamp/raw/master/mp3/llama-2.91.mp3
url: "path/to/mp3/llama-2.91.mp3"
}],
// Optional. The default skin is included in the js bundle, and will be loaded by default.
initialSkin: {
// Can be downloaded from https://github.com/captbaritone/webamp/raw/master/skins/TopazAmp1-2.wsz
url: "path/to/skins/TopazAmp1-2.wsz"
},
});
// Render after the skin has loaded.
webamp.renderWhenReady(document.getElementById('winamp-container'));
```
## API
Many methods on the webamp instance deal with `track`s. Here is the shape of a `track`:
```JavaScript
const track = {
// Either `url` or `blob` must be specified
// Note: This URL must be served the with correct CORs headers.
url: 'https://example.com/song.mp3',
blob: dataBlob,
// Optional. Name to be used until ID3 tags can be resolved.
// If the track has a `url`, and this property is not given,
// the filename will be used instead.
defaultName: 'My Song',
// Optional. Data to be used _instead_ of trying to fetch ID3 tags.
metaData: {
artist: 'Jordan Eldredge',
title: "Jordan's Song"
},
// Optional. Duration (in seconds) to be used instead of
// fetching enough of the file to measure its length.
duration: 95
};
```
## Static Methods
The `Winamp` class has the following _static_ methods:
### `browserIsSupported()`
Returns a true if the current browser supports the features that Webamp depends upon. It is recommended to check this before you attempt to instantiate an instance of `Winamp`.
```JavaScript
if(Winamp.browserIsSupported()) {
new Winamp({/* ... */});
// ...
} else {
// Perhaps you could show some simpler player in this case.
}
```
## Construction
The `Winamp` class is constructed with an options object. All are optional.
```JavaScript
const options = {
// Optional. An object representing the initial skin to use.
// If omitted, the default skin, included in the bundle, will be used.
// Note: This URL must be served the with correct CORs headers.
initialSkin: {
url: './path/to/skin.wsz'
},
// Optional. An array of `track`s (see above) to prepopulate the playlist with.
initialTracks: [/* ... */],
// Optional. An array of objects representing skins.
// These will appear in the "Options" menu under "Skins".
// Note: These URLs must be served with the correct CORs headers.
availableSkins: [
{ url: "./green.wsz", name: "Green Dimension V2" },
{ url: "./osx.wsz", name: "Mac OSX v1.5 (Aqua)" }
],
// Optional. (Default: `false`) Should global hotkeys be enabled?
enableHotkeys: true,
// Optional. (Default: `0`) The zIndex that Webamp should use.
zIndex: 99999,
// Optional. An array of additional file pickers.
// These will appear in the "Options" menu under "Play".
// In the offical version. This option is used to provide a "Dropbox" file picker.
filePickers: [{
// The name that will appear in the context menu.
contextMenuName: "My File Picker...",
// A function which returns a Promise that resolves to
// an array of `track`s (see above)
filePicker: () => Promise.resolve([{
url: './rick_roll.mp3'
}]),
// A boolean indicating if this options should be made
// available when the user is offline.
requiresNetwork: true
}],
// Optional. Provide a custom way to derive `Track` objects from a drop event.
// Useful if your website has some DOM representation of a track that you can map to a URL/blob.
handleTrackDropEvent: async (e) => {
// Return an array of `Track` objects, see documentation below, or `null` to get the default drop behavior.
// You may optionally wrap the return value in a promise.
}
};
const webamp = new Webamp(options);
```
## Instance Methods
The `Webamp` class has the following _instance_ methods:
### `appendTracks(tracks: Track[]): void`
Add an array of `track`s (see above) to the end of the playlist.
```JavaScript
webamp.appendTracks([
{url: 'https://example.com/track1.mp3'},
{url: 'https://example.com/track2.mp3'},
{url: 'https://example.com/track3.mp3'}
]);
```
### `setTracksToPlay(tracks: Track[]): void`
Replace the playlist with an array of `track`s (see above) and begin playing the first track.
```JavaScript
webamp.setTracksToPlay([
{url: 'https://example.com/track1.mp3'},
{url: 'https://example.com/track2.mp3'},
{url: 'https://example.com/track3.mp3'}
]);
```
### `previousTrack(): void`
Play the previous track.
**Since** 1.3.0
```JavaScript
webamp.previousTrack();
```
### `nextTrack(): void`
Play the next track.
**Since** 1.3.0
```JavaScript
webamp.nextTrack();
```
### `seekForward(seconds): void`
Seek forward n seconds in the current track.
**Since** 1.3.0
```JavaScript
webamp.seekForward(10);
```
### `seekBackward(seconds): void`
Seek backward n seconds in the current track.
**Since** 1.3.0
```JavaScript
webamp.seekBackward(10);
```
### `seekToTime(seconds)`
Seek to a given time within the current track.
**Since** 1.4.0
```JavaScript
webamp.seekToTime(15.5);
```
### `getMediaStatus()`
Get the current "playing" status. The return value is one of: `"PLAYING"`, `"STOPPED"`, or `"PAUSED"`.
**Since** 1.4.0
```JavaScript
const isPlaying = webamp.getMediaStatus() === "PLAYING";
```
### `pause(): void`
Pause the current track.
**Since** 1.3.0
```JavaScript
webamp.pause();
```
### `play(): void`
Play the current track.
**Since** 1.3.0
```JavaScript
webamp.play();
```
### `stop(): void`
Stop the currently playing audio. Equivilant to pressing the "stop" button.
**Since** 1.4.0
```JavaScript
webamp.stop();
```
### `renderWhenReady(domNode: HTMLElement): Promise<void>`
Webamp will wait until it has fetched the skin and fully parsed it, and then render itself into a new DOM node at the end of the `<body>` tag.
If a `domNode` is passed, Webamp will place itself in the center of that DOM node.
A promise is returned which will resolve after the render is complete.
```JavaScript
const container = document.getElementById('winamp-container');
webamp.renderWhenReady(container).then(() => {
console.log('rendered webamp!');
});
```
### `onTrackDidChange(cb: (trackInfo: LoadedURLTrack | null) => void): () => void`
A callback which will be called when a new track starts loading. This can happen on startup when the first track starts buffering, or when a subsequent track starts playing. The callback will be called with an object (`{url: 'https://example.com/track.mp3'}`) containing the URL of the track.
Returns an "unsubscribe" function.
**Note:** If the user drags in a track, the URL may be an [ObjectURL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL)
```JavaScript
const unsubscribe = webamp.onTrackDidChange((track => {
console.log("New track playing:", track.url);
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `onWillClose(cb: (cancel: () => void) => void): () => void`
A callback which will be called when Webamp is _about to_ close. Returns an "unsubscribe" function. The callback will be passed a `cancel` function which you can use to conditionally prevent Webamp from being closed.
```JavaScript
const unsubscribe = webamp.onWillClose((cancel) => {
if (!window.confirm("Are you sure you want to close Webamp?")) {
cancel();
}
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `onClose(cb: () => void): () => void`
A callback which will be called when Webamp is closed. Returns an "unsubscribe" function.
```JavaScript
const unsubscribe = webamp.onClose(() => {
console.log("Webamp closed");
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `reopen(): void`
After `.close()`ing this instance, you can reopen it by calling this method.
**Since** 1.3.0
```JavaScript
const icon = document.getElementById('webamp-icon');
webamp.onClose(() => {
icon.addEventListener('click', () => {
webamp.reopen();
});
})
```
### `onMinimize(cb: () => void): () => void`
A callback which will be called when Webamp is minimized. Returns an "unsubscribe" function.
```JavaScript
const unsubscribe = webamp.onMinimize(() => {
console.log("Webamp closed");
});
// If at some point in the future you want to stop listening to these events:
unsubscribe();
```
### `setSkinFromUrl(url: string): void`
Updates the skin used by the webamp instance. Note that this does not happen immediately. If you want to be notified when the skin load is complete, use `.skinIsLoaded()`, which returns a promise which you can await.
**Since** 1.4.1-beta01 (unreleased)
### `skinIsLoaded(): Promise<void>`
Returns a promise that resolves when the skin is done loading.
```JavaScript
const start = Date.now();
await webamp.skinIsLoaded();
console.log(`The skin loaded in ${Date.now() - start}`);
```
### `dispose(): void`
**Note:** _This method is not fully functional. It is currently impossible to clean up a Winamp instance. This method makes an effort, but it still leaks the whole instance. In the future the behavior of this method will improve, so you might as well call it._
When you are done with a Webamp instance, call this method and Webamp will attempt to clean itself up to avoid memory leaks.
```JavaScript
webamp.dispose();
```
## Notes
- Internet Explorer is not supported.
- Webamp injects CSS into the page. The CSS is namespaced (every CSS selector is prefixed with `#webamp`), so it should not interfere with anything on the host page.
- Webamp HTML contains somewhat generic IDs and class names. If you have CSS on your page that is not namespaced, it may accidentaly be applied to Webamp. If this happens please reach out. I may be able to resolve it.
- Skin and audio URLs are subject to [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS). Please ensure they are either served from the same domain, or that the other domain is served with the correct headers.
- Please reach out to me. I'd love to help you set it up, and understand how it's being used. I plan to expand this API as I learn how people want to use it.