PyAV

https://pyav.basswood.io/docs/stable/
Admin
PyAV is a Pythonic binding for FFmpeg that aims to provide direct and precise access to media via...
Tokens:16,246
Snippets:195
Trust Score:4.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install PyAV via pip

Source: https://pyav.basswood.io/docs/stable/overview/installation.html

Standard installation method using binary wheels from PyPI.

```bash
pip install av
```

--------------------------------

### Install PyAV from source

Source: https://pyav.basswood.io/docs/stable/overview/installation.html

Force installation from source to use a custom build of FFmpeg.

```bash
pip install av --no-binary av
```

--------------------------------

### Dynamic Stream Selection with get()

Source: https://pyav.basswood.io/docs/stable/api/stream.html

Shows how to use the get() method for flexible stream selection using positional and keyword arguments.

```python
# Get the first channel.
streams.get(0)

# Get the first two audio channels.
streams.get(audio=(0, 1))
```

```python
# Get the first video channel.
streams.get(video=0)
# or
streams.get({'video': 0})
```

--------------------------------

### Install PyAV via Conda

Source: https://pyav.basswood.io/docs/stable/overview/installation.html

Installation method using the conda-forge channel.

```bash
conda install av -c conda-forge
```

--------------------------------

### Inspecting a Stream

Source: https://pyav.basswood.io/docs/stable/api/stream.html

Example of opening a container and accessing a specific video stream.

```python
>>> fh = av.open(video_path)
>>> stream = fh.streams.video[0]
>>> stream
<av.VideoStream #0 h264, yuv420p 1280x720 at 0x...>
```

--------------------------------

### Install FFmpeg dependencies on MacOS

Source: https://pyav.basswood.io/docs/stable/overview/installation.html

Use Homebrew to install required FFmpeg and pkg-config tools on MacOS.

```bash
brew install ffmpeg pkg-config
```

--------------------------------

### Build PyAV on Windows with custom FFmpeg

Source: https://pyav.basswood.io/docs/stable/overview/installation.html

Specify the directory of your local FFmpeg installation during the build process.

```bash
python setup.py build --ffmpeg-dir=C:\ffmpeg
```

--------------------------------

### Accessing Frame Time in Seconds

Source: https://pyav.basswood.io/docs/stable/_sources/api/time.rst.txt

Use the convenience attribute to get the frame time as a float in seconds.

```python
>>> f.time
0.04
```

--------------------------------

### Build PyAV from latest source

Source: https://pyav.basswood.io/docs/stable/overview/installation.html

Steps to clone the repository, prepare the environment, and build PyAV.

```bash
# Get PyAV from GitHub.
git clone https://github.com/PyAV-Org/PyAV.git
cd PyAV

# Prep a virtualenv.
source scripts/activate.sh

# Optionally build FFmpeg.
./scripts/build-deps

# Build PyAV.
make
```

--------------------------------

### Initialize VideoFormat

Source: https://pyav.basswood.io/docs/stable/api/video.html

Create a VideoFormat instance by specifying the format name.

```python
>>> format = VideoFormat('rgb24')
>>> format.name
'rgb24'
```

--------------------------------

### Open a device with av.open

Source: https://pyav.basswood.io/docs/stable/api/_globals.html

Use the format parameter to specify a device, such as avfoundation for webcams on macOS.

```python
>>> # Open webcam on MacOS.
>>> av.open('0', format='avfoundation')
```

--------------------------------

### Initialize Python Logging

Source: https://pyav.basswood.io/docs/stable/api/utils.html

Configures the standard Python logging system to handle logs translated from FFmpeg.

```python
import logging
logging.basicConfig()
```

--------------------------------

### Initialize a VideoFrame

Source: https://pyav.basswood.io/docs/stable/_sources/api/video.rst.txt

Create a new VideoFrame instance by specifying dimensions and pixel format.

```python
>>> frame = VideoFrame(1920, 1080, 'rgb24')
```

--------------------------------

### av.codec.hwaccel.hwdevices_available()

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Retrieves a list of hardware device types supported by the current FFmpeg build.

```APIDOC
## av.codec.hwaccel.hwdevices_available()

### Description
Returns the names of the hardware device types FFmpeg was built with, such as ["cuda", "videotoolbox"].

### Returns
- **list** - A list of strings representing supported hardware device types.
```

--------------------------------

### CodecContext.create

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Creates a new CodecContext instance for a specific codec, mode, and hardware acceleration setting.

```APIDOC
## CodecContext.create(codec, mode=None, hwaccel=None)

### Description
Creates a new CodecContext instance. This is a static method used to initialize the codec context before opening it.

### Parameters
- **codec** (str) - Required - The name or object of the codec to use.
- **mode** (str) - Optional - The mode of operation.
- **hwaccel** (str) - Optional - Hardware acceleration configuration.
```

--------------------------------

### Generate Video from Numpy Arrays

Source: https://pyav.basswood.io/docs/stable/cookbook/numpy.html

Demonstrates how to create a video file by programmatically generating frames as Numpy arrays and encoding them using PyAV.

```python
import numpy as np

import av

duration = 4
fps = 24
total_frames = duration * fps

container = av.open("test.mp4", mode="w")

stream = container.add_stream("mpeg4", rate=fps)
stream.width = 480
stream.height = 320
stream.pix_fmt = "yuv420p"

for frame_i in range(total_frames):
    img = np.empty((320, 480, 3))
    img[:, :, 0] = 0.5 + 0.5 * np.sin(2 * np.pi * (0 / 3 + frame_i / total_frames))
    img[:, :, 1] = 0.5 + 0.5 * np.sin(2 * np.pi * (1 / 3 + frame_i / total_frames))
    img[:, :, 2] = 0.5 + 0.5 * np.sin(2 * np.pi * (2 / 3 + frame_i / total_frames))

    img = np.round(255 * img).astype(np.uint8)

    frame = av.VideoFrame.from_ndarray(img, format="rgb24")
    for packet in stream.encode(frame):
        container.mux(packet)

# Flush stream
for packet in stream.encode():
    container.mux(packet)

# Close the file
container.close()
```

