映像コーデックプリファレンス¶

概要¶

Sora Python SDK では映像コーデックのプリファレンス指定することができます。

Apple Video Toolbox¶

URL:: https://developer.apple.com/documentation/videotoolbox

Apple Video Toolbox は macOS で利用できるハードウェアアクセラレーターです
macOS でのみ利用できます。対応コーデックは H.264 / H.265 です
decoder や encoder に INTERNAL を指定することで Apple Video Toolbox を利用します

Intel Video Processing Library (VPL)¶

URL:: https://www.intel.com/content/www/us/en/developer/tools/vpl/overview.html

Intel VPL は Intel 組込 GPU や Arc で利用できるハードウェアアクセラレーターです
Linux と Windows で利用できます。対応コーデックは VP9 / AV1 / H.264 / H.265 です
VP9 はデコーダーのみ利用できます
decoder や encoder に INTEL_VPL を指定することで Intel VPL を利用します

AMD Advanced Media Framework (AMF) SDK¶

URL:: https://gpuopen.com/advanced-media-framework/

AMD AMF は AMD 組込 GPU や AMD のビデオカードで利用できるハードウェアアクセラレーターです
Linux と Windows で利用できます。対応コーデックは VP9 / AV1 / H.264 / H.265 です
AV1 デコーダーは Windows x86_64 でのみ利用できます
decoder や encoder に AMD_AMF を指定することで AMD AMF を利用します

NVIDIA Video Codec SDK¶

URL:: https://developer.nvidia.com/video-codec-sdk

NVIDIA Video Codec SDK は NVIDIA のビデオカードで利用できるハードウェアアクセラレーターです
Linux と Windows で利用できます。対応コーデックは VP8 / VP9 / AV1 / H.264 / H.265 です
VP8 と VP9 はデコーダーのみ利用できます
decoder や encoder に NVIDIA_VIDEO_CODEC_SDK を指定することで NVIDIA Video Codec SDK を利用します

Cisco OpenH264¶

URL:: https://www.openh264.org/

Cisco OpenH264 はオープンソースのソフトウェア H.264 エンコーダー/デコーダーです
対応コーデックは H.264 です
Sora の openh264 に OpenH264 のパスを指定することで Cisco OpenH264 が利用できるようになります
decoder や encoder に CISCO_OPENH264 を指定することで Cisco OpenH264 を利用します

利用できるコーデック一覧を取得する¶

Sora.get_video_codec_capability を呼び出すことで利用できるコーデック一覧を取得できます。

ただし、取得した内容をそのまま Sora の video_codec_preference に指定することはできません。

VP9 のエンコーダーが正常に動作しない¶

Ubuntu x86_64 と Windows x86_64 では VP9 のエンコーダーが正常に動作しない問題がわかっています

Ubuntu で Intel VPL と NVIDIA Video Codec SDK の両方が利用できる場合¶

Ubuntu 環境で Intel VPL と NVIDIA Video Codec SDK の両方が利用できる場合、 AV1 や H.264 にどちらの機能を利用するかを指定する必要があります。

ここでは Intel VPL を優先し、 Intel VPL が利用できない場合は NVIDIA Video Codec SDK を利用する例を示します。

import sys

from sora_sdk import (
    Sora,
    SoraVideoCodecImplementation,
    SoraVideoCodecPreference,
    get_video_codec_capability,
)

if sys.platform != "linux":
    raise RuntimeError("This script must be run in a Linux environment")

capability = get_video_codec_capability()

intel_vpl_available = None
nvidia_video_codec_sdk_available = None

# 利用できるエンジンを確認する
for engine in capability.engines:
    match engine.name:
        case SoraVideoCodecImplementation.INTEL_VPL:
            intel_vpl_available = True
        case SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK:
            nvidia_video_codec_sdk_available = True
        case _:
            continue

# Intel VPL または NVIDIA Video Codec SDK が利用できない場合はエラーにする
if intel_vpl_available or nvidia_video_codec_sdk_available:
    raise RuntimeError("Intel VPL or NVIDIA Video Codec SDK is not available")

# 利用するコーデックを決める
selected_engine = None
if intel_vpl_available:
    selected_engine = SoraVideoCodecImplementation.INTEL_VPL
elif nvidia_video_codec_sdk_available:
    selected_engine = SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK
else:
    selected_engine = SoraVideoCodecImplementation.INTERNAL

# video_codec_preference に設定する Codec リストを用意する
codecs = []
for engine in capability.engines:
    if engine.name == selected_engine:
        for codec in engine.codecs:
            if codec.decoder or codec.encoder:
                # encoder/decoder 両方が true であれば採用する
                if codec.decoder and codec.encoder:
                    codecs.append(
                        SoraVideoCodecPreference.Codec(
                            type=codec.type,
                            decoder=engine.name,
                            encoder=engine.name,
                        )
                    )

