Finished readme rewrite

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v3.x
+
+### v3.0.0
+
+Pretty much rewrote extension in more object-oriented way and sorted out spaghetti a little. Site settings and keybinds have been merged with the rest of the extension settings. Rewrote messageing.
+
+User-facing changes:
+* Extension can be enabled/disabled globally or on per-site basis
+* Automatic aspect ratio can be turned off, either globally or on per-site basis
+* Stretching mode implemented
+* Popup has been pimped up to reflect those changes
+
+## v2.x
+
 ### v2.2.5 (AMO, Chrome)
 
 Added some anti-lag measures. This seems to be an issue affecting _only_ Chrome (and only then some installs), where canvas.drawImage() won't work properly for some reason.
@@ -103,6 +117,8 @@ The extension is being rewritten almost ground-up, around automatic aspect ratio
 * Zoom/unzoom options are gone
 * Can't customize keybinds yet
 
+# v1.x
+
 ### v1.3a1
 
 * Adding ability to add custom sites (in progress)

README.md

@@ -22,6 +22,8 @@ The technology has been here for a while, but plenty of people don't know how to
 
 ## Features
 
+(Note: this readme is being written ahead of time, so not all features described here are available in the store version of the extension. Firefox users can expect these features by, at latest, 1st of August. Chrome version may take a little longer.)
+
 TL;DR:
 
 * **Can be enabled or disabled on per-site basis**
@@ -29,11 +31,32 @@ TL;DR:
 * **Automatic aspect ratio detection** (can be enabled/disabled entirely or on a per-site basis, separately of the extension)
 * **[NEW in v3!] Stretch video to fit the screen** (4 different approaches)
 
-Most settings are self-explanatory.
+Most settings are self-explanatory, but we'll get into details anyway. 
+
+### Limitations:
+
+Before we go on to features, let's discuss limitations.
+
+* Currently, this extension is only tested on Youtube and Netflix. It should work on other sites as well, but you'll need to manually enable extension on other sites via the popup.
+* It's unclear how extension handles sites displaying multiple videos per site. Having multiple videos on the same page is a very tricky case that hasn't been given much thought.
+* Autodetection is a very hard problem to solve. Despite various improvements, it's still not 100% correct. In cases where aspect ratio is hard to determine, extension tends to err on the side of caution and tries to avoid changing aspect ratios.
+* This extension only works one way. It removes horizontal bars encoded in the video. It can't remove vertical bars encoded in the video. Especially not with autodetection.
+
+### Turn extension on and off, on per-site basis
+
+![Demo](img-demo/ui/popup/extsettings.png)
+
+This is pretty straight-forward. Under **enable this extension** section, selecting `always` will ensure the extension runs on every site you visit. That unfortunately breaks some sites, so by default Ultrawidify will only run on the sites you manually enabled (`On whitelisted sites`). `Never` means extension is disabled for all sites.
+
+In the **Options for this site** section, there's some sidenotes to be had:
+
+* `Blacklist` option ensures extension _never_ runs on the site you're currently on.
+* `Default` will do whatever the global option is: if 'enable this extension' is set to `always`, then extension will work on the given site. Otherwise, it won't.
+* `Whitelist` ensures extension always runs on the site you're currently on, unless extension is disabled via previous option.
 
 ### Automatic aspect ratio detection
 
-There's a few caveats to automatic aspect ratio detection. Namely, it only works on videos. If videos on the site are DRM-protected (e.g. Netflix), autodetection will not work unless you're using Firefox (and even then, no guarantees).
+There's a few caveats to automatic aspect ratio detection. Namely, it only works on HTML5 videos (but who doesn't use HTML5 these days?). If videos on the site are DRM-protected (e.g. Netflix), autodetection will not work unless you're using Firefox (and even then, no guarantees).
 
 
 ![Demo](img-demo/ui/popup/autoar.png)
@@ -54,10 +77,47 @@ Bottom row of buttons detemrmines the mode of operation for automatic detection
 
 By default, extension is set to check for aspect ratio changes once every 666 ms, as it turned out to be a decent compromise between RAM usage (generally well under 500 MB) and the time it takes extension to react to aspect ratio changes.
 
+### Cropping video
 
+![Demo](img-demo/ui/popup/crop.png)
 
+Buttons in the **cropping mode** set how the video will be cropped. For example: clicking 21:9¹ button will crop the video so it fits 21:9 area. It's not "proper" crop — this option won't magically cause letterbox to appear on 16:9 videos viewed on 16:9 player.
+Special buttons in cropping mode:
 