--------------------------------

### av.open(file, mode='r', **kwargs)

Source: https://pyav.basswood.io/docs/stable/api/_globals.html

The main entrypoint for opening files or streams. It supports reading and writing, custom formats, and various configuration options for containers and streams.

```APIDOC
## av.open(file, mode='r', **kwargs)

### Description
Main entrypoint to opening files or streams. Returns a Container object.

### Parameters
- **file** (str) - Required - The file to open, which can be either a string or a file-like object.
- **mode** (str) - Optional - "r" for reading and "w" for writing. Defaults to "r".
- **format** (str) - Optional - Specific format to use. Defaults to autodetect.
- **options** (dict) - Optional - Options to pass to the container and all streams.
- **container_options** (dict) - Optional - Options to pass to the container.
- **stream_options** (list) - Optional - Options to pass to each stream.
- **metadata_encoding** (str) - Optional - Encoding to use when reading or writing file metadata. Defaults to "utf-8".
- **metadata_errors** (str) - Optional - Specifies how to handle encoding errors. Defaults to "strict".
- **buffer_size** (int) - Optional - Size of buffer for Python I/O operations in bytes. Defaults to 32768.
- **timeout** (float or tuple) - Optional - How many seconds to wait for data before giving up.
- **io_open** (callable) - Optional - Custom I/O callable for opening files/streams.
- **hwaccel** (HWAccel) - Optional - Settings for hardware-accelerated decoding.

### Returns
- **Container** - The opened media container.
```

--------------------------------

### Inspect Codec Information

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Demonstrates how to instantiate a Codec object and access its basic attributes like name, type, and encoder status.

```python
>>> codec = Codec('mpeg4', 'r')
>>> codec.name
'mpeg4'
>>> codec.type
'video'
>>> codec.is_encoder
False
```

--------------------------------

### av.audio.fifo.AudioFifo.write

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Push a frame of samples into the FIFO queue.

```APIDOC
## av.audio.fifo.AudioFifo.write(frame)

### Description
Push a frame of samples into the queue. The FIFO uses attributes from the first frame to populate output frames.

### Parameters
- **frame** (AudioFrame) - Required - The frame of samples to push.
```

--------------------------------

### av.codec.hwaccel.HWAccel

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Initializes settings for hardware-accelerated decoding and encoding. This object can be passed to av.open() for decoding or OutputContainer.add_stream() for encoding.

```APIDOC
## class av.codec.hwaccel.HWAccel(device_type, device=None, allow_software_fallback=True, options=None, flags=None, is_hw_owned=False)

### Description
Configures hardware acceleration parameters for media processing. Use this to specify the device type and behavior for hardware-backed codecs.

### Parameters
- **device_type** (str or HWDeviceType) - Required - The kind of device (e.g., "cuda", "vaapi", "videotoolbox").
- **device** (str) - Optional - An optional device identifier (e.g., path or index).
- **allow_software_fallback** (bool) - Optional - Whether to fall back to software decoding if hardware fails.
- **options** (dict) - Optional - Options passed to av_hwdevice_ctx_create.
- **flags** (int) - Optional - Flags passed to av_hwdevice_ctx_create.
- **is_hw_owned** (bool) - Optional - If True, frames remain on the device instead of being downloaded to system memory.
```

--------------------------------

### Hardware Accelerated Decoding

Source: https://pyav.basswood.io/docs/stable/_sources/api/codec.rst.txt

Use HWAccel with av.open to enable hardware-accelerated decoding. Frames are automatically downloaded to system memory.

```python
import av
from av.codec.hwaccel import HWAccel

hwaccel = HWAccel(device_type="videotoolbox")
with av.open("input.mp4", hwaccel=hwaccel) as container:
    for frame in container.decode(video=0):
        ...  # Frames are downloaded to system memory by default.
```

--------------------------------

### CodecContext.open

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Opens the codec context for use.

```APIDOC
## CodecContext.open(strict=True)

### Description
Initializes and opens the codec context for encoding or decoding operations.

### Parameters
- **strict** (bool) - Optional - Whether to enforce strict compliance with codec standards.
```

--------------------------------

### Access AudioFormat name

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Retrieve the canonical name of the sample format.

```python
>>> AudioFormat('s16p').name
's16p'
```

--------------------------------

### Configure threading for video decoding

Source: https://pyav.basswood.io/docs/stable/cookbook/basics.html

Compares default slice-based threading with AUTO threading to improve decoding performance.

```python
import time

import av
import av.datasets

print("Decoding with default (slice) threading...")

container = av.open(
    av.datasets.curated("pexels/time-lapse-video-of-night-sky-857195.mp4")
)

start_time = time.time()
for packet in container.demux():
    print(packet)
    for frame in packet.decode():
        print(frame)

default_time = time.time() - start_time
container.close()


print("Decoding with auto threading...")

container = av.open(
    av.datasets.curated("pexels/time-lapse-video-of-night-sky-857195.mp4")
)

# !!! This is the only difference.
container.streams.video[0].thread_type = "AUTO"

start_time = time.time()
for packet in container.demux():
    print(packet)
    for frame in packet.decode():
        print(frame)

auto_time = time.time() - start_time
container.close()


print(f"Decoded with default threading in {default_time:.2f}s.")
print(f"Decoded with auto threading in {auto_time:.2f}s.")
```

--------------------------------

### Accessing Streams in a Container

Source: https://pyav.basswood.io/docs/stable/api/stream.html

Demonstrates various methods to retrieve streams from a container, including indexing and type-based filtering.

```python
# There are a few ways to pulling out streams.
first = container.streams[0]
video = container.streams.video[0]
audio = container.streams.get(audio=(0, 1))
```

--------------------------------

### av.video.frame.VideoFrame

