### AudioFormat Bytes Example

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

Demonstrates how to get the number of bytes per sample for an audio format.

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

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

### AudioFormat Bits Example

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

Demonstrates how to get the number of bits per sample for an audio format.

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

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

### Open Webcam on MacOS

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

Example of opening a webcam on macOS using the 'avfoundation' format.

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

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

### AudioFormat Name Example

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

Retrieves the canonical name of an audio sample format.

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

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

### Record Screen with AVFoundation (macOS)

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

Example for recording the screen using AVFoundation on macOS. Note that other platforms require different input files and formats. Use `av.enumerate_input_devices('avfoundation')` to list available 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")

```

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

### Recording a Facecam with PyAV

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

This example demonstrates how to record video from a device using PyAV. It prioritizes the x264 encoder but falls back to Apple's hardware encoder if unavailable. Ensure you have the correct input device specified, as '0' is platform-dependent.

```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()
```

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

### Create VideoFrame from PIL Image

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

Construct a VideoFrame from a PIL.Image object. Ensure PIL or Pillow is installed.

```python
static VideoFrame.from_image(_img_)
```

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

### Accessing Streams in a Container

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

Demonstrates various ways to access streams from a container. You can get the first stream by index, the first video stream, or select streams based on type and index.

```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))

```

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

### Accessing Streams

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

Demonstrates various ways to access streams from a container, including direct indexing, filtering by type, and using the `get` method.

```APIDOC
## Accessing Streams

### Description
There are a few ways to pull out streams from a container.

### Code Examples
```python
# Access the first stream by index
first = container.streams[0]

# Access the first video stream
video = container.streams.video[0]

# Get audio streams by codec and channel index
audio = container.streams.get(audio=(0, 1))
```
```

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

### Exception Handling Example

Source: https://pyav.basswood-io.com/docs/stable/api/error.html

Demonstrates how to catch PyAV exceptions, including specific FFmpeg errors like FilterNotFoundError, which can be caught using the base FFmpegError or the specific exception class.

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

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

### Create VideoFrame from NumPy Array

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

Construct a VideoFrame from a NumPy array. Specify the format and channel order. Ensure NumPy is installed.

```python
static VideoFrame.from_ndarray(_array_ , _format ='rgb24'_, _channel_last =False_)
```

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

### AudioFormat Planar Variant

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

Shows how to get the planar variant of an audio format. If the format is already planar, it returns itself.

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

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

### Getting Streams by Index or Type

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

Use the `get` method to retrieve specific streams. It accepts integer indices, lists/tuples of indices, or keyword arguments mapping stream types to indices or sets of indices.

```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})

```

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

### Generate Video from Numpy Array with PyAV

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

Creates a video file by encoding frames generated from Numpy arrays. This example demonstrates generating frames with sine wave patterns for color channels and writing them to an MP4 file.

```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()

```

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

### CodecContext Flags2

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

Get and set the flags2 bitmask of CodecContext.

```APIDOC
## CodecContext.flags2

### Description
Get and set the flags2 bitmask of CodecContext.

### Return Type
int

### Related Enum
`av.codec.context.Flags2`
```

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

### VideoFrame.to_image

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

Converts the VideoFrame to a PIL Image object. Requires PIL or Pillow to be installed. Additional keyword arguments are passed to VideoReformatter.reformat().

```APIDOC
## VideoFrame.to_image

### Description
Get an RGB `PIL.Image` of this frame. Any `**kwargs` are passed to `VideoReformatter.reformat()`.

### Method
`VideoFrame.to_image(_** kwargs_)

### Note
PIL or Pillow must be installed.
```

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

### CodecContext Flags

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

Get and set the flags bitmask of CodecContext.

```APIDOC
## CodecContext.flags

### Description
Get and set the flags bitmask of CodecContext.

### Return Type
int

### Related Enum
`av.codec.context.Flags`
```

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

### AudioFormat Packed Variant

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

