This document provides instructions for working with the draft AV1 Bitstream & Decoding Process Specification.
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.
Ruby and rbenv
This project currently depends on Ruby v2.4.1. 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.4.1 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 2.4.1 # install a Ruby version: $ rbenv install 2.4.1
Depending on your distro and environment, you may have trouble building a particular Ruby version. The rbenv project site maintains a wiki page with troubleshooting help.
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/...
Clone the Repo
git clone firstname.lastname@example.org:AOMediaCodec/av1-spec.git cd av1-spec
Set Local Ruby Version (rbenv)
In the directory of your local clone, do:
rbenv local 2.4.1
Regardless of any other Rubies installed on your system, the project environment will now use v2.3.0 and gems appropriate for it.
Install Gem Dependencies with Bundler
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.
Build and Preview Locally with Jekyll
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.
Notes on NPM and Grunt
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 (
the project directory. This will apply the text transformations described in
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
<b>syntax_element</b>. This reduces the clutter of HTML elements
within the source text files.