Source: https://pyav.basswood.io/docs/stable/api/video.html

Constructor for creating a new video frame instance.

```APIDOC
## VideoFrame(width, height, format)

### Description
Creates a new single video frame instance.

### Parameters
- **width** (int) - Required - The width of the frame.
- **height** (int) - Required - The height of the frame.
- **format** (VideoFormat or str) - Optional - The format of the frame.
```

--------------------------------

### Record screen input with PyAV

Source: https://pyav.basswood.io/docs/stable/cookbook/basics.html

Captures video from a specified input device on MacOS and saves it to an MKV file. Requires identifying the correct device index via av.enumerate_input_devices.

```python
import av

av.logging.set_level(av.logging.VERBOSE)

"""
This is written for MacOS. Other platforms will need a different file, format pair.
You may need to change the file "1". Use this API to list all devices:

 av.enumerate_input_devices("avfoundation")

"""

input_ = av.open("1", format="avfoundation")
output = av.open("out.mkv", "w")

# Prefer x264, but use Apple hardware if not available.
try:
    encoder = av.Codec("libx264", "w").name
except av.FFmpegError:
    encoder = "h264_videotoolbox"

output_stream = output.add_stream(encoder, rate=30)
output_stream.width = input_.streams.video[0].width
output_stream.height = input_.streams.video[0].height
output_stream.pix_fmt = "yuv420p"

try:
    while True:
        try:
            for frame in input_.decode(video=0):
                packet = output_stream.encode(frame)
                output.mux(packet)
        except av.BlockingIOError:
            pass
except KeyboardInterrupt:
    print("Recording stopped by user")

packet = output_stream.encode(None)
output.mux(packet)

input_.close()
output.close()
```

--------------------------------

### av.audio.fifo.AudioFifo.read

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Read samples from the FIFO queue.

```APIDOC
## av.audio.fifo.AudioFifo.read(samples=0, partial=False)

### Description
Read samples from the queue. Returns a new AudioFrame or None if empty.

### Parameters
- **samples** (int) - Optional - The number of samples to pull; 0 gets all.
- **partial** (bool) - Optional - Allow returning less than requested.
```

--------------------------------

### Hardware Accelerated Encoding

Source: https://pyav.basswood.io/docs/stable/_sources/api/codec.rst.txt

Pass an HWAccel instance to add_stream when creating an output stream to enable hardware encoding. Software frames are uploaded to the device automatically.

```python
with av.open("output.mp4", "w") as container:
    stream = container.add_stream(
        "h264_videotoolbox", rate=30, hwaccel=HWAccel(device_type="videotoolbox")
    )
    ...
```

--------------------------------

### av.audio.resampler.AudioResampler

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Constructor for the AudioResampler class used to initialize audio resampling parameters.

```APIDOC
## class av.audio.resampler.AudioResampler(format=None, layout=None, rate=None, frame_size=None, options=None)

### Description
Initializes a new AudioResampler instance with the specified target audio parameters.

### Parameters
- **format** (AudioFormat) - Optional - The target format, or string that parses to one (e.g. "s16").
- **layout** (AudioLayout) - Optional - The target layout, or an int/string that parses to one (e.g. "stereo").
- **rate** (int) - Optional - The target sample rate.
- **frame_size** (int) - Optional - The number of samples per output frame.
- **options** (dict) - Optional - libswresample options passed to the underlying aresample filter.
```

--------------------------------

### Open with custom I/O

Source: https://pyav.basswood.io/docs/stable/api/_globals.html

Use the io_open parameter to provide a custom callable for handling file-like objects, often used with specific protocols.

```python
>>> av.open("customprotocol://manifest.mpd", "w", io_open=custom_io)
```

--------------------------------

### Check Codec Capabilities

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Shows how to use bitwise operations with the Capabilities enum to check for specific codec features.

```python
from av.codec import Codec, Capabilities

codec = Codec("h264", "w")

# Check if the codec can be fed a final frame with a smaller size.
# This can be used to prevent truncation of the last audio samples.
small_last_frame = bool(codec.capabilities & Capabilities.small_last_frame)
```

--------------------------------

### Enable PyAV Logging

Source: https://pyav.basswood.io/docs/stable/api/utils.html

Sets the logging level to VERBOSE to capture detailed FFmpeg logs during development.

```python
import av

av.logging.set_level(av.logging.VERBOSE)
```

--------------------------------

### av.video.reformatter.VideoReformatter.reformat

Source: https://pyav.basswood.io/docs/stable/api/video.html

Creates a new VideoFrame with the specified width, height, format, and colorspace settings. If no changes are required, the original frame is returned.

```APIDOC
## Method: reformat

### Description
Reformat a VideoFrame by adjusting its dimensions, pixel format, or colorspace. This method is most efficient when the same reformatter instance is reused for frames with identical target parameters.

### Parameters
- **frame** (VideoFrame) - Required - The source video frame to reformat.
- **width** (int) - Optional - New width, or None for the same width.
- **height** (int) - Optional - New height, or None for the same height.
- **format** (VideoFormat or str) - Optional - New pixel format, or None for the same format.
- **src_colorspace** (Colorspace or str) - Optional - Current colorspace, or None for the frame colorspace.
- **dst_colorspace** (Colorspace or str) - Optional - Desired colorspace, or None for the frame colorspace.
- **interpolation** (Interpolation or str) - Optional - Scaling algorithm to use (e.g., BILINEAR, LANCZOS).
- **src_color_range** (ColorRange or str) - Optional - Current color range.
- **dst_color_range** (ColorRange or str) - Optional - Desired color range.
- **dst_color_trc** (ColorTrc or int) - Optional - Desired transfer characteristic to tag on the output frame.
- **dst_color_primaries** (ColorPrimaries or int) - Optional - Desired color primaries to tag on the output frame.
- **threads** (int) - Optional - Number of threads for scaling; 0 for automatic selection.
```

--------------------------------

### Record facecam input with PyAV

