Add real API documentation

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
 <div id='winamp-container'></div>
@@ -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.