vpx_ios/README.VPXExample

README.VPXExample


Introduction
------------
VPXExample.app is an example application that supports playback of IVF and WebM
container files containing VP8 or VP9 bitstreams. In terms of a player
application it's about as simple as it gets:

- There is no audio playback. This is a video only player.
- There are no playback controls; you cannot pause, stop, fast forward, rewind
  or seek.


Prerequisites
-------------
To build VPXExample.app you must have the following installed:
- A recent version of Xcode (this project was built using Xcode v5.1).
- Apple iOS developer program membership.
- git
- yasm (required for libvpx)
  - Really. Don't attempt to use nasm. It most likely will not work.
  - The easiest way to obtain yasm is using a package manager like homebrew.
  - To build yasm:
    1. Clone it via git using the command:
         $ git clone git://github.com/yasm/yasm.git
       Or download a source archive from http://yasm.tortall.net/Download.html.
    2. Change into the yasm directory and run the following commands
       a. ./configure
       b. make
  - Using yasm:
    After building yasm, move the yasm binary to a directory in your path, or
    add the build directory to your path. Alternatively, you can run make with
    the install target, but you'll need to '$ sudo make install' it, or
    modify the default install location via updating DESTDIR, i.e.:
    $ make install DESTDIR=/some/writable/directory/
    - Note: /some/writable/directory will need to be in your PATH for libvpx
      to access yasm.


Getting Started
---------------
To begin with, you must clone the libvpx, libwebm, and webm-tools git
repositories.

To do so, open a terminal window, and enter the following commands:

$ git clone https://chromium.googlesource.com/webm/libvpx
$ git clone https://chromium.googlesource.com/webm/libwebm
$ git clone https://chromium.googlesource.com/webm/webm-tools

The next step is to build VPX.framework. This contains the include files and
the multi-target fat library required to build VPXExample.app for all targets.

Note: You can change the location of VPX.framework, but doing so will require
you to make changes to VPXExample.xcodeproj.

$ mkdir frameworks
$ cd frameworks
$ ../libvpx/build/make/iosbuild.sh

Notes:
- Run iosbuild.sh with the --help argument for additional command line options.
- On slower machines iosbuild.sh will take a very long time (it configures and
  builds libvpx for 5 target platforms).
- If iosbuild.sh fails, clean the directory you ran it from, and then rerun it
  with --show-build-output to see the actual error, i.e.:
  $ ../libvpx/build/make/iosbuild.sh --show-build-output
  Deeper diagnosis of problems can be had via preserving the build artifacts in
  addition to showing the output from their creation:
  $ ../libvpx/build/make/iosbuild.sh --show-build-output --preserve-build-output

Now WebM.framework must be built:

$ cd ../libwebm
$ ./iosbuild.sh --out-dir ../frameworks


Building VPXExample.app
-----------------------
Open VPXExample.xcodeproj in Xcode and build it. That's it. There is no step
two.

Notes:
- VPXExample includes two target schemes. Using the Debug scheme will result
  in severely degraded playback performance (the higher the input video
  resolution, the worse this will be).
- See vpx_example_common.h for instructions on toggling between local playback
  mode and using a remote server to download files for playback.


Playing files with VPXExample.app
---------------------------------
Whether built with only local playback mode support, or built with download
support, the application functions the same. When the application opens a
list view is displayed that contains files available for playback. The first
step is tapping a file.

When downloading support is built in, tapping a file will enable the download
button-- at this point the user must tap the download button, and then tap the
play button.

When built with local playback support, the user needs only to tap the play
button after tapping a file to play.

Once play has been tapped, the player will play the file. Once input frames
have been exhausted, the application returns to the file selection screen.


A guide to the source files in VPXExample.xcodeproj
---------------------------------------------------
The contents of the project groups (folders) Frameworks, Products, Supporting
Files, and VPXExampleTests and its Supporting Files subgroup are not documented
here. The same is true for iOS basics like AppDelegate.m, AppDelegate.h, and
main.m. VPXExample.xcodeproj uses the generated versions of these files as
produced by Xcode (excluding minor style related edits).

Everything in the libwebm group can be safely ignored. It's simply support code
for parsing WebM input. Libwebm source files have been included only because no
framework exists for libwebm.

Scripts/download_file.sh
A shell script that downloads the VP8 and VP9 versions of the Sintel trailer.

testdata/
  sintel_trailer_vp8.webm
  sintel_trailer_vp9.webm
The testdata group contains the input files built into VPXExample.app when
it's built in local playback only mode.

ivf_frame_parser.*
Implements IVF container parsing support via the class IvfFrameParser.

GlkVideoViewController.*
This is the renderer used to display video.

*.storyboard
These files contain the UI used in the application.

*.glsl
These are shaders that are responsible for converting video pixels from YUV to
RGB for display on the device and simulator screen.

video_buffer_pool.*
A thread safe buffer pool used to manage handling the movement of video frame
buffers from VpxPlayer to GlkVideoViewController.

ViewController.*
The main view controller for the application. This file supports the main UI.

vpx_example_common.h
Contains project wide settings and objects.

vpx_frame_parser.h
Defines the base interface class used by IvfFrameParser and WebmFrameParser.

vpx_player.*
The player class: VpxPlayer. Handles decoding of video via libvpx and
conversion of libvpx video buffer output from the YV12 format to the NV12
format.

webm_frame_parser.*
Implements WebM container parsing support via the class WebmFrameParser.