Shows how to get the packed variant of an audio format. If the format is already packed, it returns itself.

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

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

### Codec Capabilities Check

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

Check specific codec capabilities using bitwise operations with the Capabilities enum. This example demonstrates how to check if a codec supports feeding a smaller last frame, useful for audio sample handling.

```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)
```

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

### Convert VideoFrame to RGB

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

Get an RGB version of a VideoFrame. Any keyword arguments are passed to VideoReformatter.reformat().

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

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

### Create a VideoFrame Instance

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

Instantiate a `VideoFrame` by providing its width, height, and pixel format. The format can be a string name or a `VideoFormat` object.

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

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

### get_last_error

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

Get the last log message that was at least at the ERROR level.

```APIDOC
## API Reference

av.logging.get_last_error()
    
Get the last log that was at least `ERROR`. 
```

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

### Create a VideoFormat Instance

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

Instantiate a `VideoFormat` object with a given pixel format name. Access its properties like `name`.

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

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

### Custom I/O with DASH

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

Demonstrates using custom I/O with DASH streams by adding a protocol prefix to the file path and providing a custom I/O callable.

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

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

### CodecContext Creation and Opening

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

Create and open a CodecContext for a given codec. The `open` method initializes the codec for encoding or decoding.

```python
CodecContext.create(codec, mode='r')
codec_context.open()
```

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

### Enabling Logging

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

Demonstrates how to enable verbose logging in PyAV for more detailed error messages during development.

```APIDOC
## Enabling Logging

You can hook into the logging system with Python by setting the log level:

```python
import av

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

PyAV hooks into that system to translate FFmpeg logs into Python’s logging system.
If you are not already using Python’s logging system, you can initialize it quickly with:

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

Note that handling logs with Python sometimes doesn’t play nicely with multi-threaded workflows. An alternative is `restore_default_callback()`.
This restores FFmpeg’s default logging system, which prints to the terminal. Like with setting the log level to `None`, this may also result in raised errors having less detailed messages.
```

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

### av.open()

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

The main entrypoint for opening files or streams with PyAV. It supports various parameters for specifying file paths, modes, formats, and advanced options for container and stream configurations.

```APIDOC
## av.open()

### Description
Main entrypoint to opening files/streams.

### Parameters
#### Path Parameters
- **file** (str) - Required - The file to open, which can be either a string or a file-like object.
- **mode** (str) - Required - "r" for reading and "w" for writing.

#### Query Parameters
- **format** (str) - Optional - Specific format to use. Defaults to autodect.
- **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; behaves like `str.encode` parameter. Defaults to "strict".
- **buffer_size** (int) - Optional - Size of buffer for Python input/output operations in bytes. Honored only when `file` is a file-like object. Defaults to 32768 (32k).
- **timeout** - Optional - How many seconds to wait for data before giving up, as a float, or a `(open timeout, read timeout)` tuple.
- **io_open** (callable) - Optional - Custom I/O callable for opening files/streams. This option is intended for formats that need to open additional file-like objects to `file` using custom I/O. The callable signature is `io_open(url: str, flags: int, options: dict)`, where `url` is the url to open, `flags` is a combination of AVIO_FLAG_* and `options` is a dictionary of additional options. The callable should return a file-like object.
- **hwaccel** (HWAccel) - Optional - Optional settings for hardware-accelerated decoding.

### Return Type
Container

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

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

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

### VideoFrame.to_ndarray

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

Converts the VideoFrame to a numpy array. Additional keyword arguments are passed to VideoReformatter.reformat(). Requires numpy to be installed.

```APIDOC
## VideoFrame.to_ndarray

### Description
Get a numpy array of this frame. Any `**kwargs` are passed to `VideoReformatter.reformat()`.

### Method
`VideoFrame.to_ndarray(_channel_last =False_, _** kwargs_)

### Parameters
#### Path Parameters
- **channel_last** (bool) - Optional - If True, the shape of array will be (height, width, channels) rather than (channels, height, width) for the “yuv444p” and “yuvj444p” formats.