sora = Sora(
    video_codec_preference=SoraVideoCodecPreference(
        codecs=codecs,
    ),
)

video_codec_preference を指定する¶

Sora インスタンス生成時に Sora.video_codec_preference を指定することで映像コーデックで利用する実装を細かくしていすることができます。

以下の例では送信側で H.264 のエンコーダーに OpenH264 を利用するようにしている例です。

from sora_sdk import (
    Sora,
    SoraVideoCodecImplementation,
    SoraVideoCodecPreference,
    SoraVideoCodecType,
)

# Sora インスタンスを生成
sora = Sora(
    # ビデオコーデックプリファレンスを指定する
    video_codec_preference=SoraVideoCodecPreference(
        codecs=[
            # H.264 のみを利用する
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H264,
                # H.264 のエンコーダーに OpenH264 を指定する
                encoder=SoraVideoCodecImplementation.CISCO_OPENH264,
                # role: sendonly で利用するのでデコーダーは指定しない
                decoder=None,
            ),
        ],
    ),
    openh264="/path/to/libopenh264-2.5.0-linux64.7.so",
)

指定できるコーデックについては SoraVideoCodecType をご確認ください
指定する映像コーデックの実装については SoraVideoCodecImplementation をご確認ください

デフォルト¶

Sora.video_codec_preference のデフォルトは None で、この場合は SoraVideoCodecPreference.Codec の全ての decoder と encoder に SoraVideoCodecImplementation.INTERNAL が指定されます。

指定したコーデックのみを利用する¶

Sora.video_codec_preference に SoraVideoCodecPreference.Codec を指定した場合は、指定したコーデックのみが利用されます。もし decoder だけ指定した場合は encoder は None が指定され、利用できません。

Apple Video Toolbox¶

Apple Video Toolbox は macOS で利用できるハードウェアアクセラレーターです。

H.264 と H.265 のエンコーダー/デコーダーを利用できます。

from sora_sdk import (
    Sora,
    SoraVideoCodecImplementation,
    SoraVideoCodecPreference,
    SoraVideoCodecType,
)

sora = Sora(
    video_codec_preference=SoraVideoCodecPreference(
        codecs=[
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H264,
                encoder=SoraVideoCodecImplementation.INTERNAL,
                decoder=SoraVideoCodecImplementation.INTERNAL,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H265,
                encoder=SoraVideoCodecImplementation.INTERNAL,
                decoder=SoraVideoCodecImplementation.INTERNAL,
            ),
        ],
    ),
)

Intel VPL¶

Intel VPL は Intel の GPU を利用して映像をエンコード/デコードするハードウェアアクセラレーターです。 Intel の統合 GPU や Arc で利用できます。

対応コーデックは AV1 / H.264 / H.265 です。 VP9 は正常に動作しないため現時点では C++ SDK 側で無効かしています。 AV1 は GPU が Intel Arc のみで利用できます。

from sora_sdk import (
    Sora,
    SoraVideoCodecImplementation,
    SoraVideoCodecPreference,
    SoraVideoCodecType,
)

sora = Sora(
    video_codec_preference=SoraVideoCodecPreference(
        codecs=[
            # Intel VPL の AV1 は Core Ultra や Arc GPU でしか動作しません。
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.AV1,
                encoder=SoraVideoCodecImplementation.INTEL_VPL,
                decoder=SoraVideoCodecImplementation.INTEL_VPL,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H264,
                encoder=SoraVideoCodecImplementation.INTEL_VPL,
                decoder=SoraVideoCodecImplementation.INTEL_VPL,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H265,
                encoder=SoraVideoCodecImplementation.INTEL_VPL,
                decoder=SoraVideoCodecImplementation.INTEL_VPL,
            ),
        ],
    ),
)

対応コーデック¶

対応しているコーデックはハードウェアによって異なります。

Sora Python SDK では以下のコーデックに対応しています。

VP9
- デコードのみ対応
AV1
- エンコード/デコード対応
H.264
- エンコード/デコード対応
H.265
- エンコード/デコード対応

Intel VPL で AV1 や H.265 を利用したサイマルキャストの最小解像度制限¶

Intel VPL で AV1 や H.265 を利用したサイマルキャストでは、最小解像度 128x96 を下回った場合、ハードウェアによる制限でエンコードに失敗します。

そのため、Intel VPL で AV1 または H.265 を利用したサイマルキャスト利用する場合は、最小解像度が 128x96 以上になるよう、 simulcast_encodings の scaleResolutionDownBy または scaleResolutionDownTo を指定するようにしてください。