Source: https://pyav.basswood.io/docs/stable/cookbook/basics.html

Captures video from a camera device with specific framerate and resolution settings. Uses container_options to configure the input stream parameters.

```python
import av

av.logging.set_level(av.logging.VERBOSE)


"""
This is written for MacOS. Other platforms will need to init `input_` differently.
You may need to change the file "0". Use this API to list all devices:

 av.enumerate_input_devices("avfoundation")

"""

input_ = av.open(
    "0",
    format="avfoundation",
    container_options={"framerate": "30", "video_size": "1920x1080"},
)
output = av.open("out.mkv", "w")

# Prefer x264, but use Apple hardware if not available.
try:
    encoder = av.Codec("libx264", "w").name
except av.FFmpegError:
    encoder = "h264_videotoolbox"

output_stream = output.add_stream(encoder, rate=30)
output_stream.width = input_.streams.video[0].width
output_stream.height = input_.streams.video[0].height
output_stream.pix_fmt = "yuv420p"

try:
    while True:
        try:
            for frame in input_.decode(video=0):
                packet = output_stream.encode(frame)
                output.mux(packet)
        except av.BlockingIOError:
            pass
except KeyboardInterrupt:
    print("Recording stopped by user")

packet = output_stream.encode(None)
output.mux(packet)

input_.close()
output.close()
```

--------------------------------

### SubtitleSet.create

Source: https://pyav.basswood.io/docs/stable/api/subtitles.html

Creates a SubtitleSet for encoding purposes.

```APIDOC
## SubtitleSet.create(text: bytes, start: int, end: int, pts: int = 0, subtitle_format: int = 1)

### Description
Creates a SubtitleSet ready for encoding with specified timing and format.

### Parameters
- **text** (bytes) - Required - The subtitle text in ASS dialogue format.
- **start** (int) - Required - Start display time as offset from pts.
- **end** (int) - Required - End display time as offset from pts.
- **pts** (int) - Optional - Presentation timestamp in stream time_base units.
- **subtitle_format** (int) - Optional - Subtitle format (default 1).
```

--------------------------------

### Set MacOS build flags

Source: https://pyav.basswood.io/docs/stable/overview/installation.html

Export environment variables to resolve potential compiler issues on MacOS.

```bash
export ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future
```

--------------------------------

### av.logging.restore_default_callback()

Source: https://pyav.basswood.io/docs/stable/api/utils.html

Reverts the logging system to the default FFmpeg behavior, which prints logs directly to the terminal.

```APIDOC
## av.logging.restore_default_callback()

### Description
Restores FFmpeg's default logging system, printing logs to the terminal.
```

--------------------------------

### av.logging.Capture(local=True)

Source: https://pyav.basswood.io/docs/stable/api/utils.html

A context manager used to capture logs during a block of code execution.

```APIDOC
## av.logging.Capture(local=True)

### Description
A context manager for capturing logs. Captured logs can be accessed via the `logs` attribute after the context block.

### Parameters
- **local** (bool) - Optional - If True, captures logs only from the current thread; otherwise, captures logs from all threads.
```

--------------------------------

### Create a Video Barcode with Numpy

Source: https://pyav.basswood.io/docs/stable/cookbook/numpy.html

Processes a video file to compute the mean color of each frame and stitches them into a single image representing the video's color progression over time.

```python
import numpy as np
from PIL import Image

import av
import av.datasets

container = av.open(
    av.datasets.curated("pexels/time-lapse-video-of-sunset-by-the-sea-854400.mp4")
)
container.streams.video[0].thread_type = "AUTO"  # Go faster!

columns = []
for frame in container.decode(video=0):
    print(frame)
    array = frame.to_ndarray(format="rgb24")

    # Collapse down to a column.
    column = array.mean(axis=1)

    # Convert to bytes, as the `mean` turned our array into floats.
    column = column.clip(0, 255).astype("uint8")

    # Get us in the right shape for the `hstack` below.
    column = column.reshape(-1, 1, 3)

    columns.append(column)

# Close the file, free memory
container.close()

full_array = np.hstack(columns)
full_img = Image.fromarray(full_array, "RGB")
full_img = full_img.resize((800, 200))
full_img.save("barcode.jpg", quality=85)
```

--------------------------------

### Capture Logs with Context Manager

Source: https://pyav.basswood.io/docs/stable/api/utils.html

Uses the Capture context manager to collect logs during a specific operation.

```python
with Capture() as logs:
    # Do something.
for log in logs:
    print(log.message)
```

--------------------------------

### VideoFrame.from_image

Source: https://pyav.basswood.io/docs/stable/api/video.html

Constructs a VideoFrame from a PIL Image.

```APIDOC
## VideoFrame.from_image(img)

### Description
Construct a frame from a PIL.Image.
```

--------------------------------

### add_data_stream(codec_name=None)

Source: https://pyav.basswood.io/docs/stable/api/container.html

Creates and returns a new data stream.

```APIDOC
## add_data_stream(codec_name=None)

### Description
Creates a new data stream and returns it.

### Parameters
- **codec_name** (str | None) - Optional - The name of the data codec (e.g. 'klv').
- **options** (dict) - Optional - Stream options.
```

--------------------------------

### Access AudioFormat bytes

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Retrieve the number of bytes per sample for a given audio format.

```python
>>> AudioFormat('s16p').bytes
2
```

--------------------------------

### add_stream(codec_name, rate=None, hwaccel=None)

Source: https://pyav.basswood.io/docs/stable/api/container.html

Creates a new stream from a codec name for video, audio, or subtitles.

```APIDOC
## add_stream(codec_name, rate=None, hwaccel=None)

### Description
Creates a new stream from a codec name and returns it. Supports video, audio, and subtitle streams.

### Parameters
- **codec_name** (str) - Required - The name of a codec.
- **options** (dict) - Optional - Stream options.
- **hwaccel** (HWAccel) - Optional - Settings for hardware-accelerated encoding.
- **kwargs** (dict) - Optional - Set attributes for the stream.
```

