mirror of
https://github.com/captbaritone/webamp.git
synced 2026-07-28 12:36:35 +00:00
Tight up README by moving sections into sub-readmes
This commit is contained in:
Jordan Eldredge
parent
e288916c5f
commit
6a5fd3f8b6
2 changed files with 62 additions and 120 deletions
140
README.md
140
README.md
|
|
@ -5,115 +5,42 @@
|
|||
|
||||
# Webamp
|
||||
|
||||
A reimplementation of Winamp 2.9 in HTML5 and JavaScript.
|
||||
A reimplementation of Winamp 2.9 in HTML5 and JavaScript with full skin support.
|
||||
As seen on [TechCrunch], [Motherboard], [Gizmodo], Hacker News ([1], [2], [3], [4]), and [elsewhere](./packages/webamp/docs/press.md).
|
||||
|
||||
**As seen on [TechCrunch], [Motherboard], [Gizmodo], Hacker News ([1], [2], [3], [4]), and [elsewhere](./packages/webamp/docs/press.md).**
|
||||
|
||||
## [Give it a try!](https://webamp.org)
|
||||
|
||||
[](https://webamp.org)
|
||||
|
||||
Works in modern versions of Edge, Firefox, Safari and Chrome. IE is [not
|
||||
supported](http://caniuse.com/#feat=audio-api).
|
||||
|
||||
## Features
|
||||
Check out this [Twitter thread](https://twitter.com/captbaritone/status/96127471401331916) for an illustrated list of features.
|
||||
|
||||
Check out this Twitter thread for an illustrated list of features: https://twitter.com/captbaritone/status/961274714013319168
|
||||
|
||||
## Use Webamp in your own project
|
||||
## Add Webamp to Your Site
|
||||
|
||||
Its possible to use Webamp as a media player on your own website. In fact, the [Internet Archive](https://archive.org/) offers it as an optional player for all of their archived audio tracks. [Read more](https://blog.archive.org/2018/10/02/dont-click-on-the-llama/).
|
||||
Here is the **most minimal** example of adding Webamp to a page:
|
||||
|
||||
For examples of how to add Webamp to your projects, check out out [`examples/` directory](./examples).
|
||||
```HTML
|
||||
<div id="app"></div>
|
||||
<script src="https://unpkg.com/webamp"></script>
|
||||
<script>new Webamp().renderWhenReady(app);</script>
|
||||
```
|
||||
|
||||
See the [usage documentation](./packages/webamp/docs/usage.md) for more detailed information.
|
||||
For more examples, including how to add audio files, check out [`examples/` directory](./examples) and the [API documentation](./packages/webamp/docs/usage.md).
|
||||
|
||||
## About This Repository
|
||||
|
||||
This repository contains a number of different things:
|
||||
Webamp uses a [monorepo](https://en.wikipedia.org/wiki/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:
|
||||
|
||||
1. `packages/webamp`: The code for the [Webamp NPM module](https://www.npmjs.com/package/webamp)
|
||||
2. `packages/webamp/demo`: The code for the demo site which lives at [webamp.org](https://webamp.org), see the next section for more details
|
||||
3. `examples`: A few small examples showing how to use the NPM module
|
||||
4. `packages/*`: A few small projects that are either related to Webamp, or may some day be a part of Webamp
|
||||
|
||||
## About the Demo Site
|
||||
|
||||
The demo site, [webamp.org](https://webamp.org), uses the same interface as the NPM module but adds the following functionality by utilizing Webamp's public API
|
||||
|
||||
- Error reporting using [Sentry](https://sentry.io)
|
||||
- Analytics using [Google Analytics](https://analytics.google.com/analytics/web/)
|
||||
- Updating document's title to reflect the currently playing track
|
||||
- [Media Session API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API) integration
|
||||
|
||||
Additionally, it makes use of some private Webamp APIs to add the following functionality:
|
||||
|
||||
- [Butterchun](https://github.com/jberg/butterchurn) integration to render [MilkDrop](https://en.wikipedia.org/wiki/MilkDrop) visualizations. We intend to make this part of the public API soon.
|
||||
- "Screenshot" mode `https://webamp.org/?screenshot=1` which can be used together with [Puppeteer](https://github.com/GoogleChrome/puppeteer) to automate the generation of Winamp skin screenshots
|
||||
-
|
||||
|
||||
## Development
|
||||
|
||||
I do most development by starting the demo site in dev mode and iterating that way. The following commands will install all dependencies, run an initial development build and then start a local server. Every time you save a file, it will rebuild the bundle and automatically refresh the page.
|
||||
|
||||
# Clone the repo
|
||||
cd webamp
|
||||
# __Note:__ Please use yarn over npm, since yarn will respect our `yarn.lock` file
|
||||
yarn install
|
||||
yarn start
|
||||
|
||||
`http://localhost:8080/` should automatically open in your browser.
|
||||
|
||||
# Run tests and lint checks
|
||||
yarn test
|
||||
|
||||
## Building the demo site (webamp.org)
|
||||
|
||||
To do an optimized build of the demo site, you can run:
|
||||
|
||||
yarn run build
|
||||
|
||||
If you wish to test this build locally, run:
|
||||
|
||||
yarn run serve
|
||||
|
||||
Then open the local ip/port that is output to the console in your browser.
|
||||
|
||||
## Building the NPM module
|
||||
|
||||
The NPM module is built separately from the demo site. To build it run:
|
||||
|
||||
yarn run build-library
|
||||
|
||||
This will write files to `./built`.
|
||||
|
||||
## Testing
|
||||
|
||||
yarn test
|
||||
|
||||
This will run the tests the linter and the type checker.
|
||||
|
||||
To update snapshots run
|
||||
|
||||
yarn test -u
|
||||
|
||||
## Deploying the Demo Site
|
||||
|
||||
[Netlify](https://www.netlify.com/) watches GitHub for new versions of master. When a new version is seen, it is automatically built using `npm run build` and pushed to the server. Additionally, Netlify will run a build on every pull request and include a link under the heading "Deploy preview ready!". This enables easy high level testing of pull requests.
|
||||
|
||||
In short, deploying should be as simple as pushing a commit to master.
|
||||
|
||||
Additionally, if you want to fork the project, deploying should be as simple as setting up a free Netlify account.
|
||||
|
||||
### Advanced Usage
|
||||
|
||||
There are some "feature flags" which you can manipulate by passing a specially crafted URL hash. Simply supply a JSON blob after the `#` of the URL to change these settings:
|
||||
|
||||
- `skinUrl` (string) Url of the default skin to use. Note, this file must be served with the correct Allows Origin header.
|
||||
- `audioUrl` (string) Url of the default audio file to use. Note, this file must be served with the correct Allows Origin header.
|
||||
- `initialState` (object) Override the [initial Redux state](packages/webamp/js/reducers/index.ts). Values from this object will be recursively merged into the actual default state.
|
||||
|
||||
**Note:** These are intended mostly as development tools and are subject to change at any time.
|
||||
* [`packages/webamp`](https://github.com/captbaritone/webamp/tree/master/packages/webamp): The [Webamp NPM module](https://www.npmjs.com/package/webamp)
|
||||
* [`packages/webamp/demo`](https://github.com/captbaritone/webamp/tree/master/packages/webamp/demo): The demo site which lives at [webamp.org](https://webamp.org), see the next section for more details
|
||||
* [`packages/ani-cursor`](https://github.com/captbaritone/webamp/tree/master/packages/ani-cursor): An NPM module for rendering animiated `.ani` cursors as CSS animations
|
||||
* [`packages/skin-database`](https://github.com/captbaritone/webamp/tree/master/packages/skin-database): The server component of https://skins.webamp.org which also runs our [Twitter bot](https://twitter.com/winampskins), and a Discord bot for our community chat
|
||||
* [`packages/winamp-eqf`](https://github.com/captbaritone/webamp/tree/master/packages/winamp-eqf): An NPM module for parsing and constructing Winamp equalizer preset files (`.eqf`)
|
||||
* [`packages/archive-org-webamp-integration-tests`](https://github.com/captbaritone/webamp/tree/master/packages/archive-org-webamp-integration-tests): An integration that confirms that archive.org's Webamp integration is working as expected
|
||||
* [`packages/webamp-modern`](https://github.com/captbaritone/webamp/tree/master/packages/webamp-modern): A prototype exploring rendering "modern" Winamp skins in the browser
|
||||
* [`examples`](https://github.com/captbaritone/webamp/tree/master/examples): A few examples showing how to use the NPM module
|
||||
|
||||
## Community
|
||||
|
||||
|
|
@ -127,7 +54,7 @@ There are a few related projects that have communites:
|
|||
|
||||
## In the Wild
|
||||
|
||||
A list of public websites that are using Webamp:
|
||||
An incomplete list of websites using Webamp:
|
||||
|
||||
- [Internet Archive](https://blog.archive.org/2018/10/02/dont-click-on-the-llama/) - The Internet Archive lets you preview winamp skins and listen to audio tracks using Webamp.
|
||||
- [Winampify.io](https://winampify.io/) - An online Spotify client using Webamp
|
||||
|
|
@ -136,31 +63,6 @@ A list of public websites that are using Webamp:
|
|||
- [winxp.now.sh](https://winxp.now.sh/) - A Windows XP clone in JavaScript with React ([GitHub](https://github.com/ShizukuIchi))
|
||||
- [www.dkdomino.zone](https://www.dkdomino.zone/album.html) - Someone's personal music player.
|
||||
|
||||
## Reference
|
||||
|
||||
- [skinspecs.pdf](http://members.xoom.it/skinart/tutorial/skinspecs..pdf)
|
||||
- [Skinner's Atlas 1.5 by Jellby](http://forums.winamp.com/showthread.php?p=951257)
|
||||
- [Winamp Skinning Tutorial](http://people.xmms2.org/~tru/promoe/Winamp_skinning_tutorial_1_5_0.pdf)
|
||||
- Sacrat Skinning tutorial parts [1](http://www.hugi.scene.org/online/hugi26/hugi%2026%20-%20graphics%20skinning%20sacrat%20winamp%20skinning%20tutorial%20-%201.htm), [2](http://www.hugi.scene.org/online/hugi26/hugi%2026%20-%20graphics%20skinning%20sacrat%20winamp%20skinning%20tutorial%20-%202.htm), [3](http://www.hugi.scene.org/online/hugi26/hugi%2026%20-%20graphics%20skinning%20sacrat%20winamp%20skinning%20tutorial%20-%203.htm), [4](http://www.hugi.scene.org/online/hugi26/hugi%2026%20-%20graphics%20skinning%20sacrat%20winamp%20skinning%20tutorial%20-%204.htm), and [5](http://www.hugi.scene.org/online/hugi26/hugi%2026%20-%20graphics%20skinning%20sacrat%20winamp%20skinning%20tutorial%20-%205.htm),
|
||||
- [Winamp Wiki](http://wiki.winamp.com/wiki/Creating_Classic_Skins)
|
||||
|
||||
## Predecessors
|
||||
|
||||
- [Webamp2x](http://forums.winamp.com/showthread.php?threadid=91850) An
|
||||
impressive implementation from 2002(!).
|
||||
- [JsAmp](http://freecog.net/2005/jsamp/demo/MainWindow.xhtml) An implementation from 2005 by @twm (via [Hacker News](https://news.ycombinator.com/item?id=15317723)).
|
||||
- [LlamaCloud Comp](https://vimeo.com/20149683) From 2011 by [Lee Martin](http://www.leemartin.com/) (via [Twitter](https://twitter.com/leemartin/status/910235793737814017))
|
||||
- [Winamp em HTML5 e Javascript](http://www.tidbits.com.br/winamp-em-html5-e-javascript)
|
||||
In 2010 a developer named Danilo posted one of his HTML5 experiments: "an
|
||||
audio player simulating good old Winamp". You will have to download the zip
|
||||
file.
|
||||
- [JuicyDrop](http://cggaurav.github.io/juicydrop/) An HTML5 implementation with
|
||||
less emphasis on being true to the skin, but fully featured visualizations.
|
||||
@cggaurav is keeping it alive on [GitHub](https://github.com/cggaurav/juicydrop)
|
||||
- [Spotiamp](https://web.archive.org/web/20160109180426/http://spotiamp.com/)
|
||||
The folks at Spotify reimplemented Winamp as a frontend for Spotify. Not in a
|
||||
browser, and only runs on Windows. It has since been discontinued.
|
||||
|
||||
## Thanks
|
||||
|
||||
- [Butterchurn](https://github.com/jberg/butterchurn), the amazing Mikdrop 2 WebGL implementation. Built and integrated into Webamp by: [jberg](https://github.com/jberg)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,43 @@
|
|||
# Webamp.org
|
||||
|
||||
This directory contains the code used for [Webamp.org](https://webamp.org), as opposed to the `webamp` NPM module.
|
||||
The Webamp demo site, [webamp.org](https://webamp.org), uses the same interface as the NPM module but adds the following functionality by utilizing Webamp's public API
|
||||
|
||||
- Error reporting using [Sentry](https://sentry.io)
|
||||
- Analytics using [Google Analytics](https://analytics.google.com/analytics/web/)
|
||||
- Updating document's title to reflect the currently playing track
|
||||
- [Media Session API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API) integration
|
||||
|
||||
Additionally, it makes use of some private Webamp APIs to add the following functionality:
|
||||
|
||||
- [Butterchun](https://github.com/jberg/butterchurn) integration to render [MilkDrop](https://en.wikipedia.org/wiki/MilkDrop) visualizations. We intend to make this part of the public API soon.
|
||||
- "Screenshot" mode `https://webamp.org/?screenshot=1` which can be used together with [Puppeteer](https://github.com/GoogleChrome/puppeteer) to automate the generation of Winamp skin screenshots
|
||||
|
||||
## Production Builds
|
||||
|
||||
To do an optimized build of the demo site, you can run:
|
||||
|
||||
yarn run build
|
||||
|
||||
If you wish to test this build locally, run:
|
||||
|
||||
yarn run serve
|
||||
|
||||
Then open the local ip/port that is output to the console in your browser.
|
||||
|
||||
## Deploying
|
||||
|
||||
[Netlify](https://www.netlify.com/) watches GitHub for new versions of master. When a new version is seen, it is automatically built using `npm run build` and pushed to the server. Additionally, Netlify will run a build on every pull request and include a link under the heading "Deploy preview ready!". This enables easy high level testing of pull requests.
|
||||
|
||||
In short, deploying should be as simple as pushing a commit to master.
|
||||
|
||||
Additionally, if you want to fork the project, deploying should be as simple as setting up a free Netlify account
|
||||
|
||||
### Advanced Usage
|
||||
|
||||
There are some "feature flags" which you can manipulate by passing a specially crafted URL hash. Simply supply a JSON blob after the `#` of the URL to change these settings:
|
||||
|
||||
- `skinUrl` (string) Url of the default skin to use. Note, this file must be served with the correct Allows Origin header.
|
||||
- `audioUrl` (string) Url of the default audio file to use. Note, this file must be served with the correct Allows Origin header.
|
||||
- `initialState` (object) Override the [initial Redux state](packages/webamp/js/reducers/index.ts). Values from this object will be recursively merged into the actual default state.
|
||||
|
||||
**Note:** These are intended mostly as development tools and are subject to change at any time.
|
||||
Loading…
Add table
Add a link
Reference in a new issue