Add the start of more documentation

README.md

@@ -8,7 +8,7 @@
   <p align="center">
     Take control over your content and stream it yourself.
     <br />
-    <a href="https://github.com/gabek/owncast"><strong>Explore the docs »</strong></a>
+    <a href="https://github.com/gabek/owncast/tree/master/doc"><strong>Explore the docs »</strong></a>
     <br />
     <br />
     <a href="https://goth.land/">View Demo</a>

config/config-example.yaml

@@ -8,7 +8,6 @@ videoSettings:
   streamingKey: abc123
 
   streamQualities:
-    - bitrate: 2000k
     - bitrate: 6000k
 
 files:

doc/README.md

@@ -0,0 +1,8 @@
+
+[Read the overview first before digging into any of the detailed documentation](../README.md)
+
+## Table of Contents
+
+* [Installing](installing.md)
+* [Configuration](configuration.md)
+* [S3 Storage](S3.md)

doc/S3.md

@@ -0,0 +1,13 @@
+Here are some details and tips specific to using S3 for storage.
+
+## File expiration 
+
+You should expire old segments on your S3 bucket.  [Here are some instructions on how to do that.](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/create-lifecycle.html)
+
+* Once an object expires you won't be charged for storage, even if the object isn't deleted immediately.
+* A one day object expiration lifecycle rule on objects is as low as you can go, so use that.
+* Because AWS [rounds the expiration to midnight of the next day](https://aws.amazon.com/premiumsupport/knowledge-center/s3-lifecycle-rule-delay/)  you may have a lot of old video chunks sitting around.  You can make the most of this by increasing the `maxNumberInPlaylist` value in your config file to something much higher, allowing users to rewind your stream back in time further.  If the video is available then you might as well make it available to your users.
+
+## CORS
+
+* Ugh.  CORS.  [You will need to enable CORS on your bucket](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html#how-do-i-enable-cors) so the web player can access the video.

doc/configuration.md

@@ -0,0 +1,26 @@
+# Configuration
+
+## Video Quality
+
+Owncast supports HLS [Adaptive bitrate streaming](https://en.wikipedia.org/wiki/Adaptive_bitrate_streaming), or in other words, different video qualities that can be used for different network conditions.
+
+You can edit the `config/config.yaml` file and add as many stream _variants_ as you like under the `videoSettings` block, like so:
+
+```
+  streamQualities:
+    - bitrate: 2000k
+    - bitrate: 6000k
+```
+
+You must have at least one bitrate specified.
+
+### Important caveats
+
+#### CPU Usage
+
+Each bitrate variant adds significant CPU usage and slows down the overall generation of video segments.  If you have a slow server running Owncast you should probably only have one bitrate variant in play.  If you add more and you notice that playback becomes choppy it's likely that everything is running too slowly for consistent playback.  Consider removing the additional variants and tweaking your single variant so it supports a wider variety of network conditions.
+
+#### Disk Usage
+
+More stream quality variants requires more disk space, since it's another copy of the video on disk.  If you're serving video locally and you have enough disk space then it's probably no big deal and files will rather quickly get rotated and cleaned up.  If you're using something like [S3 for storage](S3.md) then files won't get cleaned up until some point in the future, so you'll have more remote storage use in play.
+

doc/installing.md

@@ -0,0 +1,4 @@
+Transcoding is done with ffmpeg and that is the one dependency this project requires.  So make sure it exists.
+
+* Download from https://www.johnvansickle.com/ffmpeg/ and point your config file at it if needed.
+* You will need a somewhat recent version of ffmpeg (TODO: figure out what exact version).