--------------------------------

### av.audio.frame.AudioFrame.from_ndarray

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Construct an AudioFrame from a numpy array.

```APIDOC
## av.audio.frame.AudioFrame.from_ndarray(array, format='s16', layout='stereo')

### Description
Constructs an AudioFrame object from a provided numpy array.

### Parameters
- **array** (numpy.ndarray) - Required - The input array containing audio data.
- **format** (str) - Optional - The audio sample format (default: 's16').
- **layout** (str) - Optional - The audio channel layout (default: 'stereo').
```

--------------------------------

### Check AudioFormat planar variant

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Verify if a format is planar or retrieve its planar variant.

```python
>>> fmt = AudioFormat('s16p')
>>> fmt.planar is fmt
True
```

--------------------------------

### av.audio.fifo.AudioFifo.read_many

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Read multiple frames from the FIFO queue.

```APIDOC
## av.audio.fifo.AudioFifo.read_many(samples, partial=False)

### Description
Read as many frames as possible from the queue.

### Parameters
- **samples** (int) - Required - How large the frames should be.
- **partial** (bool) - Optional - If partial frames should be returned.
```

--------------------------------

### VideoFrame.reformat

Source: https://pyav.basswood.io/docs/stable/api/video.html

Creates a new VideoFrame with specified dimensions and format.

```APIDOC
## VideoFrame.reformat(width=None, height=None, format=None, src_colorspace=None, dst_colorspace=None, interpolation=None, threads=None)

### Description
Create a new VideoFrame with the given width, height, format, and colorspace settings.
```

--------------------------------

### Check AudioFormat packed variant

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Verify if a format is packed or retrieve its packed variant.

```python
>>> fmt = AudioFormat('s16')
>>> fmt.packed is fmt
True
```

--------------------------------

### Catching PyAV Errors

Source: https://pyav.basswood.io/docs/stable/_sources/api/error.rst.txt

Demonstrates catching a specific PyAV error using a try-except block.

```python
try:
    do_something()
except av.FilterNotFoundError:
    handle_error()
```

--------------------------------

### Manage Container Lifecycle

Source: https://pyav.basswood.io/docs/stable/overview/caveats.html

Use a context manager to ensure the container is explicitly closed, preventing issues with reference cycles and garbage collection.

```python
with av.open(path) as container:
    # Do stuff with it.
```

--------------------------------

### av.codec.Codec

Source: https://pyav.basswood.io/docs/stable/api/codec.html

The Codec class represents an available codec, allowing users to inspect codec properties and create CodecContext instances.

```APIDOC
## class av.codec.Codec(name, mode='r')

### Description
Represents an available codec for encoding or decoding media.

### Parameters
- **name** (str) - Required - The codec name.
- **mode** (str) - Optional - 'r' for decoding or 'w' for encoding.

### Methods
- **create(kind=None)**: Create a CodecContext for this codec.

### Properties
- **is_decoder** (bool): Whether the codec is a decoder.
- **is_encoder** (bool): Whether the codec is an encoder.
- **name** (str): The name of the codec.
- **long_name** (str): The long name of the codec.
- **type** (str): The media type (e.g., 'audio', 'video', 'subtitle').
- **id** (int): The codec ID.
- **frame_rates** (list): Supported frame rates.
- **audio_rates** (list): Supported audio sample rates.
- **video_formats** (list): Supported video formats.
- **audio_formats** (list): Supported audio formats.
- **capabilities** (int): The capabilities bitmask of the codec.
```

--------------------------------

### av.codec.find_best_pix_fmt_of_list

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Finds the best pixel format to convert to from a given source format by wrapping the FFmpeg avcodec_find_best_pix_fmt_of_list function.

```APIDOC
## av.codec.find_best_pix_fmt_of_list(pix_fmts, src_pix_fmt, has_alpha=False)

### Description
Find the best pixel format to convert to given a source format. Wraps avcodec_find_best_pix_fmt_of_list.

### Parameters
- **pix_fmts** (Iterable) - Required - Iterable of pixel formats to choose from (str or VideoFormat).
- **src_pix_fmt** (str or VideoFormat) - Required - Source pixel format.
- **has_alpha** (bool) - Optional - Whether the source alpha channel is used.

### Returns
- **best_format** (VideoFormat | None) - The best pixel format found.
- **loss** (PixFmtLoss) - Flags describing what is lost during conversion.
```

--------------------------------

### add_stream_from_template(template, opaque=None)

Source: https://pyav.basswood.io/docs/stable/api/container.html

Creates a new stream based on an existing stream template.

```APIDOC
## add_stream_from_template(template: Stream, opaque: bool | None = None)

### Description
Creates a new stream from a template. Supports video, audio, subtitle, data and attachment streams.

### Parameters
- **template** (Stream) - Required - Copy codec from another Stream instance.
- **opaque** (bool) - Optional - If True, copy opaque data from the template’s codec context.
- **kwargs** (dict) - Optional - Set attributes for the stream.
```

--------------------------------

### Access AudioFormat bits

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Retrieve the number of bits per sample for a given audio format.

```python
>>> AudioFormat('s16p').bits
16
```

--------------------------------

### AudioResampler.resample()

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Method to convert the sample rate, channel layout, and/or format of an AudioFrame.

```APIDOC
## AudioResampler.resample(frame)

### Description
Converts the sample_rate, channel_layout and/or format of an AudioFrame.

### Parameters
- **frame** (AudioFrame) - Required - The frame to convert or None to flush.

### Returns
- A list of AudioFrame in new parameters. If nothing is to be done, returns the same frame as a single element list.
```

--------------------------------

### av.logging.set_level(level)

Source: https://pyav.basswood.io/docs/stable/api/utils.html

Sets the PyAV log level. Available constants include PANIC, FATAL, ERROR, WARNING, INFO, VERBOSE, DEBUG, or None.