### Note
Numpy must be installed.
For formats which return an array of `uint16`, `float16` or `float32`, the samples will be in the system’s native byte order.
For `pal8`, an `(image, palette)` tuple will be returned, with the palette being in ARGB (PyAV will swap bytes if needed).
For `gbrp` formats, channels are flipped to RGB order.
```

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

### av.container.OutputContainer.start_encoding

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

Writes the file header to the container. This is typically called automatically but can be invoked manually.

```APIDOC
## start_encoding

### Description
Write the file header!
Called automatically.
```

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

### Initialize Python Logging

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

Quickly initialize Python's built-in logging system if you are not already using it. This allows PyAV to translate FFmpeg logs into Python's logging framework.

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

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

### Decode and Save Video Frames

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

This snippet demonstrates how to open a video file, set logging to verbose, and decode video frames, saving each frame as a JPG image. It requires the 'av' library and a valid video file path.

```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")
```

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

### AudioFrame Handling

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

Details on creating and accessing audio frames, including conversion to numpy arrays.

```APIDOC
## Audio Frames

class av.audio.frame.AudioFrame

    format
        The audio sample format.
        Type:
            AudioFormat

    static from_ndarray(_array_ , _format ='s16'_, _layout ='stereo'_)
        Construct a frame from a numpy array.

    layout
        The audio channel layout.
        Type:
            AudioLayout

    planes
        A tuple of `AudioPlane`.
        Type:
            tuple

    rate
        Another name for `sample_rate`.

    sample_rate
        Sample rate of the audio data, in samples per second.
        Type:
            int

    samples
        Number of audio samples (per channel).
        Type:
            int

    to_ndarray()
        Get a numpy array of this frame.
        Note
        Numpy must be installed.
```

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

### Reformat VideoFrame

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

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

```python
VideoFrame.reformat(_width =None_, _height =None_, _format =None_, _src_colorspace =None_, _dst_colorspace =None_, _interpolation =None_, _threads =None_)
```

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

### AssSubtitle Methods

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

Methods for accessing ASS/SSA formatted subtitle data.

```APIDOC
## `AssSubtitle.ass()`

### Description
Returns the subtitle in the ASS/SSA format.

### Method
`ass() -> str`
```

```APIDOC
## `AssSubtitle.dialogue()`

### Description
Extracts the dialogue from the ASS format, stripping comments.

### Method
`dialogue() -> str`
```

```APIDOC
## `AssSubtitle.text()`

### Description
Provides access to the subtitle text. This attribute is rarely used; `dialogue` is usually preferred.

### Method
`text() -> str`
```

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

### Input Container Methods

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

Methods for interacting with input containers, including decoding, demuxing, and seeking.

```APIDOC
## Input Container Methods

### Description
Provides methods for reading and processing data from input containers.

### Attributes
- `InputContainer.bit_rate` (int): The bit rate of the input container.
- `InputContainer.duration` (float): The duration of the input container in seconds.
- `InputContainer.size` (int): The size of the input container in bytes.
- `InputContainer.start_time` (float): The start time of the input container in seconds.

### Methods
- `InputContainer.close()`: Closes the input container.
- `InputContainer.decode()`: Decodes packets from the container.
- `InputContainer.demux()`: Demultiplexes packets from the container.
- `InputContainer.seek(timestamp)`: Seeks to a specific timestamp in the container.
```

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

### Inspecting a Stream Object

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

Shows how to access basic information about a stream, such as its type, codec context, ID, and index within the container.

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

```

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

### SubtitleSet Creation and Properties

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

Methods and attributes for creating and managing SubtitleSet objects.

