| 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. |