webcodecs-py 2026.2.0

WebCodecs API for Python

webcodecs-py

About Shiguredo's open source software

We will not respond to PRs or issues that have not been discussed on Discord. Also, Discord is only available in Japanese.

Please read https://github.com/shiguredo/oss/blob/master/README.en.md before use.

時雨堂のオープンソースソフトウェアについて

利用前に https://github.com/shiguredo/oss をお読みください。

webcodecs-py について

webcodecs-py は WebCodecs API API を Python で利用できるようにするライブラリです。

特徴

• WebCodecs API の Python バインディング
• Opus、FLAC、AAC、VP8、VP9、AV1、H.264、H.265 コーデックをサポート
• macOS arm64 にて ImageDecoder による画像デコードをサポート
  • JPEG、PNG、GIF、WebP、BMP、TIFF、HEIC/HEIF に対応
• macOS arm64 にて Apple Audio Toolbox と Video Toolbox を利用したハードウェアアクセラレーション対応
  • AAC エンコード/デコードに対応
  • H.264 / H.265 のハードウェアエンコード/デコードに対応
  • VP9 / AV1 デコードに対応
    • AV1 デコードは M3 チップ以降で利用できる
  • CVPixelBufferRef をエンコーダーが直接利用可能
• Ubuntu x86_64 にて NVIDIA Video Codec SDK を利用したハードウェアアクセラレーション対応
  • NVIDIA Video Codec を利用する場合は NVIDIA ドライバー 570.0 以降が必要
  • AAC エンコード/デコードに対応
  • AV1 / H.264 / H.265 のハードウェアエンコード/デコードに対応
  • VP8 / VP9 デコードに対応
• Ubuntu x86_64 にて Intel VPL を利用したハードウェアアクセラレーション対応
  • AV1 / H.264 / H.265 のハードウェアエンコード/デコードに対応
  • VP8 / VP9 デコードに対応
• libyuv を利用した高速な RAW データ変換
• PyCapsule 経由で CVPixelBuffer を直接受け取るネイティブバッファー対応 (macOS)
• Python Free-Threading 対応
• クロスプラットフォーム対応
  • macOS arm64
  • Ubuntu x86_64 および arm64
  • Windows x86_64
    • Windows はソフトウェアコーデックのみ対応

開発状況は webcodecs-py 対応状況 をご確認ください。

実装しない機能

• CanvasImageSource: VideoFrame の CanvasImageSource コンストラクタはブラウザ固有機能のため実装対象外

サンプルコード

Opus オーディオエンコード

import numpy as np

from webcodecs import (
    AudioData,
    AudioDataInit,
    AudioEncoder,
    AudioEncoderConfig,
    AudioSampleFormat,
)

sample_rate = 48000
frame_size = 960  # 20ms @ 48kHz

# エンコーダを作成
encoded_chunks = []


def on_output(chunk):
    encoded_chunks.append(chunk)


def on_error(error):
    raise RuntimeError(f"エンコーダエラー: {error}")


encoder = AudioEncoder(on_output, on_error)
encoder_config: AudioEncoderConfig = {
    "codec": "opus",
    "sample_rate": sample_rate,
    "number_of_channels": 1,
    "bitrate": 64000,
}
encoder.configure(encoder_config)

# サイン波を生成してエンコード
t = np.linspace(0, frame_size / sample_rate, frame_size, dtype=np.float32)
audio_samples = (np.sin(2 * np.pi * 440 * t) * 0.5).reshape(frame_size, 1)

init: AudioDataInit = {
    "format": AudioSampleFormat.F32,
    "sample_rate": sample_rate,
    "number_of_frames": frame_size,
    "number_of_channels": 1,
    "timestamp": 0,
    "data": audio_samples,
}

# with 文で AudioData を使用（自動的に close される）
with AudioData(init) as audio_data:
    encoder.encode(audio_data)

encoder.flush()

print(f"エンコード完了: {len(encoded_chunks)} チャンク")

encoder.close()

AV1 ビデオエンコード

import numpy as np

from webcodecs import (
    LatencyMode,
    VideoEncoder,
    VideoEncoderConfig,
    VideoFrame,
    VideoFrameBufferInit,
    VideoPixelFormat,
)

width, height = 320, 240

# エンコーダを作成
encoded_chunks = []


def on_output(chunk):
    encoded_chunks.append(chunk)


def on_error(error):
    raise RuntimeError(f"エンコーダエラー: {error}")


encoder = VideoEncoder(on_output, on_error)
encoder_config: VideoEncoderConfig = {
    "codec": "av01.0.04M.08",
    "width": width,
    "height": height,
    "bitrate": 500_000,
    "framerate": 30.0,
    "latency_mode": LatencyMode.REALTIME,
}
encoder.configure(encoder_config)

# I420 フォーマットのテストフレームを作成
data_size = width * height * 3 // 2
frame_data = np.zeros(data_size, dtype=np.uint8)
init: VideoFrameBufferInit = {
    "format": VideoPixelFormat.I420,
    "coded_width": width,
    "coded_height": height,
    "timestamp": 0,
}

# with 文で VideoFrame を使用（自動的に close される）
with VideoFrame(frame_data, init) as frame:
    encoder.encode(frame, {"key_frame": True})

encoder.flush()

print(f"エンコード完了: {len(encoded_chunks)} チャンク, {encoded_chunks[0].byte_length} bytes")

encoder.close()

インストール

uv add webcodecs-py

コーデック

• Opus
  • https://github.com/xiph/opus
• FLAC
  • https://github.com/xiph/flac
• AAC
  • https://developer.apple.com/documentation/audiotoolbox
• VP8
  • https://chromium.googlesource.com/webm/libvpx
  • https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/index.html
• VP9
  • https://chromium.googlesource.com/webm/libvpx
  • https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/index.html
• AV1
  • https://aomedia.googlesource.com/aom
  • https://github.com/videolan/dav1d
  • https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/index.html
• H.264 (AVC)
  • https://developer.apple.com/documentation/videotoolbox
  • https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/index.html
• H.265 (HEVC)
  • https://developer.apple.com/documentation/videotoolbox
  • https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/index.html

Python

• 3.14
• 3.14t
  • Windows のみ非対応
• 3.13
• 3.12

プラットフォーム

• macOS 26 arm64
• macOS 15 arm64
• Ubuntu 24.04 LTS x86_64
• Ubuntu 24.04 LTS arm64
• Ubuntu 22.04 LTS x86_64
• Ubuntu 22.04 LTS arm64
• Windows Server 2025 x86_64
• Windows 11 x86_64

ビルド

make develop

テスト

uv sync
make test

サンプル

uv sync
make develop
uv run python examples/blend2d_to_mp4.py

ライセンス

Apache License 2.0

Copyright 2025-2025, Shiguredo Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

NVIDIA Video Codec SDK

https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/index.html

https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/license/index.html

“This software contains source code provided by NVIDIA Corporation.”