Updating docs, closing #26

DEVELOPERS.md

@@ -1,6 +1,6 @@
 Audiogram was developed for our particular needs but hopefully it should be reasonably hackable besides the options provided.  Here are some examples of possible customization that involve writing/editing the code and notes on how you could get started.
 
-## Use different animations besides the wave/bars
+## Use different animations besides the wave/bars/bricks
 
 The code that handles drawing a waveform involves three pieces:
 
@@ -55,6 +55,26 @@ The `node-canvas` step that draws an individual image for each frame accounts fo
 
 The FFmpeg step accounts for most of the remaining rendering time, and is defined in `audiogram/combine-frames.js`. If you're an FFmpeg expert and have thoughts on how to more intelligently render the final video, please let us know! You may at least be able to see some improvements by forcing FFmpeg to use several threads with the `-threads` flag on a multicore machine.
 
+## Extend themes
+
+The current renderer (in `renderer/`) looks for certain theme settings defined in `settings/themes.json` when it's drawing the frames for a video.  You could extend a theme with your own option names, and then reference them in the renderer.
+
+As an example, if you wanted to fill the wave with a gradient instead of a solid color, you could add the new option `waveColor2` to a theme and add this bit of extra logic into `renderer/patterns.js`:
+
+```js
+// If there's a second wave color, use a gradient instead
+if (options.waveColor2) {
+  var gradient = context.createLinearGradient(0, 0, options.width, 0);
+
+  gradient.addColorStop(0, options.waveColor);
+  gradient.addColorStop(1, options.waveColor2);
+
+  context.fillStyle = gradient;
+  context.strokeStyle = gradient;
+
+}
+```
+
 ## Use different dimensions besides 1280x720
 
 The width and height for a video are defined in `settings/themes.json`.  If you change them there, you will get a video of the appropriate size.  The simplest way to handle multiple sizes would be to define multiple themes:

INSTALL.md

@@ -17,7 +17,7 @@ You can skip almost all of the installation if you use [Docker](#docker-installa
 
 ## Ubuntu 14.04+ installation
 
-Note: if you're using something with very little memory, like a Digital Ocean micro droplet, it might cause an installation problem on the last step. See [Linux troubleshooting](INSTALL.md#linux-troubleshooting) below for how to fix it.
+Note: if you're using something with < 1GB of RAM, like a Digital Ocean micro droplet, it might cause an installation problem on the last step. See [Linux troubleshooting](INSTALL.md#linux-troubleshooting) below for how to fix it.
 
 An example bootstrap script for installing Audiogram on Ubuntu looks like this:
 
@@ -111,7 +111,7 @@ npm install
 
 ## Windows installation
 
-Installing these dependencies on Windows is pretty dicey.  If you're running Windows 10, you'll probably have better luck installing [Docker for Windows](https://docs.docker.com/docker-for-windows/) and then following the [Docker instructions](INSTALL.md#docker-installation) below. Otherwise your best bet is probably to [install it on a remote Linux server](SERVER.md#im-the-only-one-using-it-and-installing-it-on-macwindows-was-a-real-drag).
+Installing these dependencies on Windows is an uphill battle.  If you're running Windows 10, you'll probably have better luck installing [Docker for Windows](https://docs.docker.com/docker-for-windows/) and then following the [Docker instructions](INSTALL.md#docker-installation) below. Otherwise your best bet is probably to [install it on a remote Linux server](SERVER.md#im-the-only-one-using-it-and-installing-it-on-macwindows-was-a-real-drag).
 
 ## Docker installation
 

THEMES.md

@@ -17,7 +17,7 @@ The best way to get a feel for this is probably to look at the included themes f
 
 ### Required options
 
-The following options are required (they aren't required for every theme, as long as they're present in `default`):
+The following options are required (they aren't required for every theme as long as they're present in `default`):
 
 * `width` - desired video width in pixels (e.g. `1280`)
 * `height` - desired video height in pixels (e.g. `720`)
@@ -75,10 +75,6 @@ You can set both a `backgroundColor` and a `backgroundImage`, in which case the
 
 After you've edited `settings/themes.json`, you'll want to run either `npm run rebuild` or `npm start` to rebundle the new themes for the editor.
 
-### A note about layout
-
-When designing your own themes, keep in mind that web browsers and social apps put a variety of overlays on videos when they're paused or playing, like a progress bar at the bottom or a fat play button in the middle. Try to space things out so that important parts of your design aren't obscured.
-
 ### A note about fonts
 
 By default, Audiogram will already have access to fonts on your system.  This might be fine for local use, but it will become a problem on a server without the fonts you're used to, or if you want to use a specific font across lots of installations.
@@ -107,3 +103,20 @@ The bad news is that the font handling in the library Audiogram relies on has a
 2. Ensure that the font name defined in the font file's metadata matches the font name you're using (e.g. if your font definition says "32px Gotham", make sure that when you open your font file in something like Font Forge and look at the metadata, the font name is also "Gotham" and not some variant.
 
 3. Use TrueType fonts (.ttf) rather than other formats.
+
+
+### A note about layout
+
+When designing your own themes, keep in mind that web browsers and social apps put a variety of overlays on videos when they're paused or playing, like a progress bar at the bottom or a fat play button in the middle. Try to space things out so that important parts of your design aren't obscured.
+
+These diagrams show you what gets covered up in various web players for a 1280x720 video (the in-app players are generally more minimalistic):
+
+![Facebook - embedded, hovering](https://cloud.githubusercontent.com/assets/2120446/17449695/3f1e008a-5b2a-11e6-8a5a-f30b80141f7e.png)
+
+![Facebook - embedded, paused](https://cloud.githubusercontent.com/assets/2120446/17449742/7b547bec-5b2a-11e6-9107-ee79620c7612.png)
+
+![Facebook - in feed, hovering](https://cloud.githubusercontent.com/assets/2120446/17449722/5e841f5e-5b2a-11e6-9cca-e4072b6f3eb7.png)
+
+![Twitter - in feed, hovering](https://cloud.githubusercontent.com/assets/2120446/17449733/70d706b2-5b2a-11e6-9bbf-3659c36a4f41.png)
+
+![Tumblr - hovering](https://cloud.githubusercontent.com/assets/2120446/17449725/6637ff5e-5b2a-11e6-90bc-62743b13860a.png)