-## Default keyboard shortcuts
+* **Reset** undoes any aspect ratio changes either you or autodetection made to the video.
+* **Auto detect** starts autodetection (even on blacklisted sites)
+* **Custom** applies crop to custom aspect ratio
+
+Note that manually adjusting aspect ratio _disables_ autodetection for current video. Manual adjustments are temporary and should last for only one video.
+
+**Custom aspect ratio** is a box in which you enter your custom aspect ratio. It can be in any of the following formats:
+ * `width/height` (e.g. `16/9`, `21/9` - even `2560/1080`)
+ * `1:ratio` (e.g. `1:2.39`. You can omit the `1:` part, too — e.g. `2.39` is equivalent to `1:2.39`)
+'Save' button saves your custom aspect ratio. If you don't save changes, they'll be forgotten by the time you close the popup.
+
+If you watch 16:9 videos in full screen on a 21:9 monitor, there's obviously going to be black bars on either side of the video. The video will be centered, though. Some people don't want video to be centered in such situations, instead preferring having the video aligned to either side. **Video alignment** option does that.
+
+--
+¹21:9 is a marketing buzzword. It's an approximation of the following aspect ratios: `1:2.35` and `1:2.39` (as far as videos go). 21:9 option presumes 1:2.39. 
+²Vertically centered relative to the source video
+
+### Stretching videos
+
+![Demo](img-demo/ui/popup/stretch.png)
+
+When you watch a 16:9 content on a 21:9 monitor, you can deal with this issue in three ways: A) you don't, B) you crop or C) you stretch the 16:9 video to fit a 21:9 container. Obviously not everyone is a person of culture, some people prefer to choose the greater evil of the three: they prefer their videos stretched!
+
+As of v3.0, Ultrawidify does stretching. In fact, it offers you several ways of dealing with the issue:
+* **Never** — don't stretch at all
+* **Basic** — stretch the video to fit screen. Doesn't remove black bars encoded in the video. While this option is active, automatic aspect ratio detection is disabled.
+* **Hybrid** — this mode first crops away the black bars encoded in the video file. If the video doesn't fit your monitor after being cropped, the extension will proceed to stretch it in a smart way. Automatic detection remains active with this option.
+* **Thin borders** — this mode only applies stretching only when borders around video are thin (less than 5% of total width or height).
+
+## Keyboard shortcuts
+
+They still aren't rebindable.
+
+### Default keyboard shortcuts
 
 `w`   - fit to width  
 `e`   - fit to height  
@@ -68,12 +128,7 @@ By default, extension is set to check for aspect ratio changes once every 666 ms
 `s`   - force 16:9  
 `d`   - force 21:9  
 `x`   - force 18:9  
-
-### About aspect ratio autodetection
-
-Aspect ratio autodetection is achieved by performing some black magic every 30-something milliseconds. This currently can't be turned off by default. If this extension makes video sites lag too much, open an issue and include your hardware and OS — **this is important for me to know in order to better optimize autodetection.**.
-
-Manually triggering aspect ratio change will suspend automatic aspect ratio detection for until the page is refreshed, although it'll maybe unsuspend itself when video is changed. I don't know for certain.
+`q`   - force custom aspect ratio
 
 ## Installing
 
@@ -101,9 +156,9 @@ Manually triggering aspect ratio change will suspend automatic aspect ratio dete
 ~~1. Handle porting of extension settings between versions. (Some people had some issues where extension broke until reinstalled, and corrupted settings seemed to be the problem.)~~ seems to work for me?
 2. Reintroduce gradual zoom on z and u and provide a way to 'scroll' the zoomed in video up/down left/right
 reintroduce settings page (rebindable keys, blacklist/whitelist management, some settings for automatic aspect ratio detection)
-3. site-specific options for sites that require additional CSS classes or other hacks (see: vimeo, which is disabled)
+3. site-specific options for sites that require additional CSS classes or other hacks
 4. figure the best way to do GUI (injecting buttons into the player bar is not a good way. Been there, done that, each site has its own way and some appear to be impossible). Might get bumped to be released alongside #2
-5. Stretch mode, because some people are very salty and toxic about the fact that this extension is here to solve a problem that's different than the one they want. More salty than me rn.
+~~5. Stretch mode, because some people are very salty and toxic about the fact that this extension is here to solve a problem that's different than the one they want. More salty than me rn.~~ done 
 6. Improvements to automatic aspect ratio detection
 
 ## Changelog