```APIDOC
## `SubtitleSet.create()`

### Description
Creates a SubtitleSet for encoding purposes.

### Method
`static create(_bytes text: bytes_, _int start: int_, _int end: int_, _int pts: int = 0_, _int subtitle_format: int = 1_) -> SubtitleSet`

### Parameters
* `text` (bytes): The subtitle text in ASS dialogue format (e.g., `b"0,0,Default,,0,0,0,,Hello World"`).
* `start` (int): Start display time as an offset from pts (typically 0).
* `end` (int): End display time as an offset from pts (i.e., duration).
* `pts` (int, optional): Presentation timestamp in stream time_base units. Defaults to 0.
* `subtitle_format` (int, optional): Subtitle format. Defaults to 1 (text).

### Returns
A SubtitleSet ready for encoding.

### Note
All timing values should be in stream time_base units. For MKV (time_base=1/1000), units are milliseconds. For MP4 (time_base=1/1000000), units are microseconds.
```

```APIDOC
## `SubtitleSet` Properties

### Description
Attributes of a `SubtitleSet` object.

### Properties
* `end_display_time` (int): The end display time of the subtitle set.
* `format` (int): The format of the subtitle set.
* `pts` (int): Presentation timestamp in stream time_base units. Same as packet pts.
* `rects` (list): A list of subtitle rectangles.
* `start_display_time` (int): The start display time of the subtitle set.
```

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

### Create Video Barcode with PyAV and Numpy

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

Generates a 'video barcode' by processing frames from a video file. It collapses each frame into a single column representing average color and then horizontally stacks these columns to create a visual representation of color changes over time. Requires Pillow for image saving.

```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)

```

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

### Output Container Methods

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

Methods for creating and writing to output containers, including adding streams and muxing.

```APIDOC
## Output Container Methods

### Description
Provides methods for creating, configuring, and writing data to output containers.

### Attributes
- `OutputContainer.default_audio_codec` (str): The default audio codec to use.
- `OutputContainer.default_subtitle_codec` (str): The default subtitle codec to use.
- `OutputContainer.default_video_codec` (str): The default video codec to use.
- `OutputContainer.supported_codecs` (list): A list of codecs supported by the output container.

### Methods
- `OutputContainer.add_attachment(attachment)`: Adds an attachment to the container.
- `OutputContainer.add_data_stream(**options)`: Adds a data stream to the container.
- `OutputContainer.add_mux_stream(stream)`: Adds a stream to be muxed.
- `OutputContainer.add_stream(codec_name, rate=None, **options)`: Adds a new stream to the container.
- `OutputContainer.add_stream_from_template(template_stream, codec_name=None, **options)`: Adds a stream based on a template.
- `OutputContainer.close()`: Closes the output container.
- `OutputContainer.mux(stream, packet)`: Muxes a packet into a stream.
- `OutputContainer.mux_one(packet)`: Muxes a single packet.
- `OutputContainer.start_encoding(stream)`: Starts encoding for a stream.
```

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

### adapt_level

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

Convert a library log level to a Python log level.

```APIDOC
## API Reference

av.logging.adapt_level(_int level: cython.int_)
    
Convert a library log level to a Python log level. 
```

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

### Container Format Details

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

Information about container formats, including their properties and supported operations.

```APIDOC
## Container Format Details

### Description
Represents a media container format, providing details about its capabilities and properties.

### Attributes
- `ContainerFormat.name` (str): The name of the format.
- `ContainerFormat.long_name` (str): The long name of the format.
- `ContainerFormat.options` (dict): Options supported by the format.
- `ContainerFormat.input` (bool): Whether the format supports input.
- `ContainerFormat.output` (bool): Whether the format supports output.
- `ContainerFormat.is_input` (bool): Alias for `input`.
- `ContainerFormat.is_output` (bool): Alias for `output`.
- `ContainerFormat.extensions` (list): File extensions associated with the format.
- `ContainerFormat.flags` (Flags): Flags associated with the format.
```

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

### AudioLayout Definitions

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

Information about audio channel layouts.

