docs/custom-media.md

   1 CyTube Custom Content Metadata
   2 ==============================
   3
   4 *Last updated: 2019-05-05*
   5
   6 ## Purpose ##
   7
   8 CyTube currently supports adding custom audio/video content by allowing the user
   9 to supply a direct URL to an audio/video file.  The server uses `ffprobe` to
  10 probe the file for various metadata, including the codec/container format and
  11 the duration.  This approach has a few disadvantages over the officially
  12 supported media providers, namely:
  13
  14   * Since it accepts a single file, it is not possible to provide multiple
  15     source URLs with varying formats or bitrates to allow viewers to select the
  16     best source for their computer.
  17     - It also means it is not possible to provide text tracks for subtitles or
  18       closed captioning, or to provide image URLs for thumbnails/previews.
  19   * Probing the file with `ffprobe` is slow, especially if the content is hosted
  20     in a far away network location, which at best is inconvenient and at worst
  21     results in timeouts and inability to add the content.
  22   * Parsing the `ffprobe` output is inexact, and may sometimes result in
  23     detecting the wrong format, or failing to detect the title.
  24
  25 This document specifies a new supported media provider which allows users to
  26 provide a JSON manifest specifying the metadata for custom content in a way that
  27 avoids the above issues and is more flexible for extension.
  28
  29 ## Custom Manifest URLs ##
  30
  31 Custom media manifests are added to CyTube by adding a link to a public URL
  32 hosting the JSON metadata manifest.  Pasting the JSON directly into CyTube is
  33 not supported.  Valid JSON manifests must:
  34
  35   * Have a URL path ending with the file extension `.json` (not counting
  36     querystring parameters)
  37   * Be served with the `Content-Type` header set to `application/json`
  38   * Be retrievable at any time while the item is on the playlist (CyTube may
  39     re-request the metadata for an item already on the playlist to revalidate)
  40   * Respond to valid requests with a 200 OK HTTP response code (redirects are
  41     not supported)
  42   * Respond within 10 seconds
  43   * Not exceed 100 KiB in size
  44
  45 ## Manifest Format ##
  46
  47 To add custom content, the user provides a JSON object with the following keys:
  48
  49   * `title`: A nonempty string specifying the title of the content.  For legacy
  50     reasons, CyTube currently truncates this to 100 UTF-8 characters.
  51   * `duration`: A non-negative, finite number specifying the duration, in
  52     seconds, of the content.  This is what the server will use for timing
  53     purposes.  Decimals are allowed, but CyTube's timer truncates the value as
  54     an integer number of seconds, so including fractional seconds lends no
  55     advantage.
  56   * `live`: An optional boolean (default: `false`) indicating whether the
  57     content is live or pre-recorded.  For live content, the `duration` is
  58     ignored, and the server won't advance the playlist automatically.
  59   * `thumbnail`: An optional string specifying a URL for a thumbnail image of
  60     the content.  CyTube currently does not support displaying thumbnails in the
  61     playlist, but this functionality may be offered in the future.
  62   * `sources`: A nonempty list of playable sources for the content.  The format
  63     is described below.
  64   * `textTracks`: An optional list of text tracks for subtitles or closed
  65     captioning.  The format is described below.
  66
  67 ### Source Format ###
  68
  69 Each source entry is a JSON object with the following keys:
  70
  71   * `url`: A valid URL that browsers can use to retrieve the content.  The URL
  72     must resolve to a publicly-routed IP address, and must the `https:` scheme.
  73   * `contentType`: A string representing the MIME type of the content at `url`.
  74     A list of acceptable MIME types is provided below.
  75   * `quality`: A number representing the quality level of the source.  The
  76     supported quality levels are `240`, `360`, `480`, `540`, `720`, `1080`,
  77     `1440`, and `2160`.  This may be extended in the future.
  78   * `bitrate`: An optional number indicating the bitrate (in Kbps) of the
  79     content.  It must be a positive, finite number if provided.  The bitrate is
  80     not currently used by CyTube, but may be used by extensions or custom
  81     scripts to determine whether this source is feasible to play on the viewer's
  82     internet connection.
  83
  84 #### Acceptable MIME Types ####
  85
  86 The following MIME types are accepted for the `contentType` field:
  87
  88   * `video/mp4`
  89   * `video/webm`
  90   * `video/ogg`
  91   * `application/x-mpegURL` (HLS streams)
  92     - HLS is only tested with livestreams.  VODs are accepted, but I do not test
  93       this functionality.
  94   * `application/dash+xml` (DASH streams)
  95     - Support for DASH is experimental
  96   * ~~`rtmp/flv`~~
  97     - In light of Adobe phasing out support for Flash, and many browsers
  98       already dropping support, RTMP is not supported by this feature.
  99       RTMP streams are only supported through the existing `rt:` media
 100       type.
 101   * `audio/aac`
 102   * `audio/ogg`
 103   * `audio/mpeg`
 104
 105 Other audio or video formats, such as AVI, MKV, and FLAC, are not supported due
 106 to lack of common support across browsers for playing these formats.  For more
 107 information, refer to
 108 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility).
 109
 110 ### Text Track Format ###
 111
 112 Each text track entry is a JSON object with the following keys:
 113
 114
 115   * `url`: A valid URL that browsers can use to retrieve the track.  The URL
 116     must resolve to a publicly-routed IP address, and must the `https:` scheme.
 117   * `contentType`: A string representing the MIME type of the track at `url`.
 118     The only currently supported MIME type is
 119     [`text/vtt`](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API).
 120   * `name`: A name for the text track.  This is displayed in the menu for the
 121     viewer to select a text track.
 122
 123 **Important note regarding text tracks and CORS:**
 124
 125 By default, browsers block requests for WebVTT tracks hosted on different
 126 domains than the current page.  In order for text tracks to work cross-origin,
 127 the `Access-Control-Allow-Origin` header needs to be set by the remote server
 128 when serving the VTT file.  See
 129 [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin)
 130 for more information about setting this header.
 131
 132 ## Example ##
 133
 134     {
 135       "title": "Test Video",
 136       "duration": 10,
 137       "live": false,
 138       "thumbnail": "https://example.com/thumb.jpg",
 139       "sources": [
 140         {
 141           "url": "https://example.com/video.mp4",
 142           "contentType": "video/mp4",
 143           "quality": 1080,
 144           "bitrate": 5000
 145         }
 146       ],
 147       "textTracks": [
 148         {
 149           "url": "https://example.com/subtitles.vtt",
 150           "contentType": "text/vtt",
 151           "name": "English Subtitles"
 152         }
 153       ]
 154     }
 155
 156 ## Permissions ##
 157
 158 The permission node to allow users to add custom content is the same as the
 159 permission node for the existing raw file support.  Custom content is considered
 160 as an extension of the existing feature.
 161
 162 ## Unsupported/Undefined Behavior ##
 163
 164 The behavior under any the following circumstances is not defined by this
 165 specification, and any technical support in these cases is voided.  This list is
 166 non-exhaustive.
 167
 168   * Source URLs or text track URLs are hosted on a third-party website that does
 169     not have knowledge of its content being played on CyTube.
 170   * The webserver hosting the source or text track URLs serves a different MIME
 171     type than the one specified in the manifest.
 172   * The webserver hosting the source or text track URLs serves a file that does
 173     not match the MIME type specified in the `Content-Type` HTTP header returned
 174     to the browser.
 175   * The manifest includes source URLs or text track URLs with expiration times,
 176     session IDs, etc. in the URL querystring.