Intel VPL を Ubuntu 24.04 でセットアップする¶

sudo apt update
sudo apt -y install wget gpg

# Intel の GPG キーをインストールする
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | sudo gpg --dearmor --output /usr/share/keyrings/intel-graphics.gpg
# Intel のリポジトリを追加する
echo "deb [arch=amd64,i386 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu noble client" | sudo tee /etc/apt/sources.list.d/intel-gpu-noble.list

sudo apt update
# Sora Python SDK に必要なライブラリをインストールする
sudo apt -y install git libva2 libdrm2 make build-essential libx11-dev
# Intel VPL に必要なライブラリをインストールする
sudo apt -y install intel-media-va-driver-non-free libmfx1 libmfx-gen1 libvpl2 libvpl-tools libva-glx2 va-driver-all vainfo

# sudo で vainfo が実行できるか確認する
sudo vainfo --display drm --device /dev/dri/renderD128

# udev のルールを追加する
sudo echo 'KERNEL=="render*" GROUP="render", MODE="0666"' > /etc/udev/rules.d/99-vpl.rules
# 再起動する
sudo reboot

# vainfo が sudo なしで実行できるか確認する
vainfo --display drm --device /dev/dri/renderD128

Intel VPL を Ubuntu 22.04 でセットアップする¶

sudo apt update
sudo apt -y install wget gpg

# Intel の GPG キーをインストールする
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | sudo gpg --dearmor --output /usr/share/keyrings/intel-graphics.gpg
# Intel のリポジトリを追加する
echo "deb [arch=amd64,i386 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy client" | sudo tee /etc/apt/sources.list.d/intel-gpu-jammy.list

sudo apt update
# Sora Python SDK に必要なライブラリをインストールする
sudo apt -y install git libva2 libdrm2 make build-essential libx11-dev
# Intel VPL に必要なライブラリをインストールする
sudo apt -y install intel-media-va-driver-non-free libmfx1 libmfx-gen1 libvpl2 libvpl-tools libva-glx2 va-driver-all vainfo

# sudo で vainfo が実行できるか確認する
sudo vainfo --display drm --device /dev/dri/renderD128

# udev のルールを追加する
sudo echo 'KERNEL=="render*" GROUP="render", MODE="0666"' > /etc/udev/rules.d/99-vpl.rules
# 再起動する
sudo reboot

# vainfo が sudo なしで実行できるか確認する
vainfo --display drm --device /dev/dri/renderD128

Intel Linux 向けグラフィックス・ドライバーの確認方法¶

Linux* 向けのグラフィックス・ドライバーの識別と検索方法

lspci -k | grep -EA3 'VGA|3D|Display'

参考¶

AMD AMF¶

AMD AMF バージョン:: v1.4.36

from sora_sdk import (
    Sora,
    SoraVideoCodecImplementation,
    SoraVideoCodecPreference,
    SoraVideoCodecType,
)

sora = Sora(
    video_codec_preference=SoraVideoCodecPreference(
        codecs=[
            # AMD AMF の AV1 は Zen 4 世代の組込 GPU から利用できます
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.AV1,
                encoder=SoraVideoCodecImplementation.AMD_AMF,
                decoder=SoraVideoCodecImplementation.AMD_AMF,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H264,
                encoder=SoraVideoCodecImplementation.AMD_AMF,
                decoder=SoraVideoCodecImplementation.AMD_AMF,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H265,
                encoder=SoraVideoCodecImplementation.AMD_AMF,
                decoder=SoraVideoCodecImplementation.AMD_AMF,
            ),
        ],
    ),
)

Ubuntu x86_64 で AV1 デコーダーが正常に動作しない¶

Ubuntu x86_64 では AV1 デコーダーはドライバーが対応していないため利用できません
Windows x86_64 では正常に動作します

Ubuntu x86_64 で AMD AMF をセットアップする¶

セキュアブートは切っておく必要があります

sudo amdgpu-install --usecase=graphics,amf --vulkan=pro

sudo usermod -aG render $USER
sudo usermod -aG video $USER

# シェルに入り直すか以下のコマンドで反映させる
newgrp render
newgrp video

Windows x86_64 で AMD AMF をセットアップする¶

ドライバーを AMD からダウンロードしてインストールしてください。

https://www.amd.com/en.html

NVIDIA Video Codec SDK¶

NVIDIA Video Codec SDK バージョン:: 12.0
CUDA バージョン:: 11.8.0-1

NVIDIA Video Codec SDK は NVIDIA GPU に搭載されている NVENC/NVDEC をハードウェアアクセラレーターとして利用する SDK です。

