init commit

docs/account-mgmt.md

@@ -0,0 +1,20 @@
+## Registering an Account ##
+
+To register an account, click the Account dropdown on the top bar, then click Register.  This option will only appear if you are not already logged in.  When choosing a username, make sure it meets the following requirements:
+
+  * Must be 1-20 characters long
+  * May only contain the letters 'A' through 'Z' (upper or lowercase), the digits '0' through '9', hyphens '-', and underscores '_'
+
+Be sure to pick a strong password that is not easy to guess and is not the same as your accounts on other websites.  Entering an email address is optional, and will allow you to recover your account if you ever forget your password.
+
+## Changing your Password or Email Address ##
+
+On the top bar of the website, click Account, then "Change Password/Email".  You must provide your current password in order to change either of these.  You can leave the email address box blank if you wish to remove the email address from your account (note that this means you will no longer be able to receive password reset emails).
+
+## Recovering an Account If You Lost the Password ##
+
+From the login page, click "Forgot password?"  You will be prompted to enter your username and email address.  The email address must match the one associated with your account.  If you have not added an email address to your account, you cannot reset your password automatically and will need to contact an administrator for help.  Otherwise, you will receive an email with a link to reset your password.
+
+## Account Profile ##
+
+Each CyTube account can set a profile photo and short description.  On the top bar, click Account, then Profile.  You can then enter the URL of a profile image, and enter a short text blurb that will be displayed when users hover over your name in the chat username list.  Note that this is publicly visible to anyone, so don't use a private photo or include private information in your description.

docs/chat-filters.md

