Get Started with Intel® oneAPI Video Processing Library (Beta)

By Yan Liu,

Published:09/26/2019   Last Updated:10/23/2020

Get Started with Intel® oneAPI Video Processing Library (Beta)

The Intel® oneAPI Video Processing Library (oneVPL) provides a single video processing API for encode, decode, and video processing that works across a wide range of accelerators.

The oneVPL project contains sample code to help users get started. The sample code shows the basic usage of the API and can be used to try out oneVPL functionality.

Before You Begin

oneVPL should be installed as part of the Intel® oneAPI Base Toolkit (Base Kit). Refer to the Base Kit page for download and installation instructions.

System Requirements

Refer to the oneVPL System Requirements page.

Precompiled Tools

Precompiled tools are provided with oneVPL and can be used to test your installation and to try oneVPL functionality without having to build the code samples. The tools are located in the bin directory.

The following tools are available:

  • sample_decode: Legacy 1.x API-based command line tool to decode with optional output to a raw video file
  • sample_encode: Legacy 1.x API-based command line tool to encode with optional output to an encoded video stream file
  • sample_vpp: Legacy 1.x API-based command line tool to run frame processing (color conversion, resize, crop)
  • vpl-decode: Decode with optional output to a raw video file
  • vpl-encode: Encode with optional output to an encoded video stream file
  • vpl-vpp: Frame processing with optional output to a raw video file
  • vpl-inspect: Show capabilities of available implementations
  • vpl-decenc: Decode->encode pipeline with output to an encoded video stream file
  • vpl-decvpp: Decode->frameproc pipeline with output to a raw video file
  • vpl-vppenc: Frameproc->encode pipeline with output to an encoded video stream file

Before using the precompiled tools, make sure to set environment variables with the oneAPI setvars script.

In Windows*:

c:\Program Files(x86)\Intel\oneAPI\setvars.bat

In Linux*:

source /opt/intel/oneapi/setvars.sh

Precompiled Tool Command Line Options

To list command line options for the precompiled tools, enter the tool name at a command prompt. For example:

vpl-decode

Legacy tools cover 1.x API features only. Note that this reference implementation implements only a subset of command line parameters for the legacy tools. The newer oneVPL tools cover API features added in this reference implementation. Outputs should be similar to the legacy tools but command line options allow a choice of implementation paths.

Example output:

Memory model (default = -ext)
  -ext  = external memory (1.0 style)
  -int  = internal memory with MFXMemory_GetSurfaceForEncode

Dispatcher (default = -dsp1)
  -dsp1 = legacy dispatcher (API 1.x)
  -dsp2 = smart dispatcher (API 2.0)

Run Precompiled Tools

The following sample commands show how to use precompiled tools. Sample commands should be run from a writable directory using inputs downloaded from the oneVPL repository test content folder.

To show capabilities of available implementations, use the following command:

vpl-inspect

 

To decode an AV1 elementary stream (shipped in a simple IVF container) with vpl-decode, using the API 2.0 dispatcher, internal allocations, and simplified decode, use the following command:

sample_decode h265 -i cars_128x96.h265 -vpl

 

To encode an MJPEG elementary stream with vpl-encode using the API 2.0 dispatcher and internal allocations, use the following command:

sample_encode h265 -i cars_128x96.i420 -w 128 -h 96 -vpl -o out.h265 -vpl

 

To convert i420 raw frames to BGRA format, use the following command:

sample_vpp -scc nv12 -sw 128 -sh 96 -dcc rgb4 -dw 128 -dh 96 -lib vpl -i cars_128x96.i420 -o out.rgb

 

To resize an input from 128x96 to 640x480 with vpl-vpp, use the following command:

vpl-decode -i cars_128x96.ivf -if av1 -dsp2 -auto -o out.i420

 

To run a simple decode->encode pipeline with output to an encoded video stream, use the following command:

