diff --git a/docs/ussage.md b/docs/ussage.md index 022bdaeb..1b6f5d3d 100644 --- a/docs/ussage.md +++ b/docs/ussage.md @@ -1,16 +1,6 @@ -# Use Winamp2-js in your project +# Ussage -**PRE ALPHA** - -There are many websites that could potentially benefit from having Winamp embeded in them. That said, nobody that I know of is really doing this in production. In an attempt to try this out, I have published Winamp2-js as an NPM package. The API is far from stable as I don't actually know all the various use-cases it should support. Some potential ones are: - -* A player that comes preloaded with a SoundCloud playlist. -* A player that's compatible with [https://github.com/justinfrankel/WHUMP] database files. -* A player that can be used to demonstrate skins on a skins website. -* A generic podcast widget. -* Something else? - -You can attempt to use it in your JS project like so: +Here's how to use Winamp-js in your own project: ## Install @@ -27,7 +17,7 @@ Or, you can include it via a script tag: ## Create a container -Create a DOM element somewhere in your HTML document: +Create a DOM element somewhere in your HTML document. This will eventually contain Winamp2-js. ```html
@@ -60,17 +50,144 @@ const winamp = new Winamp({ // Can be downloaded from https://github.com/captbaritone/winamp2-js/raw/master/skins/base-2.91.wsz url: "path/to/skins/base-2.91.wsz" }, - enableHotkeys: true // Enable hotkeys }); // Render after the skin has loaded. winamp.renderWhenReady(document.getElementById('winamp-container')); ``` -## Notes: +## API -* This should not be considered "production" code. - * Winamp2-js does not support Internet Explorer. - * Winamp2-js was built to run on its own page, it may not play well with surrounding CSS. +Many methods on the winamp 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 Winamp2-js depends upon. It is recomended 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. + +```JavaScript +const options = { + // Required. An object representing the initial skin to use. + // 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 the with correct CORs headers. + avaliableSkins: [ + { 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. 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 + // avaliable when the user is offline. + requiresNetwork: true + }] +}; +const winamp = new Winamp(options); +``` + +## Instance Methods + +The `Winamp` class has the following _instance_ methods: + +### `appendTracks(tracks)` + +Add an array of `track`s (see above) to the end of the playlist. + +```JavaScript +winamp.appendTracks([ + {url: 'https://example.com/track1.mp3'}, + {url: 'https://example.com/track2.mp3'}, + {url: 'https://example.com/track3.mp3'} +]); +``` + +### `setTracksToPlay(tracks)` + +Replace the playlist with an array of `track`s (see above) and begin playing the first track. + +```JavaScript +winamp.appendTracks([ + {url: 'https://example.com/track1.mp3'}, + {url: 'https://example.com/track2.mp3'}, + {url: 'https://example.com/track3.mp3'} +]); +``` + +### `renderWhenReady(domNode)` + +Winamp2-js will wait until it has fetch the skin and fully parsed it, and then render itself into the given container. A promise is returned which will resolve after the render is complete. + +```JavaScript +const container = document.getElementById('winamp-container'); +winamp.renderWhenReady(container).then(() => { + console.log('rendered winamp!'); +}); +``` + +## Notes + +* Internet Explorer is not supported. +* Winamp2-js injects CSS into the page. The CSS is namespaced under `#winamp2-js` ID, so it should not interfere with anything on the host page. +* Winamp2-js' HTML contains non-prefixed IDs and class names. If you have CSS on your page that is not namespaced, it may accidently be applied to Winamp2-js. 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. -* This API is subject to change at any time. * 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.