Updates to documentation

README.md

@@ -1,89 +1,118 @@
 # Av1an
 
-![av1an fully utilizing a 96-core CPU for video encoding](https://github.com/master-of-zen/Av1an/assets/46526140/15f68b63-7be5-45e8-bf48-ae7eb2fc4bb6)
+<img align="right" width=40% src="https://github.com/master-of-zen/Av1an/assets/46526140/15f68b63-7be5-45e8-bf48-ae7eb2fc4bb6" alt="av1an fully utilizing a 96-core CPU for video encoding">
+
+
+[![Discord server](https://discordapp.com/api/guilds/696849974230515794/embed.png)](https://discord.gg/Ar8MvJh) [![CI tests](https://github.com/master-of-zen/Av1an/actions/workflows/tests.yml/badge.svg)](https://github.com/master-of-zen/Av1an/actions/workflows/tests.yml) [![](https://img.shields.io/crates/v/av1an.svg)](https://crates.io/crates/av1an) [![](https://tokei.rs/b1/github/master-of-zen/Av1an?category=code)](https://github.com/master-of-zen/Av1an)
+
+Av1an is a video encoding framework which aims to increase your encoding speed and improve CPU-utilization by running multiple encoder processes in parallel. Additional features include Scene-detection, VMAF-score plotting & quality-targeting.
 
-[![Discord server](https://discordapp.com/api/guilds/696849974230515794/embed.png)](https://discord.gg/Ar8MvJh)
-[![CI tests](https://github.com/master-of-zen/Av1an/actions/workflows/tests.yml/badge.svg)](https://github.com/master-of-zen/Av1an/actions/workflows/tests.yml)
-[![](https://img.shields.io/crates/v/av1an.svg)](https://crates.io/crates/av1an)
-[![](https://tokei.rs/b1/github/master-of-zen/Av1an?category=code)](https://github.com/master-of-zen/Av1an)
 
 <a href="https://www.buymeacoffee.com/master_of_zen" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
 
-Av1an is a video encoding framework. It can increase your encoding speed and improve cpu utilization by running multiple encoder processes in parallel. Target quality, VMAF plotting, and more, available to take advantage for video encoding.
 
-For help with av1an, please reach out to us on [Discord](https://discord.gg/Ar8MvJh) or file a GitHub issue.
+> [!TIP]
+> Check out the [**Av1an Book**](https://master-of-zen.github.io/Av1an/) for more details on usage.
+
+For help with av1an, feel free to reach out to us on [Discord](https://discord.gg/Ar8MvJh) or file an [issue on GitHub](https://github.com/master-of-zen/Av1an/issues).
 
-# [**Av1an Book**](https://master-of-zen.github.io/Av1an/)
 
 ## Features
 
 - Hyper-scalable video encoding
-- [Target Quality mode](https://master-of-zen.github.io/Av1an/Features/TargetQuality.html), using VMAF control encoders rate control to achieve the desired video quality
+- [Target Quality mode](https://master-of-zen.github.io/Av1an/Features/target_quality.html), using VMAF control encoders rate control to achieve the desired video quality
 - [VapourSynth](http://www.vapoursynth.com) script support
-- Cancel and resume encoding without loss of progress
+- Cancel and resume encoding without loss of progress (see `--keep` & `--resume`)
 - Minimal and clean CLI
 - Docker images available
 - Cross-platform application written in Rust
 
 ## Usage
 
-For complete reference, refer to [CLI](/docs/CLI.md)
-or run `av1an --help`
+Av1an offers a comprehensive command-line interface for streamlined operation. For complete reference of it's offerings, refer to the [CLI Reference](https://master-of-zen.github.io/Av1an/Cli/general.html) in the docs or run `av1an --help`.
 
-Encode a video file with the default parameters:
+### Examples
 
-```sh
-av1an -i input.mkv
-```
+Encode a video file with the default parameters (uses `aom` for encoding):
 
-Or use a VapourSynth script and custom parameters:
+```bash
+$ av1an -i input.mkv
+```
 
-```sh
-av1an -i input.vpy -v "--cpu-used=3 --end-usage=q --cq-level=30 --threads=8" -w 10 --target-quality 95 -a "-c:a libopus -ac 2 -b:a 192k" -l my_log -o output.mkv
+Encode a video file and all it's accompanying audio-tracks to 2-channel 192kbps opus:
+```bash
+$ av1an -i input.mkv -a "-c:a libopus -ac 2 -b:a 192k"
 ```
 
-## Supported encoders
+Encode a video file with cinematic cropping using ffmpeg parameters:
+```bash
+$ av1an -i input.mkv -f "-vf crop=1920:800"
+```
 
-At least one encoder is required to use Av1an. The following encoders are supported:
+Encode from a VapourSynth script with custom video encoder settings, 10 workers, [target quality](https://master-of-zen.github.io/Av1an/Features/target_quality.html), audio encoding options, logging and custom output file-name:
 
-- [aomenc](https://aomedia.googlesource.com/aom/) (AV1)
-- [SvtAv1EncApp](https://gitlab.com/AOMediaCodec/SVT-AV1) (AV1)
-- [rav1e](https://github.com/xiph/rav1e) (AV1)
-- [vpxenc](https://chromium.googlesource.com/webm/libvpx/) (VP8 and VP9)
-- [x264](https://www.videolan.org/developers/x264.html) (H.264/AVC)
-- [x265](https://www.videolan.org/developers/x265.html) (H.265/HEVC)
+```bash
+$ av1an -i input.vpy -v "--cpu-used=3 --end-usage=q --cq-level=30 --threads=8" -w 10 --target-quality 95 -a "-c:a libopus -ac 2 -b:a 192k" -l my_log -o output.mkv
+```
 
-Note that Av1an requires the executable encoder. If you use a package manager to install encoders, check that the installation includes an executable encoder (e.g. vpxenc, SvtAv1EncApp) from the list above. Just installing the library (e.g. libvpx, libSvtAv1Enc) is not enough.
+## Supported Video encoders
+Av1an is able to use a variety of external video-encoders to encode your chosen video. At least one of these encoders must be installed in order to use Av1an. The following are supported:
+| Codec | Encoder | `-e` option | Default encoder Parameters (`-v`) | Source |
+| -:| - | - | - |:-:|
+| AV1 | aomenc | `aom` | `--threads=8 --cpu-used=6 --end-usage=q --cq-level=30 --tile-columns=1 --tile-rows=0` |[Google Source](https://aomedia.googlesource.com/aom/) |
+| AV1 | rav1e | `rav1e` | `--speed 6 --quantizer 100 --no-scene-detection --tiles 2` | [GitHub](https://github.com/xiph/rav1e) |
+| AV1 | SvtAv1EncApp | `svt-av1` | `--preset 4 --keyint 240 --rc 0 --crf 25 --tile-columns 1 --tile-rows 0` | [GitLab](https://gitlab.com/AOMediaCodec/SVT-AV1) |
+| VP8 & VP9 | vpxenc | `vpx` | `--codec=vp9 -b 10 --profile=2 --threads=4 --cpu-used=2 --end-usage=q --cq-level=30 --row-mt=1 --auto-alt-ref=6 --tile-columns=1 --tile-rows=0` | [Google Source](https://chromium.googlesource.com/webm/libvpx/) |
+| H.264/AVC | x264 | `x264` | `--preset slow --crf 25` | [VideoLAN](https://www.videolan.org/developers/x264.html) |
+| H.256/HEVC | x265 | `x265` | `-p slow --crf 25 -D 10 --level-idc 5.0` | [VideoLAN](https://www.videolan.org/developers/x265.html) |
+
+> [!IMPORTANT]
+> 
+> Note that Av1an depends on external encoder executables as opposed to libraries.
+>
+> If you use a package manager to install your encoders, check that the packages you've installed include the encoder executables (e.g. `vpxenc`, `SvtAv1EncApp`) from the list above, and not simply their respective libraries (e.g. `libvpx`, `libSvtAv1Enc`).
+
+## Supported Audio encoders
+Av1an relies entirely on your system's `ffmpeg` binary for audio encoding.
 
 ## Installation
 
-av1an can be installed from package managers, cargo.io, or compliled manually. There are also pre-built [Docker images](/site/src/docker.md) which include all dependencies and are frequently updated.
+av1an can be installed from package managers, cargo.io, or compliled manually. There are also pre-built [Docker images](/site/src/DOCKER.md) available that include all dependencies and are frequently updated.
 
 For Windows users, prebuilt binaries are also included in every [release](https://github.com/master-of-zen/Av1an/releases), and a [nightly build](https://github.com/master-of-zen/Av1an/releases/tag/latest) of the current `master` branch is also available.
 
 ### Package managers
 
-Arch Linux & Manjaro: `pacman -S av1an`
-Cargo: `cargo install av1an`
+Av1an is available officially for download from the [Arch Linux](https://archlinux.org/packages/extra/x86_64/av1an/) & [Manjaro](https://packages.manjaro.org/?query=av1an) package repositories
+```bash
+$ pacman -S av1an
+```
+
+In addition, Av1an is also available as a Rust Package, and can therefore easily be compiled from source and installed using Cargo:
+```bash
+cargo install av1an
+```
+
+See [Compiling](https://master-of-zen.github.io/Av1an/compiling.html) for details on building Av1an from source.
 
-### Manual installation
+### Dependencies
 
-Prerequisites:
+Requirements:
 
 - [FFmpeg](https://ffmpeg.org/download.html)
 - [VapourSynth](https://github.com/vapoursynth/vapoursynth/releases)
-- At least one [encoder](#supported-encoders)
+- At least one [supported encoder](#supported-encoders)
 
 Optional:
 
 - [L-SMASH](https://github.com/AkarinVS/L-SMASH-Works) VapourSynth plugin for better chunking (recommended)
-- [DGDecNV](https://www.rationalqm.us/dgdecnv/dgdecnv.html) Vapoursynth plugin for very fast and accurate chunking, `dgindexnv` executable needs to be present in system path and an NVIDIA GPU with CUVID 
+- [DGDecNV](https://www.rationalqm.us/dgdecnv/dgdecnv.html) Vapoursynth plugin for very fast and accurate chunking, `dgindexnv` executable needs to be present in system path and an Nvidia GPU with CUVID
 - [ffms2](https://github.com/FFMS/ffms2) VapourSynth plugin for better chunking
 - [bestsource](https://github.com/vapoursynth/bestsource) Vapoursynth plugin for slow but accurate chunking
 - [mkvmerge](https://mkvtoolnix.download/) to use mkvmerge instead of FFmpeg for file concatenation
-- [VMAF](https://github.com/Netflix/vmaf) to calculate VMAF scores and to use [target quality mode](docs/TargetQuality.md)
+- [VMAF](https://github.com/Netflix/vmaf) to calculate VMAF scores and to use [target quality mode](docs/target_quality.md)
 
-### VapourSynth plugins on Windows
+#### VapourSynth plugins on Windows
 
 If you want to install the L-SMASH or ffms2 plugins and are on Windows, then you have [two installation options](http://vapoursynth.com/doc/installation.html#plugins-and-scripts). The easiest way is using the included plugin script:
 

av1an/src/main.rs

@@ -384,7 +384,7 @@ pub struct CliOpts {
   /// Photon noise tables are more visually pleasing than the film grain generated by aomenc,
   /// and provide a consistent level of grain regardless of the level of grain in the source.
   /// Strength values correlate to ISO values, e.g. 1 = ISO 100, and 64 = ISO 6400. This
-  /// option currently only supports aomenc and rav1e.
+  /// option is only implemented in select AV1 encoders, including aomenc, rav1e and svt-av1.
   ///
   /// An encoder's grain synthesis will still work without using this option, by specifying the
   /// correct parameter to the encoder. However, the two should not be used together,

site/src/Cli/encoding.md

@@ -118,7 +118,7 @@
 		Photon noise tables are more visually pleasing than the film grain generated by aomenc,
 		and provide a consistent level of grain regardless of the level of grain in the source.
 		Strength values correlate to ISO values, e.g. 1 = ISO 100, and 64 = ISO 6400. This
-		option currently only supports aomenc and rav1e.
+		option is only implemented in select AV1 encoders, including aomenc, rav1e and svt-av1
 
 		An encoder's grain synthesis will still work without using this option, by specifying
 		the correct parameter to the encoder. However, the two should not be used together, and

site/src/Features/target_quality.md

@@ -0,0 +1,63 @@
+# Target Quality
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+2. [Prerequisites](#prerequisites)
+3. [Parameters](#parameters)
+4. [Usage examples](#usage-examples)
+5. [Considerations when Cropping](#considerations-when-cropping)
+
+## Overview
+
+Av1an's Target Quality feature has a really simple goal; instead of having the user guess what the appropriate CQ/CRF value is to achieve their desired video quality, we simply set a VMAF score 'target' that we wish to achieve and let av1an automatically determine the appropriate CRF/CQ values per segment through testing. This approach offers a multitude of benefits:
+
+- It ensures a better level of visual consistency than regular rate controls.
+- It allocates enough bitrate to complex segments to match target quality, while similarly saving bitrate by not overspending on simpler scenes.
+- Unlike CRF, av1an's Target Quality feature a unified scale/interface for setting encoding quality across all encoders.
+
+However, using Target Quality also greatly increases total-encoding time, as each segement will be re-tested until the the appropriate CRF/CQ value is found. The time that's usually taken to manually determine these values is instead simply automated and standarized.
+
+## Prerequisites
+
+ - A build of `ffmpeg` compiled with `libvmaf` (included by default configuration since 2020)
+ - Pre-installed or or otherwise manually selected VMAF models
+   - The default model used by ffmpeg is `/usr/share/model/vmaf_v0.6.1.pkl`
+   - Windows-user are likely to have to manually specify their VMAF-model. See [this](https://github.com/Netflix/vmaf/blob/master/resource/doc/ffmpeg.md#note-about-the-model-path-on-windows) for using Target Quality / VMAF on Windows.
+ - An encoder with Constant Quality (CQ) / Constant Rate Control (CRF) support (e.g. `--crf 30`, `--cq-level=30`). These values will then be tweaked for each scene/segment until the desired score is achieved.
+
+## Parameters
+
+- `--target-quality <float>` - Enables target quality with default settings for your encoder. Targets the `<float>` VMAF score (0-100, higher = better)
+
+- `--probes <int>` - Overrides maximum amount of probes to make for each segment (Default: `4`)
+
+- `--min_q <int> --max_q <int>` - Overrides default CRF/CQ boundaries for search
+
+- `--vmaf-res <resolution>` - Overrides default VMAF calculation resolution for video (Default: `1920x1080`)
+
+## Usage examples
+
+Run av1an with default settings (aomenc), targetting a VMAF-score of 90:
+```bash
+$ av1an -i file --target-quality 90
+```
+
+Target a VMAF score of 95 using a custom VMAF-model and probe-count:
+```bash
+av1an -i file --target-quality 95 --vmaf_path "vmaf_v.0.6.3.pkl" --probes 6
+```
+
+## Considerations when Cropping
+
+When cropping video during Av1an's encoding process using ffmpeg filters, one should additionally pass these filters to the VMAF process, as well as the target-resolution: 
+
+```bash
+$ av1an -i input.mkv --ffmpeg "-vf crop=3840:1900:0:0" --vmaf-filter "crop=3840:1900:0:0" --vmaf-res "3840x1900" --target-quality 90
+```
+
+If cropping is performed through a VaporSynth script, the user need only set `--vmaf-res` to the appropriate output resolution:
+
+```bash
+$ av1an -i 4k_crop.vpy --vmaf-res "3840x1600" --target-quality 90
+```

site/src/SUMMARY.md

@@ -1,6 +1,5 @@
 # Av1an
-[av1an](./av1an.md)
-
+[Av1an](./av1an.md)
 
 
 # CLI Reference
@@ -11,21 +10,20 @@
  - [VMAF](Cli/vmaf.md)
  - [Target Quality](Cli/target_quality.md)
 
-# Features Documentation
 
-- [Target Quality](./Features/TargetQuality.md)
+# Features Documentation
+- [Target Quality](./Features/target_quality.md)
 
-# Instalation
 
+# Installation
  - [Compiling](./compiling.md)
  - [Docker](./docker.md)
 
 
-
 # Encoders
-
 - [Aomenc](./Encoders/aomenc.md)
 - [SVT-AV1](./Encoders/svt-av1.md)
 - [Rav1e](./Encoders/rav1e.md)
 
-# Video encoding knowledge
+
+# Video encoding knowledge