```APIDOC
## av.logging.set_level(level)

### Description
Sets PyAV's log level. It is recommended to use `av.logging.VERBOSE` during development to ensure detailed error messages.

### Parameters
- **level** (constant) - Required - One of: PANIC, FATAL, ERROR, WARNING, INFO, VERBOSE, DEBUG, or None.
```

--------------------------------

### VideoFrame.to_image

Source: https://pyav.basswood.io/docs/stable/api/video.html

Converts the frame to a PIL Image.

```APIDOC
## VideoFrame.to_image(**kwargs)

### Description
Get an RGB PIL.Image of this frame. Requires PIL or Pillow to be installed.
```

--------------------------------

### Remuxing Subtitle Streams with PyAV

Source: https://pyav.basswood.io/docs/stable/cookbook/subtitles.html

Copies subtitle streams from a source container to a destination container without transcoding. Requires an input file with subtitle streams and a compatible output container format.

```python
import av

av.logging.set_level(av.logging.VERBOSE)

input_ = av.open("resources/webvtt.mkv")
output = av.open("remuxed.vtt", "w")

in_stream = input_.streams.subtitles[0]
out_stream = output.add_stream_from_template(in_stream)

for packet in input_.demux(in_stream):
    if packet.size == 0:
        continue
    packet.stream = out_stream
    output.mux(packet)

input_.close()
output.close()

print("Remuxing done")

with av.open("remuxed.vtt") as f:
    for subset in f.decode(subtitles=0):
        for sub in subset:
            print(sub.ass)
```

--------------------------------

### Increase audio speed with atempo filter

Source: https://pyav.basswood.io/docs/stable/cookbook/audio.html

Uses a filter graph to apply the atempo filter to an audio stream, doubling the playback speed before encoding to a new file.

```python
import av

av.logging.set_level(av.logging.VERBOSE)

input_file = av.open("input.wav")
output_file = av.open("output.wav", mode="w")

input_stream = input_file.streams.audio[0]
output_stream = output_file.add_stream("pcm_s16le", rate=input_stream.rate)

graph = av.filter.Graph()
graph.link_nodes(
    graph.add_abuffer(template=input_stream),
    graph.add("atempo", "2.0"),
    graph.add("abuffersink"),
).configure()

for frame in input_file.decode(input_stream):
    graph.push(frame)
    while True:
        try:
            for packet in output_stream.encode(graph.pull()):
                output_file.mux(packet)
        except (av.BlockingIOError, av.EOFError):
            break

# Flush the stream
for packet in output_stream.encode(None):
    output_file.mux(packet)

input_file.close()
output_file.close()
```

--------------------------------

### Finding the Best Stream

Source: https://pyav.basswood.io/docs/stable/api/stream.html

Retrieves the optimal stream of a specific type using the best() method.

```python
stream = container.streams.best("video")
```

--------------------------------

### av.container.InputContainer.demux

Source: https://pyav.basswood.io/docs/stable/api/container.html

Yields a series of Packet objects from the specified streams.

```APIDOC
## demux(streams=None, video=None, audio=None, subtitles=None, data=None)

### Description
Yields a series of `Packet` objects from the given set of `Stream` objects.

### Parameters
- **streams** (list) - Optional - List of streams to demux.
- **video** (bool) - Optional - Include video streams.
- **audio** (bool) - Optional - Include audio streams.
- **subtitles** (bool) - Optional - Include subtitle streams.
- **data** (bool) - Optional - Include data streams.
```

--------------------------------

### CodecContext.parse

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Parses a raw byte stream into a list of packets.

```APIDOC
## CodecContext.parse(raw_input=None)

### Description
Splits a byte stream into a list of Packet objects. It buffers partial packets until they are complete and assigns timing information where possible.

### Parameters
- **raw_input** (ByteSource) - Optional - A chunk of a byte-stream to process. Passing None or empty input flushes the parser's buffers.

### Returns
- **list** - A list of newly available Packet objects.
```

--------------------------------

### av.buffer.Buffer

Source: https://pyav.basswood.io/docs/stable/api/buffer.html

The Buffer class is a base class for objects supporting the buffer protocol. It provides properties to access the underlying memory and a method to update the buffer data.

```APIDOC
## class av.buffer.Buffer

### Description
A base class for PyAV objects which support the buffer protocol, such as Packet and Plane.

### Properties
- **buffer_ptr** (int) - The memory address of the buffer.
- **buffer_size** (int) - The size of the buffer.

### Methods
#### update(input)
Replace the data in this object with the given buffer. Accepts anything that supports the buffer protocol, e.g. bytes, NumPy arrays, other Buffer objects, etc.
```

--------------------------------

### BitStreamFilterContext.filter()

Source: https://pyav.basswood.io/docs/stable/api/bitstream.html

Processes a packet based on the filter description set during initialization.

```APIDOC
## BitStreamFilterContext.filter(packet)

### Description
Processes a packet based on the filter_description set during initialization. Multiple packets may be created.

### Parameters
- **packet** (Packet | None) - Optional - The packet to process.

### Returns
- **list[Packet]** - A list of processed packets.
```

--------------------------------

### Decode video frames to images

Source: https://pyav.basswood.io/docs/stable/_sources/index.rst.txt

Opens a video container and saves each decoded frame as a JPEG image.

```python
import av

av.logging.set_level(av.logging.VERBOSE)
container = av.open(path_to_video)

for index, frame in enumerate(container.decode(video=0)):
    frame.to_image().save(f"frame-{index:04d}.jpg")
```

--------------------------------

### Parse raw H.264 stream into packets

Source: https://pyav.basswood.io/docs/stable/cookbook/basics.html

Uses CodecContext.parse() to process raw byte chunks into packets and decode them into frames.

