Documentation improvement for the 1.0 release
In preparation for the 1.0 release (#1845 (closed)), it makes sense to clean up existing documentation and prepare some user-friendly guides to help people who use SVTAV1 for the first time to have a good experience. Some suggestions:
Organization
-
Document the goals of SVTAV1 that make it distinct from rav1e and aomenc, perhaps describe the target user and strenghts/weaknesses of each project -
Make top-level readme an index to all documents -
Move hardware requirements and build information to its own document -
Move input video formation information to a lower-level, technical, document -
Move standalone app usage to its own document -
Move legal and how-to-contribute information to its own document -
Increase clarity of github repo or delete, to avoid ambiguity. That repo shows up first in a web search and a casual user may not notice that it is a mirror. Looking at the small number of issues and the last tag being from 2020, one might conclude that the SVTAV1 project is dead or very unhealthy (I am aware of people who have done this). -
Is there a role for the wiki?
Parameter Documentation
-
Prepare an accessible discussion (a paragraph or two, including what it does, tradeoff information, whether it is considered mature, and likely use cases) for each of the most frequently used parameters -
Presets -
CRF -
Grain synth -
Fast decode -
Scene change detection (this needs to be clear, as users will likely expect it to be placing key frames at scene changes) -
GOP size -
Tune -
8 bit vs 10 bit (what is gained/lost when using 10 bit)
-
-
Document example/suggested usage in common use cases: -
With current ffmpeg, including the svtav1-params
usage -
Using an older version of ffmpeg, requiring piping to SvtAv1EncApp -
Standalone usage (may be taken from current top-level readme)
-
-
Look over each documented parameter in the user's guide and ensure that the description is complete, clear, and accurate. Where possible, recommendations can be made and notes about which parameters are considered experimental can be left. For example, the recommendation on GOP size is outdated. -
Document the features enabled with each preset, similar to what is done in x265. #1753 (closed)
New User Documentation
-
Write an easy-to-use getting-started guide with a section describing/discussing recommended settings for each common use case: -
Professional VOD (low presets, third-party scene detection/chunking, smaller GOP) -
End-user encodes of ripped movies, home videos, etc. (presets 4-6, larger GOP) -
Realtime (high presets)
-
Advice and Details Documentation
-
Threading concerns: -
How many cores can be efficiently used by each preset, how does performance scale? -
Quality tradeoffs with multicore usage and how to mitigate them, if desired -
Approaches to increasing threading performance
-
-
Performance graph/discussion versus other AV1 and non-AV1 encoders -
Discussion of which options give the best bang for compute buck -
Discussion of which options are most likely to increase quality/size efficiency -
Discussion of how optimal parameters change for high and low resolution videos -
Special considerations -
Suggestions for encoding animation -
HDR issues -
Multipass encoding, and what kind of gains to expect, if any -
VBR mode -
Tips for increasing decode performance
-
Marketing
-
Blog post -
PR document, to be sent to various tech media outlets -
Provide an improved/more detailed document to ffmpeg so SVTAV1 appears less like a footnote to libaom and more like its own project
I also suggest that the release of 1.0 be coordinated with an ffmpeg release that uses the updated svtav1 plugin, so documents can include information about which ffmpeg version is recommended for use.
I am happy to write or edit any of this, and to solicit input from end-users, but I will require more knowledgeable people to guide/check me on anything I write as I am not a developer.
Tagging @gnafuthegreat
Edited by Hassene Tmar