```APIDOC
## Audio Layouts

class av.audio.layout.AudioLayout

    channels
         

    name
        AudioLayout.name: str
        The canonical name of the audio layout.

    nb_channels
         

class av.audio.layout.AudioChannel(_name : 'str'_, _description : 'str'_)

    name: str
         

    description: str
```

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

### Catching PyAV Exceptions

Source: https://pyav.basswood-io.com/docs/stable/api/error.html

Demonstrates how to catch specific PyAV exceptions, such as `FilterNotFoundError`, which inherit from a common `FFmpegError`.

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

```

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

### Capture Logs with Context Manager

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

Use the `Capture` context manager to capture FFmpeg logs within a specific block of code.

```APIDOC
## API Reference

class av.logging.Capture(_bool local: cython.bint = True_)

    Bases: `object`
    A context manager for capturing logs. 

    Parameters:
        
    **local** (_bool_) – Should logs from all threads be captured, or just one this object is constructed in?
    e.g.:
    ```python
    with Capture() as logs:
        # Do something.
    for log in logs:
        print(log.message)
    ```

    logs
         
```

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

### Accessing Stream Time Base

Source: https://pyav.basswood-io.com/docs/stable/api/time.html

Demonstrates how to access the time base of a video stream after opening a container.

```APIDOC
## Overview

Time is expressed as integer multiples of arbitrary units of time called a `time_base`. There are different contexts that have different time bases: `Stream` has `Stream.time_base`, `CodecContext` has `CodecContext.time_base`, and `Container` has `av.TIME_BASE`.

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

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

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

### VideoFrame.reformat

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

Creates a new VideoFrame with specified dimensions, format, and colorspace. It leverages VideoReformatter for efficient reformatting.

```APIDOC
## VideoFrame.reformat

### Description
Create a new `VideoFrame` with the given width/height/format/colorspace. See also `VideoReformatter.reformat()` for arguments.

### Method
`VideoFrame.reformat(_width =None_, _height =None_, _format =None_, _src_colorspace =None_, _dst_colorspace =None_, _interpolation =None_, _threads =None_)

### Parameters
#### Path Parameters
- **_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 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 - The interpolation method to use, or `None` for `BILINEAR`.
- **_threads** (int) - Optional - How many threads to use for scaling, or `0` for automatic selection based on the number of available CPUs. Defaults to `0` (auto).
```

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

### Capture FFmpeg Logs with a Context Manager

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

Use the `Capture` context manager to capture FFmpeg logs within a specific block of code. Logs can be captured locally to the current thread or globally.

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

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

### VideoFrame.from_image()

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

Creates a VideoFrame from a PIL Image object.

```APIDOC
## Method: VideoFrame.from_image()

### Description
Creates a `VideoFrame` object from a PIL (Pillow) Image.

### Usage
```python
from PIL import Image

# Assuming 'pil_image' is a PIL Image object
video_frame = av.VideoFrame.from_image(pil_image)
```

### Parameters
- **image** (PIL.Image.Image): The PIL Image to convert.
- **format** (str, optional): The desired pixel format for the VideoFrame. Defaults to a suitable format based on the image.
```

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

### restore_default_callback

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

Reverts the logging system back to FFmpeg's default callback, which prints logs to the terminal.

```APIDOC
## API Reference

av.logging.restore_default_callback()
    
Revert back to FFmpeg’s log callback, which prints to the terminal. 
```

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

### Calculating Duration in Seconds

Source: https://pyav.basswood-io.com/docs/stable/api/time.html

Shows how to calculate the duration of a stream in seconds by multiplying the duration attribute by the stream's time base.

```APIDOC
## Overview

Attributes that represent time on those objects will be in that object’s `time_base`:

### Request Example
```python
>>> video.duration
168
>>> float(video.duration * video.time_base)
6.72
```
```

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

### AudioFifo Buffer Management

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

Methods for writing audio frames to and reading samples from an audio FIFO buffer.

```APIDOC
## Audio FIFOs