vpl-encode -i cars_128x96.i420 -if i420 -o out.mjpeg -of jpeg -sw 128 -sh 96

 

To run a simple decode->image process pipeline with output to a raw video file, use the following command:

vpl-vpp -i cars_128x96.i420 -if i420 -sw 128 -sh 96 -o out_640x480.i420 -of i420 -dw 640 -dh 480

 

To run a simple decode->encode pipeline with output to an encoded video stream, use the following command:

 vpl-decenc content/cars_128x96.h265

 

To run a simple decode->image process pipeline with output to a raw video file, use the following command:

 vpl-decvpp content/cars_128x96.h265

 

To run a simple image process->encode pipeline with output to an encoded video stream file, use the following command:

vpl-vppenc content/cars_128x96.i420 128 96

 

Troubleshooting tips:

  • Make sure to set environment variables with the oneAPI setvars script before using the precompiled tools.
  • Make sure you have write permissions to the location of the tool outputs.

Sample Code

Use the following sample projects to learn basic use of the API and to try out oneVPL functionality:

Sample Name Description
hello-decode Read an encoded video stream file and decode with optional output to a raw video file.
hello-encode Read a raw video file and encode with optional output to an encoded video stream file.
hello-vpp Read a raw video file (I420) and resize it with output to a new raw video file (I420).
dpcpp-blur Read a raw video file (I420) and color convert (RGB32), then use DPC++ kernel to blur the image, output to a new raw video file.

Detailed instructions can be found in the individual README files for each oneVPL sample.

Download Sample Code

The sample source code can be cloned or downloaded from the oneAPI-samples repository.

Build and Run Sample Code

  1. Go to the oneVPL sample directory at <oneAPI-samples root>/Libraries or <oneVPL install root>/examples.

  2. Visit each sample directory and follow the instructions in the README file.

Troubleshooting

To check the oneVPL installation, review the content in the appropriate oneVPL installation directory:

  • For root users in Linux: /opt/intel/inteloneapi/vpl/latest
  • For non-root users in Linux: $HOME/intel/inteloneapi/vpl/latest, or you can configure your own
  • For Windows: C:\Program Files (x86)\inteloneapi\vpl\latest

NOTE: “latest” is a soft link to point to the latest installed version. Multiple oneVPL versions can exist on the same system.

Next Steps

To explore oneVPL functionality, you can:

  • Start to build your own prototype based on the samples and oneVPL programming guide.
  • Evaluate the features and performance of oneVPL as part of your future product.

Find More

Document Description
oneVPL Programming Guide Details on the oneVPL programming model, function usage, etc.
oneVPL specification Specification for the oneVPL API as an open standard. 
oneVPL API reference API reference for oneVPL.

Notices and Disclaimers

FFmpeg is an open source project licensed under LGPL and GPL. See https://www.ffmpeg.org/legal.html. You are solely responsible for determining if your use of FFmpeg requires any additional licenses. Intel is not responsible for obtaining any such licenses, nor liable for any licensing fees due, in connection with your use of FFmpeg.

No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document. Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade.

This document contains information on products, services and/or processes in development. All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest forecast, schedule, specifications and roadmaps.

The products and services described may contain defects or errors which may cause deviations from published specifications. Current characterized errata are available on request.

Intel, the Intel logo, Intel Core, Intel Atom, and Xeon are trademarks of Intel Corporation in the U.S. and/or other countries.

*Other names and brands may be claimed as the property of others.

Microsoft, Windows®, and the Windows® logo are trademarks, or registered trademarks of Microsoft Corporation in the United States and/or other countries.
Copyright 2020 Intel Corporation
This software and the related documents are Intel copyrighted materials, and your use of them is governed by the express license under which they were provided to you (License). Unless the License provides otherwise, you may not use, modify, copy, publish, distribute, disclose or transmit this software or the related documents without Intel's prior written permission.
This software and the related documents are provided as is, with no express or implied warranties, other than those that are expressly stated in the License.

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804