This document, once published, will define the AV1 video codec bitstream format and decoding process.
The document is built from plaintext section and subsection Markdown files (more specifically, kramdown files) using the Jekyll static site building tool. GitHub supports Jekyll natively.
Contributors will want to preview their edits locally before submitting pull requests. 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/...
First, use the Fork button on the repo's homepage to fork a copy to your GitHub account.
Second, clone your fork locally:
git clone email@example.com:<username>/av1-bitstream.git cd av1-bitstream
Note that we strongly suggest using SSH with GitHub, not HTTPS.
Third, add a Git remote
upstream that points to webmproject/av1-bitstream:
git remote add upstream firstname.lastname@example.org:webmproject/av1-bitstream.git
Your local repo with then have two remotes,
upstream pointing at the authoritative GitHub repo and
origin pointing at your GitHub fork.
$ git remote origin upstream $ git remote show origin * remote origin Fetch URL: email@example.com:<username>/av1-bitstream.git Push URL: firstname.lastname@example.org:<username>/av1-bitstream.git HEAD branch: master Remote branch: master tracked Local branch configured for 'git pull': master merges with remote master Local ref configured for 'git push': master pushes to master (up to date) $ git remote show upstream * remote upstream Fetch URL: email@example.com:webmproject/av1-bitstream.git Push URL: firstname.lastname@example.org:webmproject/av1-bitstream.git HEAD branch: master Remote branch: master tracked Local ref configured for 'git push': master pushes to master (up to date)
See this page for a longer discussion of managing remotes and general GitHub workflow.
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 --watch
This will build the document and launch a local webserver at
http://127.0.0.1:4000/av1-bitstream/ (by default). Jekyll will also watch the the filesystem for changes and rebuild the document as needed.
Always do your work in a local branch.
git co -b my-branch-name ## work ## git add <filenames or -A for all> git ci -m "Reasonably clear commit message"
Push your branch to
origin (your GitHub fork):
git push origin my-branch-name
Next, visit the
upstream homepage. GitHub will be aware of your recently pushed branch, and offer an in-page widget for submitting a pull request for the project maintainers to consider.
Once your pull request is merged into upstream's master branch, you may synchronize your clone (and remote
origin) as follows:
git co master git fetch upstream git merge upstream/master git push origin
Your old working branch is no longer needed, so do some housekeeping:
git br -d my-branch-name