Get Started with Intel® oneAPI Video Processing Library

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.

You can also install oneVPL dispatcher, CPU runtime, and GPU runtime by building sources from GitHub.

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/hello-decode: Read an encoded video stream file, decode it, and output it to a raw video file.
• hello/hello-encode: Read a raw video file, encode it, and output it to an encoded video stream file.
• hello/hello-vpp: Read a raw video file (I420), resize it, and output it to a new raw video file (I420).

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

Build and Run Sample Code on Linux

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

• <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 mentioned in Sample Code section

Clone the source code

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

Set up environment

source <oneVPL build root>/env/vars.sh # When you build oneVPL from sources

Additional setup steps for GPU:

Windows: refer to oneVPL Installation Guide.

Linux: 

• Install the graphics stack

Build and run samples with cmake

All samples with the source code in <oneVPL sample root>/Libraries/oneVPL/<sample name> can be built and run using the following process:

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

Note:

• On success, you will see [max-content] completed at the end of the cmake target output.

You may also compile and link applications using pkg-config.

Test built samples from command line

Run "hello-decode":

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

Expected result below.

Note: Implementation details may be different based on what is found on the system when the sample is run.

Implementation details:
  ApiVersion:           2.6
  Implementation type:  SW
  AccelerationMode via: NA
  Path: /opt/intel/oneapi/vpl/2022.1.0/oneVPL_Linux_Q1_RC1/lib/libvplswref64.so.1
Decoding ../../../content/cars_128x96.h265 -> out.raw
Output colorspace: I420 (aka yuv420p)
Decoded 60 frames

Build and Run Sample Code on Windows

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

• <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 mentioned in Sample Code section

Clone the source code

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

Set up environment

<oneVPL build root>\env\var.bat # When you build oneVPL from sources

Build and run samples with cmake

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

Note:

• On success, you will see [max-content] completed at the end of the cmake target output.

You may also compile and link applications using pkg-config.

Test built samples from command line

Run "hello-decode":

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

Expected result below.

Note: Implementation details may be different based on what is found on the system when the sample is run.

Implementation details:
  ApiVersion:           2.6
  Implementation type:  SW
  AccelerationMode via: NA
  Path: C:\vpltmp\bin\libvplswref64.dll
Decoding ..\content\cars_128x96.h265 -> out.raw
Output colorspace: I420 (aka yuv420p)
Decoded 60 frames

.

Run pre-built Intel® Media SDK tools on Linux

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

Expected result below.

Note: Implementation details may be different based on what is found on the system when the sample is run.

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 <oneVPL install root>\vpl\latest\bin
source <oneAPI install root>/setvars.sh
sample_decode.exe h265 -i ..\content\cars_128x96.h265

Expected result below.

Note: Implementation details may be different based on what is found on the system when the sample is run.

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 and tool binaries at <oneVPL 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/oneapi/vpl/latest
• For non-root users in Linux: $HOME/intel/oneapi/vpl/latest, or you can configure your own
• For Windows: C:\Program Files (x86)\oneapi\vpl\latest

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

Debugging

Use the following debug versions of oneVPL on Windows:

• Static linking:vpld.lib

• Dynamic linking: libvpld.dll

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

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.