This document provides instructions for working with the draft AV1 Bitstream & Decoding Process Specification.
The specification document is built from plaintext section and subsection Markdown files (more specifically, kramdown files) using the Jekyll static site generator tool.
Contributors will want to preview their edits locally before submitting patches for review. Doing so requires a sane Ruby and rubygems environment. We use rbenv and bundler to “groom” the project environment and avoid conflicts.
Note that all commands are to be run as an ordinary, unprivileged user.
This project currently depends on Ruby v2.3.0. Because your distro may lack this version -- or installing it may conflict with your system's installed version -- first install rbenv, then install Ruby v2.3.0 within it (again, in userland).
# list all available versions: $ rbenv install -l 2.2.6 2.3.0-dev 2.3.0-preview1 2.3.0-preview2 2.3.0 # install a Ruby version: $ rbenv install 2.3.0
Gem dependencies are managed by bundler.
$ gem install bundler # Filesystem location where gems are installed $ gem env home # => ~/.rbenv/versions/<ruby-version>/lib/ruby/gems/...
git clone https://aomedia.googlesource.com/av1-spec cd av1-spec
In the directory of your local clone, do:
rbenv local 2.3.0
Regardless of any other Rubies installed on your system, the project environment will now use v2.3.0 and gems appropriate for it.
In the directory of your local clone, run
Bundler will set dependencies and install needed gems as listed in
Note that you may need Ruby development headers installed on your system for some gems to compile successfully.
bundle exec jekyll serve
This will build the document and launch a local webserver at
http://127.0.0.1:4000/av1-spec/ (by default). Jekyll will also watch the the filesystem for changes and rebuild the document as needed. Reload your browser tab to view any changes you've made.
These steps are not critically necessary for working on the document. Rather, they apply cosmetic changes to the HTML output on a postproc basis.
The specification document requires a bit of arbitrary text manipulation that can't be done with Jekyll alone. To automate these needs we turn to GruntJS, a Node-based task runner. The following assumes you have already installed NodeJS and npm, the Node package manager.
## Update npm globally npm update -g npm ## Install grunt globally npm install -g grunt-cli ## Go the the project directory cd av1-spec ## Install the project's Node dependencies ## (uses package.json and Gruntfile) npm install
To transform the Jekyll-generated HTML file (
grunt in the project directory. This will apply the text transformations described in Grunt's
replace task (see
Gruntfile) and will write the output to
Currently this method is used to “bold” the names of syntax elements within syntax tables. For example, the tokenized string
@@syntax_element will be replaced with
<b>syntax_element</b>. This reduces the clutter of HTML elements within the source text files.
The project is hosted on Git at Google, which uses the Gerrit code review tool. Prospective contributors must have a Google account and a working knowledge of Gerrit. In particular, contributors must install the Gerrit commit-msg script in their local repo for Gerrit to accept any patches they push to it for review.