class av.audio.fifo.AudioFifo

    write(_frame_)
        Push a frame of samples into the queue.
        Parameters:
            **frame** (_AudioFrame_) – The frame of samples to push.
        The FIFO will remember the attributes from the first frame, and use those to populate all output frames.
        If there is a `pts` and `time_base` and `sample_rate`, then the FIFO will assert that the incoming timestamps are continuous.

    read(_samples =0_, _partial =False_)
        Read samples from the queue.
        Parameters:
            * **samples** (_int_) – The number of samples to pull; 0 gets all.
            * **partial** (_bool_) – Allow returning less than requested.
        Returns:
            New `AudioFrame` or `None` (if empty).
        If the incoming frames had valid a `time_base`, `sample_rate` and `pts`, the returned frames will have accurate timing.

    read_many(_samples_ , _partial =False_)
        Read as many frames as we can.
        Parameters:
            * **samples** (_int_) – How large for the frames to be.
            * **partial** (_bool_) – If we should return a partial frame.
        Returns:
            A `list` of `AudioFrame`.

    format
        The `AudioFormat` of this FIFO.

    layout
        The `AudioLayout` of this FIFO.

    pts_per_sample
         

    sample_rate
         

    samples
        Number of audio samples (per channel) in the buffer.

    samples_read
         

    samples_written
```

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

### Frame Time in Seconds

Source: https://pyav.basswood-io.com/docs/stable/api/time.html

Demonstrates the convenience of the `Frame.time` attribute, which provides the presentation time in seconds as a float.

```APIDOC
## Overview

For convenience, `Frame.time` is a `float` in seconds:

### Request Example
```python
>>> f.time
0.04
```
```

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

### Accessing Stream Time Base

Source: https://pyav.basswood-io.com/docs/stable/api/time.html

Open a media file and access the time_base of its video stream. This is useful for understanding the stream's temporal resolution.

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

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

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

### AudioFormat Descriptors

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

Details about audio sample formats, including bit depth, byte size, and planar/packed status.

```APIDOC
## Audio Formats

class av.audio.format.AudioFormat

    bits
        Number of bits per sample.
        ```
        >>> AudioFormat('s16p').bits
        16
        ```

    bytes
        Number of bytes per sample.
        ```
        >>> AudioFormat('s16p').bytes
        2
        ```

    container_name
        The name of a `ContainerFormat` which directly accepts this data.
        Raises:
            **ValueError** – when planar, since there are no such containers.

    is_packed
        Is this a packed format?
        Strictly opposite of `is_planar`.

    is_planar
        Is this a planar format?
        Strictly opposite of `is_packed`.

    name
        Canonical name of the sample format.
        ```
        >>> AudioFormat('s16p').name
        's16p'
        ```

    packed
        The packed variant of this format.
        Is itself when packed:
        ```
        >>> fmt = AudioFormat('s16')
        >>> fmt.packed is fmt
        True
        ```

    planar
        The planar variant of this format.
        Is itself when planar:
        ```
        >>> fmt = AudioFormat('s16p')
        >>> fmt.planar is fmt
        True
        ```
```

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

### VideoFrame.from_image

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

Constructs a VideoFrame from a PIL Image object.

```APIDOC
## VideoFrame.from_image

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

### Method
`static VideoFrame.from_image(_img_)
```

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

### Finding the Best Stream

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

The `best` method finds the most suitable stream of a given type, optionally using another stream as a reference. This is a convenient wrapper around `av_find_best_stream`.

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

```

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

### Control Emission of Identical Logs

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

Configure whether identical consecutive logs should be emitted. Set to True to emit all logs, or False to suppress repeated identical messages.

```python
av.logging.set_skip_repeated(False)
```

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

### av.container.OutputContainer.add_stream

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

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

```APIDOC
## add_stream

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

### Parameters
* **codec_name** (str) - The name of a codec.
* **options** (dict) - Stream options.
* **kwargs** - Set attributes for the stream.

