How to use av.CodecContext.create(..., hwaccel=...) with raw H265 chunks?

[Chastrlove]

Title: Unable to use av.CodecContext.create(..., hwaccel=...) with raw H265 chunks and videotoolbox on macOS

---

Hi PyAV team,

I'm trying to build a real-time H265 decoding pipeline using PyAV on macOS, with hardware-accelerated decoding via VideoToolbox.

I noticed that av.CodecContext.create(codec_name, 'r', hwaccel=...) accepts a third hwaccel argument, and I attempted to use it like this.

---

✅ What I'm Trying to Do

• Decode raw H265 chunks (Annex B NALUs, received from a stream), not a complete .h265 or .mp4 file.
• Use videotoolbox as a hardware accelerator for performance.
• Convert decoded frames to BGR using .to_ndarray("bgr24"), and pass to OpenCV for post-processing.
• Avoid using av.open() and demux — my use case works directly with stream fragments.

---

🧪 My Attempt (Non-working Code)

import av
import cv2
from av.codec import hwaccel


def decode_h265_chunk_videotoolbox(chunk: bytes):
    """
    Decode a raw H265 chunk using VideoToolbox hardware acceleration on macOS.
    This does NOT require a complete video container, just raw NALUs.

    :param chunk: Raw H265 encoded data (e.g. Annex B NALU stream)
    :return: List of BGR frames (decoded)
    """

    # Create hardware accelerator (macOS only: 'videotoolbox')
    accel = hwaccel.HWAccel("videotoolbox")

    # Create decoder context with hardware acceleration
    codec_ctx = av.CodecContext.create("hevc", "r", hwaccel=accel)

    # Decode raw chunk
    frames = []
    try:
        packets = codec_ctx.parse(chunk)
        for packet in packets:
            decoded = codec_ctx.decode(packet)
            for frame in decoded:
                img = frame.to_ndarray(format="bgr24")
                frames.append(img)
    except av.FFmpegError as e:
        # Example error:
        # Decoding failed: [Errno 1313558101] Unknown error occurred: 'avcodec_send_packet()'
        print(f"Decoding failed: {e}")

    return frames


# === Test entrypoint ===
if __name__ == "__main__":
    # Simulate a raw H265 NALU chunk
    with open("./test.h265", "rb") as f:
        chunk = f.read()

    frames = decode_h265_chunk_videotoolbox(chunk)

    for i, frame in enumerate(frames):
        cv2.imshow(f"frame-{i}", frame)
        cv2.waitKey(0)

    cv2.destroyAllWindows()

Decoding failed: [Errno 1313558101] Unknown error occurred: 'avcodec_send_packet()'

My Questions

1. Does PyAV currently support using videotoolbox with CodecContext.decode() on raw H265 NALU streams (not full containers)?

test.h265.zip