From d357b30f9d2d0757f4da6aa0f81ae155f5ce574a Mon Sep 17 00:00:00 2001
From: calzoneman <calzoneman@gmail.com>
Date: Thu, 19 May 2016 21:07:42 -0700
Subject: [PATCH] Add raw video documentation

---
 docs/raw-videos.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++
 src/ffmpeg.js      |  7 +++---
 2 files changed, 61 insertions(+), 3 deletions(-)
 create mode 100644 docs/raw-videos.md

diff --git a/docs/raw-videos.md b/docs/raw-videos.md
new file mode 100644
index 00000000..e3e33d50
--- /dev/null
+++ b/docs/raw-videos.md
@@ -0,0 +1,57 @@
+# Raw Videos / Audio #
+
+Want to host your own video/audio files for use on CyTube?  For servers with the
+ffprobe module enabled, CyTube supports this!  However, in order to provide a
+consistent experience, there are limitations.
+
+## Hosting the File ##
+
+CyTube requires a direct link to the file in order to query it for metadata such
+as duration and encoding.  The website where you host the file needs to be able
+to serve the video directly (rather than embedding it in a flash
+player/iframe/etc.).  It also needs to serve the correct MIME type for the video
+in the `Content-Type` HTTP header, e.g. `video/mp4`.
+
+I don't recommend hosting videos on Dropbox-type services, as they aren't built
+to distribute video to many users at a time and often have strict bandwidth
+limits.  File hosting sites such as Putlocker also cause problems due to being
+unable to serve the file directly, or due to binding the link to the IP address
+of the user who retrieved it.  For best results when using raw video, host the
+video yourself on a VPS or dedicated server with plenty of bandwidth.
+
+Note that CyTube only queries the file for metadata, it does not proxy it for
+users!  Every user watching the video will be downloading it individually.
+
+## Encoding the Video ##
+
+Current internet browsers are very limited in what codecs they can play
+natively.  Accordingly, CyTube only supports a few codecs:
+
+**Video**
+
+  * MP4 (H.264)
+  * WebM (VP8)
+  * WebM (VP9)
+  * Ogg/Theora
+
+**Audio**
+
+  * MP3
+  * Ogg/Vorbis
+
+If your video is in some other format (such as MKV or AVI), then it will need to
+be re-encoded.  There are plenty of free programs available to re-encode video
+files, such as [ffmpeg](http://ffmpeg.org/) and
+[handbrake](http://handbrake.fr/).
+
+For best results, encode as an MP4 using H.264.  This is natively supported by
+many browsers, and can also be played using a fallback flash player for older
+browsers that don't support it natively.  Always encode with the
+[faststart](https://trac.ffmpeg.org/wiki/Encode/H.264#faststartforwebvideo)
+flag.
+
+### Subtitles ###
+
+Unfortunately, soft-subtitles are not supported right now.  This is something
+that may be supported in the future, but currently if you need subtitles, they
+will have to be hardsubbed onto the video itself.
diff --git a/src/ffmpeg.js b/src/ffmpeg.js
index e16fb4ad..1631d22e 100644
--- a/src/ffmpeg.js
+++ b/src/ffmpeg.js
@@ -93,7 +93,7 @@ function testUrl(url, cb, redirCount) {
                 return cb("The request for the audio/video file has been redirected " +
                           "more than twice.  This could indicate a misconfiguration " +
                           "on the website hosting the link.  For best results, use " +
-                          "a direct link.");
+                          "a direct link.  See https://git.io/vrE75 for details.");
             }
             return testUrl(fixRedirectIfNeeded(data, res.headers["location"]), cb,
                     redirCount + 1);
@@ -107,7 +107,8 @@ function testUrl(url, cb, redirCount) {
             return cb("Expected a content-type starting with 'audio' or 'video', but " +
                       "got '" + res.headers["content-type"] + "'.  Only direct links " +
                       "to video and audio files are accepted, and the website hosting " +
-                      "the file must be configured to send the correct MIME type.");
+                      "the file must be configured to send the correct MIME type.  " +
+                      "See https://git.io/vrE75 for details.");
         }
 
         cb();
@@ -386,7 +387,7 @@ exports.query = function (filename, cb) {
                 cb(null, data);
             } else {
                 return cb("File did not contain an acceptable codec.  See " +
-                          "https://git.io/va9g9 for details.");
+                          "https://git.io/vrE75 for details.");
             }
         });
     });