Readme update

CHANGELOG.md

@@ -5,6 +5,8 @@
 ### v3.2.0 
 
 * Zoom and panning
+* Reorganized popup
+* Various bug fixes
 
 ### v3.1.1 (Chrome-only)
 

README.md

@@ -10,7 +10,7 @@ If you own an ultrawide monitor, you have probably noticed that sometimes videos
 
 * Unclear how extension handles sites with more than one video per page.
 * Autodetection is only correct 95% of the time, most of the time.
-* That new stretching mode wasn't thoroughly tested yet. Issues may be present.
+* That new stretching mode wasn't thoroughly tested yet. Issues may be present. (Same with zoom)
 * Enabling extension everywhere (as opposed to whitelisted sites) could break some websites. 
 
 ### Features
@@ -20,7 +20,7 @@ If you own an ultrawide monitor, you have probably noticed that sometimes videos
 * **Automatic aspect ratio detection** (can be enabled/disabled entirely or on a per-site basis, separately of the extension. Autodetection in action: [youtube](https://www.youtube.com/watch?v=j2xn1WpbtCQ))
 * **Supports Youtube theater mode**
 * **[EXPERIMENTAL!]** Stretch video to fit the screen (4 different approaches)
-* **[EXPERIMENTAL!] (3.2.0) custom zooming and panning**
+* **[EXPERIMENTAL!]** custom zooming and panning
 
 
 ### Officially supported sites
@@ -30,7 +30,7 @@ If you own an ultrawide monitor, you have probably noticed that sometimes videos
 
 ### Other sites
 
-I am not actively testing extension on other sites. You can try your luck and enable extension for any unsupported site you stumble across via extension popup (in the _Setting for this site_ menu), but I make no guarantees it will work everywhere.
+I am not actively testing extension on other sites. You can try your luck and enable extension for any unsupported site you stumble across via extension popup, but I make no guarantees it will work everywhere.
 
 ### Installing this extension
 
@@ -67,66 +67,62 @@ 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.
+* 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. However, sometimes aspect ratio changes will still trigger too eagerly.
-* 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 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). Video demonstration of autodetection can be found [here](https://www.youtube.com/watch?v=j2xn1WpbtCQ). 
+By default, automatic detection will run on every site this extension is enabled for. It does what it says on the tin: it attempts to detect aspect ratio of the video by periodically looking at a video frame.
 
-![Demo](img-demo/ui/popup/autoar.png)
+Some caveats apply:
+* autodetection is very easy in 99% of cases and very tricky in the 1%. Sometimes, autodetection will be too eager. Sometimes it won't be eager enough.
+* Some sites use DRM. DRM measures are designed specifically to prevent scripts from looking at video frames. Since that's exactly what this extension uses to determine aspect ratio of a video, **autodetection is not possible on sites that use DRM** (Netflix and the likes). Firefox is slight exception to this.
+* Firefox offers an API that can be used to take screenshots of the page. Turns out that you can use this API to work around the above limitation. Usage of this API has its own limitations. Due to those limitations, automatic detection on DRM-protected sites in Firefox keeps a thin black bar at the top and the bottom of the video.
 
-Top row of buttons determines the default mode of operation for automatic detection.
+Autodetection can be enabled or disabled globally, per site or per video.
 
-* **Always** — works on all sites this extension is enabled on, unless autodetection is specifically disabled for that site. [Default]
+### Popup
-* **Only on whitelisted sites** — autodetection only works on sites, on which autodetection is enabled.
-* **Never** — turn aspect ratio detection off
 
-Bottom row of buttons detemrmines the mode of operation for automatic detection for current site. 
+Most of the extension settings can be accessed and modified via the popup. If extension is enabled for the site you're currently on, the popup will display options for the video you're currently watching.
 
-* **Blacklist** — don't ever attempt automatic aspect ratio detection on this site
+![Demo](img-demo/ui/popup/popup_video_settings.png)
-* **Default** — follow global rules. If default mode of operation is 'always', automatic aspect ratio detection will work on this site, otherwise it won't.
-* **Whitelist** — perform automatic detection on given site, unless automatic aspec ratio detection is turned off 
 
-'Check every ___ ms box determines how often the extension will check for aspect ratio changes. Longer periods will result in this extension using less system resources, but extension will be slow to detect changes. Short periods will increase the use of system resources. Periods shorter than 500 ms will significantly increase RAM and CPU usage. **Time periods shorter than 100 _will_ result in _massive_ RAM usage due to technical limitations of Javascript and canvas API. To give a solid example, setting this value to '30' ms can result in multiple _gigabytes_ of RAM used (personal record is 7 GB, but the number is very dependant on multiple factors, such as what browser are you using and how long the browser has been running. In Firefox 56, the amount of RAM used was correlated with amount of time the browser has been running).
-
-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.
+Extension can crop videos to the desired aspect ratio. Options offered by the extension are (keyboard shortcuts in **bold**):
-Special buttons in cropping mode:
 
-* **Reset** undoes any aspect ratio changes either you or autodetection made to the video.
+* Automatic — **A**
-* **Auto detect** starts autodetection (even on blacklisted sites)
+* Reset (default) — **R**
-* **Custom** applies crop to custom aspect ratio
+* 21:9 (2.39:1) — **D**
+* 18:9 (2:1) — **X**
+* 16:9 (1.77) — **S**
+* Custom — **Q**
 
-Note that manually adjusting aspect ratio _disables_ autodetection for current video. Manual adjustments are temporary and should last for only one video.
+In addition to that, you can crop video to fit width (**W**) or height (**E**).
 
-**Custom aspect ratio** is a box in which you enter your custom aspect ratio. It can be in any of the following formats:
+**Note:** manually adjusting aspect ratio _disables_ autodetection for current video. Manual adjustments are temporary and should last for only one video.
+
+You can set custom aspect ratio by clicking 'set custom aspect ratio' link under the buttons, changing the value in the box and clicking 'save'. Aspect ratio 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.
+![Demo](img-demo/ui/popup/crop_custom.png)
 
---
+### Zoom
-¹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
+Keys 'Z' and 'U' manually zoom the video. You can use those to zoom farther than merely adjusting aspect ratio would. At high magnification, you can pan the video by moving mouse over it. Panning is off by default and can be activated by holding 'shift' or toggled by pressing 'P' key.
+
+You can also zoom video by using the slider in the popup:
+
+![Demo](img-demo/ui/popup/zoom.png)
+
+### Align video
+
+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.
 
 ### Stretching videos
 
@@ -134,15 +130,55 @@ If you watch 16:9 videos in full screen on a 21:9 monitor, there's obviously goi
 
 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:
+Ultrawidify 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).
 
+## Global and per-site default settings
+
+You can change default settings for extension or site you're currently on by visiting 'Extension settings' and 'Site settings' tabs in the popup. Per-site settings override extension defaults, video settings override both. Both tabs also have the same options:
+
+![Demo](img-demo/ui/popup/extension_settings.png)
+
+Quick rundown of the options:
+
+* **Enable this extension** (Extension settings)
+
+Whether the extension is enabled. Options:
+
+`Always` — allow this extension to run on every site (unless the site is blacklisted)
+`On whitelisted sites` — allow this extension to run only on sites you manually enabled
+`Never` — this extension won't work. At all. 
+
+* **Enable autodetection** (Extension settings)
+
+Whether extension should automatically detect aspect ratio. Uses same options as _Enable this extension_ options.
+
+* **Enable this extension** (Site settings)
+
+Whether the extension is enabled on current site. Options:
+
+`Whitelist` — allow this extension to run on current site.
+`Default` — follow global settings (allow if global option is set to 'always', don't allow if global option is set to any of the other two)
+`Blacklist` — never allow extension to run on current site.
+
+* **Enable autodetection** (Site settings)
+
+Whether extension should automatically detect aspect ratio on current site. Uses same options as _Enable this extension_ options.
+
+* **Default stretching mode**
+
+How, if at all, should extension stretch the video by default. 
+
+* **Video alignment**
+
+How to align the video by default.
+
 ## Keyboard shortcuts
 
-They still aren't rebindable.
+The keyboard shortcuts have already been listed, but let's list them all again in the same, handy place.
 
 ### Default keyboard shortcuts
 
@@ -157,13 +193,38 @@ They still aren't rebindable.
 `x`   - force 18:9  
 `q`   - force custom aspect ratio
 
+`z`   - zoom
+`u`   - unzoom
+`p`   - toggle video panning
+`shift`- pan video (while holding)
+
+### Rebinding keyboard shortcuts
+
+is currently not possible. Settings page for this extension has been disabled sometime with 2.0 release (because it [broke](https://github.com/xternal7/ultrawidify/issues/16)), and fixing the setting page has been very low priority as I've had more important issues to work on. 
+
+However, I do plan on implementing this feature. Hopefully by the end of the year, but given how consistently I've been breaking self-imposed deadlines and goals for this extension don't hold your breath. After all, [Hofstadter's a bitch](https://en.wikipedia.org/wiki/Hofstadter%27s_law).
+
+## Known issues
+
+* Netflix autodetection not working in Chrome, wontfix as issue is fundamentally unfixable.
+* Everything reported in [issues](https://github.com/xternal7/ultrawidify/issues)
+
+## Plans for the future
+
+1. Handle porting of extension settings between versions. 
+2. ~~Reintroduce gradual zoom on z and u and provide a way to 'scroll' the zoomed in video up/down left/right.~~ (v3.2.0)
+3. reintroduce settings page (rebindable keys, blacklist/whitelist management, some settings for automatic aspect ratio detection)
+4. site-specific options for sites that require additional CSS classes or other hacks
+5. 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~~no it wont lol
+6. Improvements to automatic aspect ratio detection
+
 ## Installing
 
 ### Permanent install / stable
 
-[Latest stable for Firefox — download from AMO](https://addons.mozilla.org/en/firefox/addon/ultrawidify/) (v3.0.0)
+[Latest stable for Firefox — download from AMO](https://addons.mozilla.org/en/firefox/addon/ultrawidify/)
 
-[Latest stafle for Chrome — download from Chrome store](https://chrome.google.com/webstore/detail/ultrawidify/dndehlekllfkaijdlokmmicgnlanfjbi) (v2.2.5)
+[Latest stafle for Chrome — download from Chrome store](https://chrome.google.com/webstore/detail/ultrawidify/dndehlekllfkaijdlokmmicgnlanfjbi)
 
 ### Installing the current, github version
 
@@ -173,20 +234,6 @@ They still aren't rebindable.
 4. Add temporary addon
 5. Browse to wherever you saved it and select manifest.json
 
-## Known issues
-
-* Netflix autodetection not working in Chrome, wontfix as issue is fundamentally unfixable. (Although a different kind of workaround could probably be put in place, but don't count on it)
-* Everything reported in [issues](https://github.com/xternal7/ultrawidify/issues)
-
-## Plans for the future
-
-1. Handle porting of extension settings between versions. 
-2. Reintroduce gradual zoom on z and u and provide a way to 'scroll' the zoomed in video up/down left/right.
-3. reintroduce settings page (rebindable keys, blacklist/whitelist management, some settings for automatic aspect ratio detection)
-4. site-specific options for sites that require additional CSS classes or other hacks
-5. 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
-6. Improvements to automatic aspect ratio detection
-
 ## Changelog
 
 see changelog.md