Get Started with Intel® oneAPI Video Processing Library

By Yan Liu, Ekaterina Mekhnetsova

Version:2021.1   Published:09/26/2019   Last Updated:03/26/2021

Get Started with Intel® oneAPI Video Processing Library

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

Ensure oneVPL and its runtime libraries are installed successfully on your system. Refer to the oneAPI installation page page for download and installation instructions.

You can also install oneVPL and its CPU runtime by building sources from GitHub.

oneVPL has many runtime libraries, the default runtime is CPU runtime. This document mainly describes the sample code for CPU runtime.

System Requirements

Refer to the oneVPL System Requirements page.

Sample Code

Use the following sample projects to learn basic usage scenarios of oneVPL application programming interfaces and to try out oneVPL functionality:

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

For the detailed instructions, refer to the individual README files in each oneVPL sample directory.

Download Sample Code

You can clone or download the sample source code from the oneAPI-samples repository.

Build and Run Sample Code on Linux

Note: The following variables are used in the steps below.

  • <oneAPI sample root> refers to the sample code cloned from GitHub
  • <oneAPI install root> refers to the root directory of Intel(R) oneAPI Base Toolkit, which includes oneVPL
  • <oneVPL build root> refers to the root directory of the oneVPL installation when oneVPL is built from the source code
  • <sample name> refers to one of the names of hello-decode, hello-encode, hello-vpp, dpcpp-blur mentioned in Sample Code section

Clone the source code

git clone https://github.com/oneapi-src/oneAPI-samples.git
cd oneAPI-samples/Libraries/oneVPL

Set up environment

source <oneAPI install root>/setvars.sh # When you installed oneVPL from Intel(R) oneAPI Base Toolkit
source <oneVPL build root>/env/vars.sh # When you build oneVPL from sources

Build and run samples with cmake

In general, all samples with the source code in <oneAPI sample root>/Libraries/oneVPL/<sample name> can be built and run using the following process:

source <oneAPI install root>/setvars.sh
cd sample_tests/<sample name>
# Build sample
mkdir build
cd build
cmake ..
cmake --build .
# Run sample
cmake --build . --target run

Note:

  1. On success, you will see [100%] completed at the end of the cmake target output.
  2. You might get the warning message while running dpcpp-blur sample. The root cause is that DPC++ is not enabled during installation.

Test built samples from command line

Run "hello-decode":

./hello-decode ../content/cars_128x96.h265 

Expected result:

Found ApiVersion: 1.34     HW   skip
Found ApiVersion: 2.2     SW   session created
Decoding ../content/cars_128x96.h265 -> out.i420
Decoded 60 frames

Run "dpcpp-blur":

./dpcpp-blur ../content/cars_128x96.i420 128 96

Expected result:

! DPCPP blur feature not enabled

Found ApiVersion: 1.34     HW   skip
Found ApiVersion: 2.2     SW   session created
Processing ../content/cars_128x96.i420 -> out.bgra
Processed 60 frames

Note:

  1. It is expected to see "! DPCPP blur feature not enabled" if DPC++ toolkit was not installed.
  2. If you run the build samples on API 2.2 supported hardware, the sample will automatically select the API 2.2 hardware runtime.

Build and Run Sample Code on Windows

Note: The following variables are used in the steps below.

  • <oneAPI sample root> refers to the sample code cloned from GitHub
  • <oneAPI install root> refers to the root directory of Intel(R) oneAPI Base Toolkit, which includes oneVPL
  • <oneVPL build root> refers to the root directory of the oneVPL installation when oneVPL is built from the source code
  • <sample name> refers to one of the names of hello-decode, hello-encode, hello-vpp, dpcpp-blur mentioned in Sample Code section

Clone the source code

git clone https://github.com/oneapi-src/oneAPI-samples.git
cd oneAPI-samples\Libraries\oneVPL

Set up environment

<oneAPI install root>\setvars.bat # When you installed oneVPL from Intel(R) oneAPI Base Toolkit
<oneVPL build root>\env\var.bat # When you build oneVPL from sources

Build and run samples with cmake

oneAPI install root>\setvars.bat
cd <oneAPI sample root>\Libraries\oneVPL\<sample name>
mkdir build
cd build
cmake ..
cmake --build .
cmake --build . --target run

Note:

  1. On success, you will see the cmake sequence completed at the end.
  2. You might get the warning message while running dpcpp-blur sample. The root cause is that DPC++ is not enabled during installation.

Test built samples from command line

Run "hello-decode":

Debug\hello-decode.exe ..\content\cars_128x96.h265

Expected result:

Found ApiVersion: 1.34          HW   skip
Found ApiVersion: 2.2           SW   session created
Decoding ..\content\cars_128x96.h265 -> out.i420
Decoded 60 frames

Run "dpcpp-blur":

Debug\dpcpp-blur.exe ..\content\cars_128x96.i420 128 96

Expected result:

! DPCPP blur feature not enabled

Found ApiVersion: 1.34          HW   skip
Found ApiVersion: 2.2           SW   session created
Processing ..\content\cars_128x96.i420 -> out.bgra
Processed 60 frames

Note:

  1. It is expected to see "! DPCPP blur feature not enabled" if DPC++ toolkit was not installed.
  2. If you run the build samples on API 2.2 supported hardware, the sample will select and run on API 2.2 hardware runtime automatically.

Run pre-built Intel® Media SDK samples on Linux

cd <oneAPI install root>/vpl/latest/bin
source <oneAPI install root>/setvars.sh
sample_decode.exe h265 -i ../content/cars_128x96.h265

Expected result:

pretending that stream is 30fps one
pretending that aspect ratio is 1:1
Decoding Sample Version 8.4.27.0


Input video     HEVC
Output format   NV12
Input:
  Resolution    128x96
  Crop X,Y,W,H  0,0,128,96
Output:
  Resolution    128x96
Frame rate      30.00
Memory type             system
MediaSDK impl           hw
MediaSDK version        1.34

Decoding started
Frame number:   60, fps: 109.540, fread_fps: 0.000, fwrite_fps: 0.000
Decoding finished

Run pre-built Intel® Media SDK samples on Windows

cd <oneAPI install root>\vpl\latest\bin
source <oneAPI install root>/setvars.sh
sample_decode.exe h265 -i ..\content\cars_128x96.h265

Expected result:

pretending that stream is 30fps one
pretending that aspect ratio is 1:1
Decoding Sample Version 8.4.27.0


Input video     HEVC
Output format   NV12
Input:
  Resolution    128x96
  Crop X,Y,W,H  0,0,128,96
Output:
  Resolution    128x96
Frame rate      30.00
Memory type             system
MediaSDK impl           hw
MediaSDK version        1.34

Decoding started
Frame number:   60, fps: 109.540, fread_fps: 0.000, fwrite_fps: 0.000
Decoding finished

Run other pre-built samples

You can also try the pre-built sample binaries at <oneAPI install root>/vpl/latest/bin.

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.

Note: oneVPL is aligned with the oneVPL Specification version 2.3 at the time of 2021.2.2 release. oneVPL Specifications below 2.3 version used the legacy header and dispatcher naming. As a result, the prototypes developed with the 2021.1.1 revision of oneVPL should use the legacy oneVPL Programming Guide.

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

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.