```python
import os
import subprocess

import av
import av.datasets

# We want an H.264 stream in the Annex B byte-stream format.
# We haven't exposed bitstream filters yet, so we're gonna use the `ffmpeg` CLI.
h264_path = "night-sky.h264"
if not os.path.exists(h264_path):
    subprocess.check_call(
        [
            "ffmpeg",
            "-i",
            av.datasets.curated("pexels/time-lapse-video-of-night-sky-857195.mp4"),
            "-vcodec",
            "copy",
            "-an",
            "-bsf:v",
            "h264_mp4toannexb",
            h264_path,
        ]
    )


fh = open(h264_path, "rb")

codec = av.CodecContext.create("h264", "r")

while True:
    chunk = fh.read(1 << 16)

    packets = codec.parse(chunk)
    print(f"Parsed {len(packets)} packets from {len(chunk)} bytes:")

    for packet in packets:
        print("   ", packet)

        frames = codec.decode(packet)
        for frame in frames:
            print("       ", frame)

    # We wait until the end to bail so that the last empty `buf` flushes
    # the parser.
    if not chunk:
        break
```

--------------------------------

### VideoFrame

Source: https://pyav.basswood.io/docs/stable/_sources/api/video.rst.txt

Represents a single video frame and provides methods for creation and conversion.

```APIDOC
## VideoFrame(width, height, format)

### Description
Creates a new video frame with the specified dimensions and format.

### Parameters
- **width** (int) - Required - The width of the frame.
- **height** (int) - Required - The height of the frame.
- **format** (VideoFormat or str) - Required - The format of the frame.

### Methods
- **reformat(...)**: Reformat the frame.
- **to_rgb()**: Convert frame to RGB.
- **to_image()**: Convert frame to an image object.
- **to_ndarray()**: Convert frame to a numpy array.
- **from_image(image)**: Create a frame from an image.
- **from_ndarray(array)**: Create a frame from a numpy array.
```

--------------------------------

### av.frame.Frame.make_writable

Source: https://pyav.basswood.io/docs/stable/api/frame.html

Ensures that the frame data is writable, copying the data to a new buffer if necessary.

```APIDOC
## Frame.make_writable()

### Description
Ensures that the frame data is writable. If the data is not currently writable, it copies the data to a new buffer.

### Method
Method call

### Returns
- **None** (void) - Modifies the frame in-place.
```

--------------------------------

### av.container.InputContainer.decode

Source: https://pyav.basswood.io/docs/stable/api/container.html

Yields a series of Frame objects from the specified streams.

```APIDOC
## decode(streams=None, video=None, audio=None, subtitles=None, data=None)

### Description
Yields a series of `Frame` objects from the given set of streams.

### Parameters
- **streams** (list) - Optional - List of streams to decode.
- **video** (bool) - Optional - Include video streams.
- **audio** (bool) - Optional - Include audio streams.
- **subtitles** (bool) - Optional - Include subtitle streams.
- **data** (bool) - Optional - Include data streams.
```

--------------------------------

### BitStreamFilterContext

Source: https://pyav.basswood.io/docs/stable/api/bitstream.html

Initializes a bitstream filter to modify packet data.

```APIDOC
## class av.bitstream.BitStreamFilterContext

### Description
Initializes a bitstream filter, which provides a way to directly modify packet data.

### Parameters
- **in_stream** (Stream, Codec, str, or None) - Required - Defines the input codec for the bitfilter.
- **out_stream** (Stream) - Required - A stream whose codec is overwritten using the output parameters from the bitfilter.
```

--------------------------------

### add_mux_stream(codec_name, rate=None)

Source: https://pyav.basswood.io/docs/stable/api/container.html

Creates a new stream for muxing pre-encoded data without a CodecContext.

```APIDOC
## add_mux_stream(codec_name, rate=None)

### Description
Creates a new stream for muxing pre-encoded data without creating a CodecContext. Use this when you want to mux packets that were already encoded externally.

### Parameters
- **codec_name** (str) - Required - The name of a codec.
- **kwargs** (dict) - Optional - Set attributes for the stream (e.g. width, height, time_base).
```

--------------------------------

### Accessing Stream Time Base

Source: https://pyav.basswood.io/docs/stable/_sources/api/time.rst.txt

Retrieve the time_base of a video stream from an opened container.

```python
>>> fh = av.open(path)
>>> video = fh.streams.video[0]

>>> video.time_base
Fraction(1, 25)
```

--------------------------------

### Convert VideoFrame to RGB

Source: https://pyav.basswood.io/docs/stable/api/video.html

Convert a frame to the RGB format using the to_rgb method.

```python
>>> frame = VideoFrame(1920, 1080)
>>> frame.format.name
'yuv420p'
>>> frame.to_rgb().format.name
'rgb24'
```

--------------------------------

### StreamContainer.best()

Source: https://pyav.basswood.io/docs/stable/api/stream.html

Finds the best stream of a specific type within the container.

```APIDOC
## StreamContainer.best(type, related=None)

### Description
Finds the best stream in the file for the given type, wrapping av_find_best_stream.

### Parameters
- **type** (Literal['video', 'audio', 'subtitle', 'attachment', 'data']) - Required - The type of stream to find.
- **related** (Stream) - Optional - A related stream to use as a reference.

### Returns
- **Stream | None** - The best stream of the specified type.
```

--------------------------------

### Save Keyframes with PyAV

Source: https://pyav.basswood.io/docs/stable/cookbook/basics.html

Optimizes decoding by setting skip_frame to NONKEY, allowing efficient extraction of keyframes from a video stream.

```python
import av
import av.datasets

content = av.datasets.curated("pexels/time-lapse-video-of-night-sky-857195.mp4")
with av.open(content) as container:
    # Signal that we only want to look at keyframes.
    stream = container.streams.video[0]
    stream.codec_context.skip_frame = "NONKEY"

    for i, frame in enumerate(container.decode(stream)):
        print(frame)
        frame.to_image().save(f"night-sky.{i:04d}.jpg", quality=80)
```

--------------------------------

### VideoStream.set_display_matrix

Source: https://pyav.basswood.io/docs/stable/api/video.html