@@ -0,0 +1,67 @@
+## Please do not use chat filters for emoticons! ##
+
+CyTube has an emotes feature which is better-suited for adding emoticons.
+Adding them as chat filters is more difficult to manage and uses more server
+resources.
+
+## Managing Chat Filters ##
+
+You can access the Chat Filters editor by clicking on "Channel Settings" at the
+top of the page, then the "Edit" dropdown, and selecting "Chat Filters".
+
+### Adding a New Chat Filter ###
+
+The first field allows you to enter a unique name for the filter.  This can be
+anything you like, but it must be unique among all filters on your channel.
+
+The "Filter regex" field is where you input the [regular
+expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
+that you would like to match.  Regular expressions allow you to build
+sophisticated filters that can find and replace patterns rather than simple
+words.  If you simply want to filter a word, you can just use `\bword\b`, as
+long as the word does not contain any of the special characters listed on the
+linked regular expression guide.  The leading and trailing `\b` ensure that you
+only match the whole word "word", and do not match instances where it is nested
+inside other words.
+
+If you're looking for a way to test your regular expression, there are many free
+tools available online, such as [this one](http://regexpal.com/).
+
+The "Flags" field allows you to control certain aspects of matching.  The "g"
+flag specifies that replacement will be done "globally"-- it will replace all
+instances of the regular expression instaed of just the first one.  The "i" flag
+makes matching case-insensitive, so that the capitalization of the message
+doesn't matter.  Flags can be combined by putting both of them in the box, e.g.
+"gi".
+
+The "Replacement" field is where you specify the text to be substituted for the
+original messagse.  This allows a limited subset of HTML tags to be used.
+
+## Editing Filters ##
+
+From the chat filter list, you can drag and drop filters to rearrange the order
+in which they are executed.  For each filter, there are two buttons.  The left
+button allows you to edit the filter, to update the regular expression, flags,
+replacement, and whether or not the filter should be applied to links inside of
+messages (this defaults to off).  The red trash can button removes the filter.
+
+## Export/Import ##
+
+The export/import feature allows you to back up your filter list and restore it
+later, or clone filters to a new channel.  Clicking "Export filter list" will
+populate the below textarea with a JSON encoded version of the filter list.
+Copy this and save it somewhere safe.  Later, you can paste this same text back
+into the box and click "Import filter list" to overwrite your current filters
+with the exported list.
+
+## Notes ##
+
+  * By default, CyTube automatically replaces URLs in chat messages with
+    clickable links.  You can disable this from the "Chat Settings" section
+    under the "General Settings" tab.
+  * By default, chat filters will not replace text inside of links, to prevent
+    them from being broken by the filter.  You can override this by editing the
+    filter and checking the "Filter Links" box.
+  * Incoming messages have HTML special characters sanitized before messages are
+    filtered.  You will have to account for this if you want to filter these
+    characters.  For example, instead of matching `<`, you must match `&lt;`.

docs/custom-media.md

@@ -0,0 +1,179 @@
+CyTube Custom Content Metadata
+==============================
+
+*Last updated: 2019-05-05*
+
+## Purpose ##
+
+CyTube currently supports adding custom audio/video content by allowing the user
+to supply a direct URL to an audio/video file.  The server uses `ffprobe` to
+probe the file for various metadata, including the codec/container format and
+the duration.  This approach has a few disadvantages over the officially
+supported media providers, namely:
+
+  * Since it accepts a single file, it is not possible to provide multiple
+    source URLs with varying formats or bitrates to allow viewers to select the
+    best source for their computer.
+    - It also means it is not possible to provide text tracks for subtitles or
+      closed captioning, or to provide image URLs for thumbnails/previews.
+  * Probing the file with `ffprobe` is slow, especially if the content is hosted
+    in a far away network location, which at best is inconvenient and at worst
+    results in timeouts and inability to add the content.
+  * Parsing the `ffprobe` output is inexact, and may sometimes result in
+    detecting the wrong format, or failing to detect the title.
+
+This document specifies a new supported media provider which allows users to
+provide a JSON manifest specifying the metadata for custom content in a way that
+avoids the above issues and is more flexible for extension.
+
+## Custom Manifest URLs ##
+
+Custom media manifests are added to CyTube by adding a link to a public URL
+hosting the JSON metadata manifest.  Pasting the JSON directly into CyTube is
+not supported.  Valid JSON manifests must:
+
+  * Have a URL path ending with the file extension `.json` (not counting
+    querystring parameters)
+  * Be served with the `Content-Type` header set to `application/json`
+  * Be retrievable at any time while the item is on the playlist (CyTube may
+    re-request the metadata for an item already on the playlist to revalidate)
+  * Respond to valid requests with a 200 OK HTTP response code (redirects are
+    not supported)
+  * Respond within 10 seconds
+  * Not exceed 100 KiB in size
+
+## Manifest Format ##
+
+To add custom content, the user provides a JSON object with the following keys:
+
+  * `title`: A nonempty string specifying the title of the content.  For legacy
+    reasons, CyTube currently truncates this to 100 UTF-8 characters.
+  * `duration`: A non-negative, finite number specifying the duration, in
+    seconds, of the content.  This is what the server will use for timing
+    purposes.  Decimals are allowed, but CyTube's timer truncates the value as
+    an integer number of seconds, so including fractional seconds lends no
+    advantage.
+  * `live`: An optional boolean (default: `false`) indicating whether the
+    content is live or pre-recorded.  For live content, the `duration` is
+    ignored, and the server won't advance the playlist automatically.
+  * `thumbnail`: An optional string specifying a URL for a thumbnail image of
+    the content.  CyTube currently does not support displaying thumbnails in the
+    playlist, but this functionality may be offered in the future.
+  * `sources`: A nonempty list of playable sources for the content.  The format
+    is described below.
+  * `textTracks`: An optional list of text tracks for subtitles or closed
+    captioning.  The format is described below.
+
+### Source Format ###
+
+Each source entry is a JSON object with the following keys:
+
+  * `url`: A valid URL that browsers can use to retrieve the content.  The URL
+    must resolve to a publicly-routed IP address, and must the `https:` scheme.
+  * `contentType`: A string representing the MIME type of the content at `url`.
+    A list of acceptable MIME types is provided below.
+  * `quality`: A number representing the quality level of the source.  The
+    supported quality levels are `240`, `360`, `480`, `540`, `720`, `1080`,
+    `1440`, and `2160`.  This may be extended in the future.
+  * `bitrate`: An optional number indicating the bitrate (in Kbps) of the
+    content.  It must be a positive, finite number if provided.  The bitrate is
+    not currently used by CyTube, but may be used by extensions or custom
+    scripts to determine whether this source is feasible to play on the viewer's
+    internet connection.
+
+#### Acceptable MIME Types ####
+
+The following MIME types are accepted for the `contentType` field:
+
+  * `video/mp4`
+  * `video/webm`
+  * `video/ogg`
+  * `application/x-mpegURL` (HLS streams)
+    - HLS is only tested with livestreams.  VODs are accepted, but I do not test
+      this functionality.
+  * `application/dash+xml` (DASH streams)
+    - Support for DASH is experimental
+  * ~~`rtmp/flv`~~
+    - In light of Adobe phasing out support for Flash, and many browsers
+      already dropping support, RTMP is not supported by this feature.
+      RTMP streams are only supported through the existing `rt:` media
+      type.
+  * `audio/aac`
+  * `audio/ogg`
+  * `audio/mpeg`
+
+Other audio or video formats, such as AVI, MKV, and FLAC, are not supported due
+to lack of common support across browsers for playing these formats.  For more
+information, refer to
+[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility).
+
+### Text Track Format ###
+
+Each text track entry is a JSON object with the following keys:
+
+
+  * `url`: A valid URL that browsers can use to retrieve the track.  The URL
+    must resolve to a publicly-routed IP address, and must the `https:` scheme.
+  * `contentType`: A string representing the MIME type of the track at `url`.
+    The only currently supported MIME type is
+    [`text/vtt`](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API).
+  * `name`: A name for the text track.  This is displayed in the menu for the
+    viewer to select a text track.
+  * `default`: Enable track by default.  Optional boolean attribute to enable
+    a subtitle track to the user by default.
+
+**Important note regarding text tracks and CORS:**
+
+By default, browsers block requests for WebVTT tracks hosted on different
+domains than the current page.  In order for text tracks to work cross-origin,
+the `Access-Control-Allow-Origin` header needs to be set by the remote server
+when serving the VTT file.  See
+[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)
+for more information about setting this header.
+
+## Example ##
+
+    {
+      "title": "Test Video",
+      "duration": 10,
+      "live": false,
+      "thumbnail": "https://example.com/thumb.jpg",
+      "sources": [
+        {
+          "url": "https://example.com/video.mp4",
+          "contentType": "video/mp4",
+          "quality": 1080,
+          "bitrate": 5000
+        }
+      ],
+      "textTracks": [
+        {
+          "url": "https://example.com/subtitles.vtt",
+          "contentType": "text/vtt",
+          "name": "English Subtitles",
+          "default": true
+        }
+      ]
+    }
+
+## Permissions ##
+
+The permission node to allow users to add custom content is the same as the
+permission node for the existing raw file support.  Custom content is considered
+as an extension of the existing feature.
+
+## Unsupported/Undefined Behavior ##
+
+The behavior under any the following circumstances is not defined by this
+specification, and any technical support in these cases is voided.  This list is
+non-exhaustive.
+
+  * Source URLs or text track URLs are hosted on a third-party website that does
+    not have knowledge of its content being played on CyTube.
+  * The webserver hosting the source or text track URLs serves a different MIME
+    type than the one specified in the manifest.
+  * The webserver hosting the source or text track URLs serves a file that does
+    not match the MIME type specified in the `Content-Type` HTTP header returned
+    to the browser.
+  * The manifest includes source URLs or text track URLs with expiration times,
+    session IDs, etc. in the URL querystring.

docs/gdrive-userscript-serveradmins.md

@@ -0,0 +1,24 @@
+# Google Drive Userscript Setup
+
+In response to increasing difficulty and complexity of maintaining Google Drive
+support, the native player is being phased out in favor of requiring a
+userscript to allow each client to fetch the video stream links for themselves.
+Users will be prompted with a link to `/google_drive_userscript`, which explains
+the situation and instructs how to install the userscript.
+
+As a server admin, you must generate the userscript from the template by using
+the following command:
+
+```sh
+npm run generate-userscript <site name> <url> [<url>...]
+```
+
+The first argument is the site name as it will appear in the userscript title.
+The remaining arguments are the URL patterns on which the script will run.  For
+example, for cytu.be I use:
+
+```sh
+npm run generate-userscript CyTube http://cytu.be/r/* https://cytu.be/r/*
+```
+
+This will generate `www/js/cytube-google-drive.user.js`. If you've changed the channel path, be sure to take that into account.

docs/google-drive-subtitles.md

@@ -0,0 +1,24 @@
+Adding subtitles to Google Drive
+================================
+
+  1. Upload your video to Google Drive
+  2. Right click the video in Google Drive and click Manage caption tracks
+  3. Click Add new captions or transcripts
+  4. Upload a supported subtitle file
+    * I have verified that Google Drive will accept .srt and .vtt subtitles.  It
+      might accept others as well, but I have not tested them.
+
+Once you have uploaded your subtitles, they should be available the next time
+the video is refreshed by CyTube (either restart it or delete the playlist item
+and add it again).  On the video you should see a speech bubble icon in the
+controls, which will pop up a menu of available subtitle tracks.
+
+## Limitations ##
+
+  * Google Drive converts the subtitles you upload into a custom format which
+    loses some information from the original captions.  For example, annotations
+    for who is speaking are not preserved.
+  * As far as I know, Google Drive is not able to automatically detect when
+    subtitle tracks are embedded within the video file.  You must upload the
+    subtitles separately (there are plenty of tools to extract
+    captions/subtitles from MKV and MP4 files).

docs/index.md

@@ -0,0 +1,15 @@
+# User Guide #
+
+This user guide is a work in progress rewrite of the old user guide.  If you notice something is missing, it probably hasn't been ported over from [here](https://github.com/calzoneman/sync/wiki/CyTube-3.0-User-Guide) yet.
+
+## I want to know more about... ##
+
+* [Registering and managing my user account](account-mgmt.md)
+* [Available user preferences](user-settings.md)
+* [Adding subtitles to Google Drive videos](google-drive-subtitles.md)
+* [Managing chat filters](chat-filters.md)
+
+## I need help! ##
+
+1. Please read the [FAQ](https://github.com/calzoneman/sync/wiki/Frequently-Asked-Questions) and check whether that answers your question.
+2. If not, you can contact someone for help.  IRC support is provided on `irc.esper.net #cytube` ([webchat](https://webchat.esper.net/?channels=cytube) available) for https://cytu.be and general questions about using the software.  If nobody is available on IRC, or you want to speak privately, email one of the contacts on https://cytu.be/contact.

docs/new-account-chat-restrictions.md

@@ -0,0 +1,29 @@
+Restricting New Accounts from Chat
+==================================
+
+With the rising availability and popularity of VPNs and proxies, dedicated
+trolls may often come back again and again with a new proxy after being IP
+banned and continue spamming.  In order to combat this, a new feature has been
+added to make it more difficult to rejoin quickly and continue spamming.
+
+Channel moderators now have the ability to configure 2 different settings:
+
+  * How long an account must be active before the user can send any chat message
+  * How long an account must be active before the user can send a chat message
+    containing a link
+
+This limit applies to both chat messages sent to the channel as well as private
+messages.  Both of these settings can be configured from the Channel Settings
+menu at the top of the page, under the General Settings tab.  By default,
+accounts must be at least 10 minutes old to chat, and 1 hour old to send links
+in chat.  Setting either restriction to 0 will disable that restriction.
+
+The age of an account is determined as follows:
+
+  * If the user is logged in as a registered account, the registration time of
+    the account is used.
+  * Otherwise, the timestamp of the session cookie is used.
+
+The session cookie is set whenever a user first joins a channel, and is reset
+whenever the user's IP address changes.  Different browsers will have different
+session cookies.

docs/raw-videos.md

@@ -0,0 +1,59 @@
+# 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 (AV1)
+  * MP4 (H.264)
+  * WebM (AV1)
+  * 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.

docs/socketconfig.md

@@ -0,0 +1,57 @@
+Socket.IO Client Configuration
+==============================
+
+As of 2015-10-25, the legacy `/sioconfig` JavaScript for retrieving connection
+information is being deprecated in favor of a new API.  The purpose of this
+change is to allow partitioning channels across multiple servers in order to
+better handle increasing traffic.
+
+To get the socket.io configuration for the server hosting a particular channel,
+make a `GET` request to `/socketconfig/<channel name>.json`.  The response will
+be a JSON object containing a list of acceptable servers to connect to, or an
+error message.
+
+Examples:
+
+```
+GET /socketconfig/test.json
+200 OK
+
+{
+    "servers": [
+        {
+            "url": "https://localhost:8443",
+            "secure": true
+        },
+        {
+            "url": "http://localhost:1337",
+            "secure": false
+        },
+        {
+            "url": "https://local6:8443",
+            "secure": true,
+            "ipv6": true
+        },
+        {
+            "url": "http://local6:1337",
+            "secure": false,
+            "ipv6": true
+        }
+    ]
+}
+
+GET /socketconfig/$invalid$.json
+404 Not Found
+
+{
+    "error": "Channel \"$invalid$\" does not exist."
+}
+```
+
+Each entry in the `servers` array has `"secure":true` if the connection is
+secured with TLS, otherwise it it is false.  An entry with `"ipv6":true`
+indicates that the server is listening on the IPv6 protocol.
+
+You can pick any URL to connect socket.io to in order to join the specified
+channel.  I recommend picking one with `"secure":true`, only choosing an
+insecure connection if implementing a TLS connection is infeasible.

docs/user-settings.md

@@ -0,0 +1,56 @@
+# User Preferences #
+
+From any CyTube channel, you can click the Options link at the top of the page to open a dialog where you can change your personal preferences.  This page explains each of the available options.
+
+## General ##
+
+General interface preferences.
+
+Setting | Description
+--------|------------
+Theme | Choose from different colorschemes for the website.
+Layout | Choose from different layouts for elements on the page.  Fluid layouts will expand to fill the entire window, while compact layouts will remain the same size.  "Synchtube" layout is the same as the default layout, but mirrored.
+Ignore Channel CSS | Don't load custom stylesheets for each channel.  Requires a refresh to take effect.
+Ignore Channel JavaScript | Don't load custom scripts for each channel.  The Script Access tab allows you to manage your preferences on a per-channel basis, but if this setting is checked, scripts will be globally disallowed and you will not be prompted to accept them when joining a channel.
+
+## Playback ##
+
+Preferences for video playback and the playlist.
+
+Setting | Description
+--------|------------
+Synchronize video playback | By default, CyTube attempts to synchronize the video so that everyone is watching at the same time.  Some users with poor internet connections may wish to disable this in order to prevent excessive buffering due to constantly seeking forward.
+Synch threshold | The number of seconds your video is allowed to be ahead/behind before it is forcibly seeked to the correct position.  Should be set to at least 2 seconds to avoid buffering problems and choppy playback.
+Set wmode=transparent | There's probably no reason to touch this unless you know what you're doing.  Having a non-transparent wmode can cause modals to display behind the video player, but also can cause performance issues in some situations.
+Remove the video player | Automatically remove the video player on page load.  Equivalent to manually clicking Layout->Remove Video every time you load a channel.
+Hide playlist buttons by default | Hides the control buttons from each video in the playlist, so that only the title is displayed.  The control buttons can be shown by right clicking the video item in the playlist.
+Old style playlist buttons | Legacy feature introduced in CyTube 2.0 for those who preferred the old 1.0-style video control buttons.
+Quality Preference | Sets the preferred quality for player types that support quality selection (currently, this is YouTube, Vimeo, Dailymotion, Google Drive, and Google+).  If your preferred quality is not available, the next lowest quality will be used.
+
+## Chat ##
+
+Preferences for the integrated chatroom.
+
+Setting | Description
+--------|------------
+Show timestamps in chat | When enabled, a timestamp is prepended to each chat message.  For example, `[09:45:10] message here`.
+Sort userlist by rank | Controls whether the username list is sorted alphabetically and by rank, or just alphabetically.
+Sort AFKers to bottom | When enabled, usernames of AFK users will be sorted to the bottom of the username list.
+Blink page title on new messages | Controls the conditions under which the tab title blinks between the channel title and `*Chat*` when a new message arrives.
+Notification sound on new messages | Controls the conditions under which a notification sound is played when a new message arrives.
+Add a send button to chat | Adds a clickable button to send chat messages.  Only really useful for virtual keyboards that lack a dedicated Enter key.
+Disable chat emotes | Disables the automatic conversion of channel-defined emote codes to inline images.
+
+## Script Access ##
+
+Manage your preferences for allowing or denying custom scripts for channels you've visited.  A channel will only appear here if you checked "Remember my preference" when allowing or denying a channel script.  You can toggle the preference between "Allow" and "Deny", or click "Clear Preference" to remove the saved preference, so that you will be asked every time you join the channel.
+
+## Moderator ##
+
+Settings that only apply to channel moderators.
+
+Setting | Description
+--------|------------
+Show name color | Colors your username in chat (the same color as in the username list).  This setting is also controlled by the small button labeled "M" in the upper right corner of chat.
+Show join messages | Display a message every time a user logs in to the chat.
+Show shadowmuted messages | Show chat messages from shadowmuted users.  These messages will appear ~~struck through~~, and only moderators with this setting enabled will see them.