### Return Type
The new `Stream`.
```

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

### Increase Audio Speed with atempo Filter

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

Applies the 'atempo' filter to double the audio playback speed. Ensure input and output files are correctly opened and streams are added before filtering.

```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()


```

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

### VideoReformatter.reformat()

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

Reformats a video frame using a VideoReformatter instance.

```APIDOC
## Method: VideoReformatter.reformat()

### Description
Applies the reformatting operations configured in the `VideoReformatter` instance to a given `VideoFrame`.

### Usage
```python
# Assuming 'reformatter' is a configured VideoReformatter instance
# and 'frame' is a VideoFrame object
new_frame = reformatter.reformat(frame)
```

### Parameters
- **frame** (VideoFrame): The input video frame to be reformatted.
```

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

### Reformat VideoFrame using VideoReformatter

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

Reformat a VideoFrame using a VideoReformatter object. This is efficient if reformatting to the same parameters repeatedly. Arguments include width, height, format, colorspace, color range, and interpolation.

```python
reformat(_VideoFrame frame: VideoFrame_, _width =None_, _height =None_, _format =None_, _src_colorspace =None_, _dst_colorspace =None_, _interpolation =None_, _src_color_range =None_, _dst_color_range =None_, _dst_color_trc =None_, _dst_color_primaries =None_, _threads =None_)
```

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

### av.container.OutputContainer.add_stream_from_template

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

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

```APIDOC
## add_stream_from_template

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

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

### Return Type
The new `Stream`.
```

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

### Compare Decoding Threading Performance

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

Compare the decoding speed between default (slice) threading and 'AUTO' threading. Enabling 'AUTO' threading can significantly speed up decoding by allowing multiple threads to decode independent frames, though it may introduce a larger delay.

```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("Decoded with default threading in {:.2f}s.".format(default_time))
print("Decoded with auto threading in {:.2f}s.".format(auto_time))

```

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

### VideoFrame.to_image()

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

Converts the video frame to a PIL Image object.

```APIDOC
## Method: VideoFrame.to_image()

### Description
Converts the video frame into a PIL (Pillow) Image object for easier manipulation and saving.

### Usage
```python
pil_image = frame.to_image()
```

### Parameters
- **width** (int, optional): Target width. Defaults to original width.
- **height** (int, optional): Target height. Defaults to original height.
- **interpolation** (Interpolation, optional): Interpolation method. Defaults to `Interpolation.BILINEAR`.
```

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

### set_level

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

Sets the log level for PyAV. Recommended to use `av.logging.VERBOSE` during development.

```APIDOC
## API Reference

av.logging.set_level(_level_)
    
Sets PyAV’s log level. It can be set to constants available in this module: `PANIC`, `FATAL`, `ERROR`, `WARNING`, `INFO`, `VERBOSE`, `DEBUG`, or `None` (the default).
PyAV defaults to totally ignoring all ffmpeg logs. This has the side effect of making certain Exceptions have no messages. It’s therefore recommended to use:
> av.logging.set_level(av.logging.VERBOSE)
When developing your application. 
```

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

### Codec Information Retrieval

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

Instantiate a Codec object to access its properties like name, type, and encoder status. This is useful for querying available codecs and their basic attributes.

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

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

### Enable Verbose Logging in PyAV

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

Set the PyAV log level to VERBOSE to capture detailed FFmpeg logs. This is recommended during development to see more information in error messages.

```python
import av

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

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

### Packet and Frame Timestamps

Source: https://pyav.basswood-io.com/docs/stable/api/time.html

Illustrates accessing the time base, DTS (decode timestamp), and PTS (presentation timestamp) for packets and frames.