Sets the display matrix for the video stream.

```APIDOC
## set_display_matrix(matrix)

### Description
Sets the display matrix written to the container as coded side data. Must be called before the first frame is encoded.

### Parameters
- **matrix** (sequence of 9 integers | None) - Required - The display matrix layout or None to clear.
```

--------------------------------

### Packet.decode()

Source: https://pyav.basswood.io/docs/stable/api/packet.html

Sends the packet's data to the decoder and returns a list of decoded frames.

```APIDOC
## Packet.decode()

### Description
Sends the packet's data to the decoder and returns a list of `AudioFrame`, `VideoFrame` or `SubtitleSet` objects.

### Returns
- **list** - A list of decoded frames or subtitle sets.
```

--------------------------------

### VideoFrame.from_ndarray

Source: https://pyav.basswood.io/docs/stable/api/video.html

Constructs a VideoFrame from a numpy array.

```APIDOC
## VideoFrame.from_ndarray(array, format='rgb24', channel_last=False)

### Description
Construct a frame from a numpy array.

### Parameters
- **array** (ndarray) - Required - The input numpy array.
- **format** (str) - Optional - The format of the frame.
- **channel_last** (bool) - Optional - If False, the shape for yuv444p/yuvj444p is (channels, height, width).
```

--------------------------------

### CodecContext.encode

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Encodes a frame into packets.

```APIDOC
## CodecContext.encode(frame=None)

### Description
Encodes a given Frame into a list of Packet objects.

### Parameters
- **frame** (Frame) - Optional - The frame to encode. If None, flushes the encoder.
```

--------------------------------

### VideoFrame.to_rgb

Source: https://pyav.basswood.io/docs/stable/api/video.html

Converts the current frame to an RGB format.

```APIDOC
## VideoFrame.to_rgb(**kwargs)

### Description
Get an RGB version of this frame. Any additional keyword arguments are passed to the reformatting process.
```

--------------------------------

### StreamContainer.get()

Source: https://pyav.basswood.io/docs/stable/api/stream.html

Retrieves a selection of streams from the container as a list based on indices or stream types.

```APIDOC
## StreamContainer.get(streams=None, video=None, audio=None, subtitles=None, data=None)

### Description
Get a selection of Stream objects as a list. Positional arguments can be integers (indices) or collections of integers. Keyword arguments allow filtering by stream type.

### Parameters
- **streams** (int | list | tuple) - Optional - Index or indices of streams to retrieve.
- **video** (int | list | tuple) - Optional - Index or indices of video streams.
- **audio** (int | list | tuple) - Optional - Index or indices of audio streams.
- **subtitles** (int | list | tuple) - Optional - Index or indices of subtitle streams.
- **data** (int | list | tuple) - Optional - Index or indices of data streams.
```

--------------------------------

### Demux packets from a container

Source: https://pyav.basswood.io/docs/stable/api/container.html

Iterate through packets yielded by the container's demux method, often followed by decoding the packets into frames.

```python
for packet in container.demux():
    # Do something with `packet`, often:
    for frame in packet.decode():
        # Do something with `frame`.
```

--------------------------------

### VideoStream.set_display_rotation

Source: https://pyav.basswood.io/docs/stable/api/video.html

Sets the container display matrix from rotation and flip parameters.

```APIDOC
## set_display_rotation(degrees, hflip=False, vflip=False)

### Description
Sets the container display matrix from a rotation and optional flips. Must be called before the first frame is encoded.

### Parameters
- **degrees** (number) - Required - Counter-clockwise rotation.
- **hflip** (boolean) - Optional - Horizontal flip.
- **vflip** (boolean) - Optional - Vertical flip.
```

--------------------------------

### CodecContext.flush_buffers

Source: https://pyav.basswood.io/docs/stable/api/codec.html

Resets the internal codec state.

```APIDOC
## CodecContext.flush_buffers()

### Description
Resets the internal codec state and discards all internal buffers. This should be called when seeking or switching streams.
```

--------------------------------

### av.audio.stream.AudioStream.encode

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Encodes an audio frame into a list of packets.

```APIDOC
## encode(frame: AudioFrame | None = None)

### Description
Encodes an AudioFrame and returns a list of Packet objects.

### Parameters
- **frame** (AudioFrame | None) - Optional - The audio frame to encode.

### Returns
- **list[Packet]** - A list of encoded packets.
```

--------------------------------

### av.audio.frame.AudioFrame.to_ndarray

Source: https://pyav.basswood.io/docs/stable/api/audio.html

Convert an AudioFrame to a numpy array.

```APIDOC
## av.audio.frame.AudioFrame.to_ndarray()

### Description
Returns the audio data of the frame as a numpy array. Requires numpy to be installed.
```

--------------------------------

### av.container.InputContainer.seek

Source: https://pyav.basswood.io/docs/stable/api/container.html

Seek to a frame nearest to the given timestamp.

```APIDOC
## seek(offset, backward=True, any_frame=False, stream=None)

### Description
Seek to a (key)frame nearest to the given timestamp.

### Parameters
- **offset** (int) - Required - Time to seek to, expressed in `stream.time_base` if `stream` is given, otherwise in `av.time_base`.
- **backward** (bool) - Optional - If there is not a (key)frame at the given offset, look backwards for it.
- **any_frame** (bool) - Optional - Seek to any frame, not just a keyframe.
- **stream** (Stream) - Optional - The stream whose `time_base` the `offset` is in.
```

--------------------------------

### Inspecting Packet and Frame Timestamps

Source: https://pyav.basswood.io/docs/stable/_sources/api/time.rst.txt

Access the time_base and timestamps (DTS/PTS) for specific packets and frames.

```python
>>> p, f = get_nth_packet_and_frame(fh, skip=1)

>>> p.time_base
Fraction(1, 25)
>>> p.dts
1

>>> f.time_base
Fraction(1, 25)
>>> f.pts
1
```
Tokens:
Raw