Sora Python SDK では Ubuntu または Windows の x86_64 で NVIDIA Video Codec SDK を利用できます。

from sora_sdk import (
    Sora,
    SoraVideoCodecImplementation,
    SoraVideoCodecPreference,
    SoraVideoCodecType,
)

sora = Sora(
    video_codec_preference=SoraVideoCodecPreference(
        codecs=[
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.VP8,
                decoder=SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.VP9,
                decoder=SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.AV1,
                encoder=SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK,
                decoder=SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H264,
                encoder=SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK,
                decoder=SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK,
            ),
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H265,
                encoder=SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK,
                decoder=SoraVideoCodecImplementation.NVIDIA_VIDEO_CODEC_SDK,
            ),
        ],
    ),
)

対応コーデック¶

対応しているコーデックはハードウェアによって異なります。

詳細は公式ページを確認してください。 https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new

Sora Python SDK では以下のコーデックに対応しています。

VP8
- デコードのみ対応
VP9
- デコードのみ対応
AV1
- エンコード/デコード対応
H.264
- エンコード/デコード対応
H.265
- エンコード/デコード対応

NVIDIA Video Codec SDK で AV1 や H.265 を利用したサイマルキャストの最小解像度制限¶

NVIDIA Video Codec SDK で AV1 や H.265 を利用したサイマルキャストでは、最小解像度 128x96 を下回った場合、ハードウェアによる制限でエンコードに失敗します。

そのため、NVIDIA Video Codec SDK で AV1 または H.265 を利用したサイマルキャスト利用する場合は、最小解像度が 128x96 以上になるよう、 simulcast_encodings の scaleResolutionDownBy または scaleResolutionDownTo を指定するようにしてください。

Ubuntu x86_64 で NVIDIA Video Codec SDK をセットアップする¶

# デスクトップの場合
sudo ubuntu-drivers list

# サーバーの場合
sudo ubuntu-drivers list --gpgpu

# これだけでインストールできます
sudo ubuntu-drivers install

実行の参考¶

# インストールしたドライバーを確認できます
$ nvidia-smi
Tue Mar  4 02:03:58 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.120                Driver Version: 550.120        CUDA Version: 12.4     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 4060        Off |   00000000:01:00.0 Off |                  N/A |
| 30%   30C    P8             N/A /  115W |       2MiB /   8188MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI        PID   Type   Process name                              GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

参考¶

https://documentation.ubuntu.com/server/how-to/graphics/install-nvidia-drivers/index.html

Cisco OpenH264¶

OpenH264 バージョン:: 2.6.0

Cisco OpenH264 はオープンソースのソフトウェア H.264 エンコーダー/デコーダーです。 Cisco が公開しているバイナリを利用する事で、 H.264 のライセンスを Cisco が負担してくれる仕組みです。

Sora Python SDK では Ubuntu の x86_64 または arm64 、 macOS の arm64 、Windows の x86_64 で Cisco OpenH264 を利用できます。

from sora_sdk import (
    Sora,
    SoraVideoCodecImplementation,
    SoraVideoCodecPreference,
    SoraVideoCodecType,
)

sora = Sora(
    openh264="/path/to/libopenh264-2.5.0-mac-arm64.dylib",
    video_codec_preference=SoraVideoCodecPreference(
        codecs=[
            SoraVideoCodecPreference.Codec(
                type=SoraVideoCodecType.H264,
                encoder=SoraVideoCodecImplementation.CISCO_OPENH264,
                decoder=SoraVideoCodecImplementation.CISCO_OPENH264,
            ),
        ],
    ),
)

Ubuntu x86_64 で Cisco OpenH264 をセットアップする¶

curl -LO http://ciscobinary.openh264.org/libopenh264-2.5.0-linux64.7.so.bz2
bzip2 -d libopenh264-2.5.0-linux-x64.7.so.bz2

Ubuntu arm64 で Cisco OpenH264 をセットアップする¶

curl -LO http://ciscobinary.openh264.org/libopenh264-2.5.0-linux-arm64.7.so.bz2
bzip2 -d libopenh264-2.5.0-linux-arm64.7.so.bz2

macOS arm64 で Cisco OpenH264 をセットアップする¶

curl -LO http://ciscobinary.openh264.org/libopenh264-2.5.0-mac-arm64.dylib.bz2
bzip2 -d libopenh264-2.5.0-mac-arm64.dylib.bz2

Windows x86_64 で Cisco OpenH264 をセットアップする¶

$url = "http://ciscobinary.openh264.org/openh264-2.5.0-win64.dll.bz2"
Invoke-WebRequest -Uri $url -OutFile "openh264-2.5.0-win64.dll.bz2"
7z e openh264-2.5.0-win64.dll.bz2