```APIDOC
## Overview

`Packet` has a `Packet.pts` and `Packet.dts` (“presentation” and “decode” time stamps), and `Frame` has a `Frame.pts` (“presentation” time stamp). Both have a `time_base` attribute, but it defaults to the time base of the object that handles them. For packets that is streams. For frames it is streams when decoding, and codec contexts when encoding (which is strange, but it is what it is).

In many cases a stream has a time base of `1 / frame_rate`, and then its frames have incrementing integers for times (0, 1, 2, etc.). Those frames take place at `pts * time_base` or `0 / frame_rate`, `1 / frame_rate`, `2 / frame_rate`, etc..

### Request Example
```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
```
```

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

### Restore Default FFmpeg Logging Callback

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

Revert to FFmpeg's default logging behavior, which prints messages directly to the terminal. Note that this may result in less detailed error messages compared to using PyAV's logging.

```python
av.logging.restore_default_callback()
```

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

### VideoFrame.from_ndarray()

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

Creates a VideoFrame from a NumPy array.

```APIDOC
## Method: VideoFrame.from_ndarray()

### Description
Creates a `VideoFrame` object from a NumPy array.

### Usage
```python
import numpy as np

# Assuming 'ndarray_data' is a NumPy array
video_frame = av.VideoFrame.from_ndarray(ndarray_data, format='rgb24')
```

### Parameters
- **array** (np.ndarray): The NumPy array containing the video data.
- **format** (str): The pixel format of the data in the NumPy array (e.g., 'rgb24', 'gray').
- **layout** (str, optional): The memory layout of the array (e.g., 'rgb', 'bgr'). Defaults to None.
- **device** (str, optional): Specifies the device for the array (e.g., 'cuda'). Defaults to None.
```

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

### Plane Class

Source: https://pyav.basswood-io.com/docs/stable/api/plane.html

The Plane class is the base class for audio and video planes. It inherits from Buffer and is extended by AudioPlane and VideoPlane.

```APIDOC
class av.plane.Plane
    Bases: Buffer
    Base class for audio and video planes.
    See also `AudioPlane` and `VideoPlane`.
```

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

### av.codec.Codec

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

Represents an available codec and provides an interface to create a CodecContext for encoding or decoding.

```APIDOC
## av.codec.Codec

### Description
This object exposes information about an available codec, and an avenue to create a `CodecContext` to encode/decode directly.

### Parameters
* **name** (str) – The codec name.
* **mode** (str) – `'r'` for decoding or `'w'` for encoding.

### Attributes
* **name** (str) – The name of the codec.
* **type** (str) – The media type of this codec. E.g: `'audio'`, `'video'`, `'subtitle'`.
* **is_encoder** (bool) – True if the codec is an encoder.
* **is_decoder** (bool) – True if the codec is a decoder.
* **long_name** (str) – The long name of the codec.
* **id** (int) – The codec ID.
* **frame_rates** (list[fractions.Fraction] or None) – A list of supported frame rates.
* **audio_rates** (list[int] or None) – A list of supported audio sample rates.
* **video_formats** (list[VideoFormat] or None) – A list of supported video formats.
* **audio_formats** (list[AudioFormat] or None) – A list of supported audio formats.
* **properties** (av.codec.Properties) – Properties of the codec.
* **capabilities** (int) – Get the capabilities bitmask of the codec. This can be used to check specific codec features by performing bitwise operations with the `Capabilities` enum values.

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

### Example
```python
import av

codec = av.codec.Codec('mpeg4', 'r')
print(codec.name)
print(codec.type)
print(codec.is_encoder)

# Check codec capabilities
from av.codec import Capabilities
if codec.capabilities & Capabilities.small_last_frame:
    print("Codec supports small last frame.")
```
```

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

### av.container.OutputContainer.mux

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

Muxes a sequence of packets into the container.

```APIDOC
## mux

### Description
Muxes a sequence of packets into the container.

### Parameters
* **packets** - An iterable of `Packet` objects to mux.
```

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

### Set PyAV Log Level

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

Set PyAV's log level to control the verbosity of FFmpeg logs. Available levels include PANIC, FATAL, ERROR, WARNING, INFO, VERBOSE, DEBUG, or None. Defaults to ignoring all logs.

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