### Install SDL2 Development Packages (Ubuntu)

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/installation.md

Installs the development libraries for SDL2 and SDL2_mixer using apt-get on Ubuntu systems. These are essential for multimedia functionalities that ffpyplayer might utilize.

```bash
sudo apt-get update
sudo apt-get -y install libsdl2-dev libsdl2-mixer-dev
```

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

### Simple Video Transcoding with ffpyplayer

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/examples.md

This example shows a basic video transcoding process using ffpyplayer. It reads frames from an input file using MediaPlayer and writes them to an output file using MediaWriter, with options to disable audio and synchronize on video.

```python
from ffpyplayer.player import MediaPlayer
from ffpyplayer.writer import MediaWriter
import time, weakref

# only video
ff_opts={'an':True, 'sync':'video'}
player = MediaPlayer(filename, ff_opts=ff_opts)
# wait for size to be initialized (todo: add timeout and check for quitting)
while player.get_metadata()['src_vid_size'] == (0, 0):
    time.sleep(0.01)

frame_size = player.get_metadata()['src_vid_size']
# use the same size as the inputs
out_opts = {'pix_fmt_in':'rgb24', 'width_in':frame_size[0],
            'height_in':frame_size[1], 'codec':'rawvideo',
            'frame_rate':(30, 1)}

writer = MediaWriter(filename_out, [out_opts])
while 1:
    frame, val = player.get_frame()
    if val == 'eof':
        break
    elif frame is None:
        time.sleep(0.01)
    else:
        img, t = frame
        writer.write_frame(img=img, pts=t, stream=0)
```

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

### Get FFmpeg Codec and Format Info with ffpyplayer.tools

Source: https://context7.com/matham/ffpyplayer/llms.txt

Provides examples of using functions from the ffpyplayer.tools module to query FFmpeg capabilities. This includes listing available encoding and decoding codecs, identifying video encoders and audio decoders, and retrieving information about supported pixel formats and frame rates.

```python
from ffpyplayer.tools import (
    codecs_enc, codecs_dec, pix_fmts, formats_in, formats_out,
    get_codecs, get_fmts, get_format_codec,
    get_supported_framerates, get_supported_pixfmts, get_best_pix_fmt,
    set_loglevel, set_log_callback, loglevels
)

# Available codecs
print("Encoding codecs:", codecs_enc[:10])
print("Decoding codecs:", codecs_dec[:10])

# Get specific codec types
video_encoders = get_codecs(encode=True, video=True)
audio_decoders = get_codecs(decode=True, audio=True)
print(f"Video encoders: {len(video_encoders)}")
print(f"Audio decoders: {len(audio_decoders)}")

# Get supported pixel formats for a codec
# Example: Get supported pixel formats for 'libx264' encoder
# supported_pix_fmts = get_supported_pixfmts(codec='libx264', encode=True)
# print(f"Supported pixel formats for libx264: {supported_pix_fmts}")

# Get best pixel format for a given format
# Example: Find best pixel format for 'yuv420p'
# best_pix_fmt = get_best_pix_fmt('yuv420p')
# print(f"Best pixel format for yuv420p: {best_pix_fmt}")

# Get format codec information
# Example: Get codec for a specific format
# format_codec = get_format_codec('mp4')
# print(f"Codec for mp4 format: {format_codec}")

# Logging control (example)
# set_loglevel({'ffpyplayer': 'debug'})
# def my_log_callback(level, msg):
#     print(f"LOG [{level}]: {msg}")
# set_log_callback(my_log_callback)
# print(f"Available log levels: {loglevels}")
```

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

### Compress Video to H.264 with MediaWriter

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/examples.md

This example demonstrates writing compressed H.264 video to a file using ffpyplayer. It configures the MediaWriter with the 'libx264' codec, specifies compression options like preset and CRF, and includes metadata. The output file size is significantly smaller compared to raw video.

```python
from ffpyplayer.writer import MediaWriter
from ffpyplayer.tools import get_supported_pixfmts, get_supported_framerates
from ffpyplayer.pic import Image

# make sure the pixel format and rate are supported.
print get_supported_pixfmts('libx264', 'rgb24')
#['yuv420p', 'yuvj420p', 'yuv422p', 'yuvj422p', 'yuv444p', 'yuvj444p', 'nv12', 'nv16']
print get_supported_framerates('libx264', (5, 1))
#[]
w, h = 640, 480
out_opts = {'pix_fmt_in':'rgb24', 'width_in':w, 'height_in':h, 'codec':'libx264',
            'frame_rate':(5, 1)}

# use the following libx264 compression options
lib_opts = {'preset':'slow', 'crf':'22'}
# set the following metadata (ffmpeg doesn't always support writing metadata)
metadata = {'title':'Singing in the sun', 'author':'Rat', 'genre':'Animal sounds'}

# write using yuv420p frames into a two stream h264 codec, mp4 file where the output
# is half the input size for both streams.
writer = MediaWriter('output.avi', [out_opts] * 2, fmt='mp4',
                     width_out=w/2, height_out=h/2, pix_fmt_out='yuv420p',
                     lib_opts=lib_opts, metadata=metadata)

# Construct images
size = w * h * 3
buf = bytearray([int(x * 255 / size) for x in range(size)])
img = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))

buf = bytearray([int((size - x) * 255 / size) for x in range(size)])
img2 = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))

for i in range(20):
    writer.write_frame(img=img, pts=i / 5., stream=0)  # stream 1
    writer.write_frame(img=img2, pts=i / 5., stream=1)  # stream 2
```

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

### Complex Video Transcoding with ffpyplayer

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/examples.md

This example demonstrates a more complex video transcoding scenario with ffpyplayer. It reads video frames, converts them to 'yuv420p' format, and resizes the output frames to half the original width and height before writing to a new file.

```python
from ffpyplayer.player import MediaPlayer
from ffpyplayer.tools import free_frame_ref
from ffpyplayer.writer import MediaWriter
import time, weakref

# only video, output yuv420p frames
ff_opts={'an':True, 'sync':'video', 'out_fmt':'yuv420p'}
player = MediaPlayer(filename, ff_opts=ff_opts)
# wait for size to be initialized
while player.get_metadata()['src_vid_size'] == (0, 0):
    time.sleep(0.01)

frame_size = player.get_metadata()['src_vid_size']
# use the half the size for the output as the input
out_opts = {'pix_fmt_in':'yuv420p', 'width_in':frame_size[0],
            'height_in':frame_size[1], 'codec':'rawvideo',
            'frame_rate':(30, 1), 'width_out':frame_size[0] / 2,
            'height_out':frame_size[1] / 2}

writer = MediaWriter(filename_out, [out_opts])
while 1:
    frame, val = player.get_frame()
    if val == 'eof':
        break
    elif frame is None:
        time.sleep(0.01)
    else:
        img, t = frame
        writer.write_frame(img=img, pts=t, stream=0)
```

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

### Save Image to Disk using ffpyplayer

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/examples.md

This example demonstrates saving an image to disk using ffpyplayer's MediaWriter. It covers creating an image, determining supported pixel formats for a given codec (TIFF in this case), and writing the frame to a file, including options for compression.

```python
from ffpyplayer.pic import Image, SWScale
from ffpyplayer.tools import get_supported_pixfmts

# create image
w, h = 500, 100
fmt = 'rgb24'
size = w * h * 3
buf = bytearray([int(x * 255 / size) for x in range(size)])
img = Image(plane_buffers=[buf], pix_fmt=fmt, size=(w, h))
codec = 'tiff'  # we'll encode it using the tiff codec

# make sure the output codec supports the input pixel format type
# otherwise, convert it to the best pixel format
ofmt = get_supported_pixfmts(codec, fmt)[0]
if ofmt != fmt:
    sws = SWScale(w, h, fmt, ofmt=ofmt)
    img = sws.scale(img)
    fmt = ofmt

out_opts = {'pix_fmt_in': fmt, 'width_in': w, 'height_in': h,
            'frame_rate': (30, 1), 'codec': codec}
writer = MediaWriter('myfile.tiff', [out_opts])
writer.write_frame(img=img, pts=0, stream=0)
writer.close()

# to save the file as a compressed tiff using lzw
writer = MediaWriter('myfile.tiff', [out_opts], lib_opts={'compression_algo': 'lzw'})
writer.write_frame(img=img, pts=0, stream=0)
writer.close()
```

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

### Create and Get Image Buffer Sizes with ffpyplayer.pic.Image

Source: https://context7.com/matham/ffpyplayer/llms.txt

This snippet demonstrates the usage of the Image class from ffpyplayer.pic for creating and manipulating image data. It shows how to get the required buffer sizes for different pixel formats (RGB24 and YUV420P) using the get_image_size function, which is crucial for allocating memory for image planes. Dependencies include ffpyplayer.pic.

```Python
from ffpyplayer.pic import Image, get_image_size
import copy

w, h = 640, 480

# Get buffer sizes for different pixel formats
print("RGB24 buffer sizes:", get_image_size('rgb24', w, h))
# Output: (921600, 0, 0, 0) - single plane

print("YUV420P buffer sizes:", get_image_size('yuv420p', w, h))
# Output: (307200, 76800, 76800, 0) - three planes
```

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

### Write Video File with FFPyPlayer

Source: https://github.com/matham/ffpyplayer/blob/master/README.rst

This example demonstrates how to use MediaWriter to create a video file. It defines output options including pixel format, dimensions, codec, and frame rate. It then constructs an image and writes multiple frames to the specified output file with corresponding presentation timestamps (pts).

```python
from ffpyplayer.writer import MediaWriter
from ffpyplayer.pic import Image

w, h = 640, 480
# write at 5 fps.
out_opts = {'pix_fmt_in':'rgb24', 'width_in':w, 'height_in':h,
    'codec':'rawvideo', 'frame_rate':(5, 1)}
writer = MediaWriter('output.avi', [out_opts])

# Construct image
size = w * h * 3
buf = bytearray([int(x * 255 / size) for x in range(size)])
img = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))

for i in range(20):
    writer.write_frame(img=img, pts=i / 5., stream=0)
```

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

### Convert Image Formats with ffpyplayer

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/examples.md

This example shows how to convert an image from one pixel format to another using ffpyplayer's Image and SWScale classes. It creates a raw RGB image buffer and then scales it to YUV420p format.

```python
from ffpyplayer.pic import Image, SWScale
w, h = 500, 100
size = w * h * 3
buf = bytearray([int(x * 255 / size) for x in range(size)])

img = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))
sws = SWScale(w, h, img.get_pixel_format(), ofmt='yuv420p')

img2 = sws.scale(img)
img2.get_pixel_format()
'yuv420p'
planes = img2.to_bytearray()
map(len, planes)
[50000, 12500, 12500, 0]
```

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

### Play Webcam Stream using DirectShow on Windows

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/examples.md

This example demonstrates how to play a webcam stream on Windows using ffpyplayer's MediaPlayer with DirectShow. It configures options like framerate, video size, and pixel format, and continuously retrieves frames from the webcam.

```python
# see http://ffmpeg.org/ffmpeg-formats.html#Format-Options for rtbufsize
# lets use the yuv420p, 320x240, 30fps
# 27648000 = 320*240*3 at 30fps, for 4 seconds.
# see http://ffmpeg.org/ffmpeg-devices.html#dshow for video_size, and framerate
lib_opts = {'framerate':'30', 'video_size':'320x240',
'pixel_format': 'yuv420p', 'rtbufsize':'27648000'}
ff_opts = {'f':'dshow'}
player = MediaPlayer('video=Logitech HD Webcam C525:audio=Microphone (HD Webcam C525)',
                     ff_opts=ff_opts, lib_opts=lib_opts)

while 1:
    frame, val = player.get_frame()
    if val == 'eof':
        break
    elif frame is None:
        time.sleep(0.01)
    else:
        img, t = frame
        print val, t, img.get_pixel_format(), img.get_buffer_size()
        time.sleep(val)
0.0 264107.429 rgb24 (230400, 0, 0, 0)
0.0 264108.364 rgb24 (230400, 0, 0, 0)
0.0790016651154 264108.628 rgb24 (230400, 0, 0, 0)
0.135997533798 264108.764 rgb24 (230400, 0, 0, 0)
0.274529457092 264108.897 rgb24 (230400, 0, 0, 0)
0.272421836853 264109.028 rgb24 (230400, 0, 0, 0)
0.132406949997 264109.164 rgb24 (230400, 0, 0, 0)
...

# NOTE, by default the output was rgb24. To keep the output format the
# same as the input, do ff_opts['out_fmt'] = 'yuv420p'
```

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

### Install Python3 Development Headers (Ubuntu)

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/installation.md

Installs the Python 3 development headers package on Ubuntu. These headers are required for compiling Python extensions, which is necessary for libraries like ffpyplayer that interface with Python.

```bash
sudo apt-get install python3-dev
```

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

### Set FFmpeg and SDL2 Root Directories

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/installation.md

Defines environment variables FFMPEG_ROOT and SDL_ROOT to point to the root directories of FFmpeg and SDL2 installations, respectively. These directories should contain 'include' and 'lib' subdirectories for headers and compiled libraries.

```bash
export FFMPEG_ROOT=/path/to/ffmpeg/root
export SDL_ROOT=/path/to/sdl2/root
```

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

### Write H.264 Compressed Video with MediaWriter

Source: https://context7.com/matham/ffpyplayer/llms.txt

This example demonstrates writing compressed H.264 video to an MP4 file using MediaWriter. It includes checks for supported pixel formats and frame rates, configures codec-specific options like preset and CRF, and sets file metadata. The code generates gradient frames and writes them to the output file, ensuring the output pixel format is compatible with H.264. Dependencies include ffpyplayer.writer, ffpyplayer.pic, and ffpyplayer.tools.

```Python
from ffpyplayer.writer import MediaWriter
from ffpyplayer.pic import Image
from ffpyplayer.tools import get_supported_pixfmts, get_supported_framerates

w, h = 1280, 720
codec = 'libx264'

# Check supported formats for codec
print("Supported pixel formats:", get_supported_pixfmts(codec, 'rgb24'))
# Output: ['yuv420p', 'yuvj420p', 'yuv422p', ...] - rgb24 converted to yuv420p

print("Supported frame rates:", get_supported_framerates(codec, (30, 1)))
# Output: [] - empty means all rates supported

out_opts = {
    'pix_fmt_in': 'rgb24',
    'width_in': w,
    'height_in': h,
    'codec': codec,
    'frame_rate': (30, 1)
}

# Codec-specific options
lib_opts = {
    'preset': 'medium',         # Encoding speed preset
    'crf': '23',                # Quality (0-51, lower is better)
    'tune': 'film'              # Optimize for film content
}

# File metadata
metadata = {
    'title': 'My Video',
    'author': 'FFPyPlayer',
    'comment': 'Generated with FFPyPlayer'
}

writer = MediaWriter(
    'output.mp4',
    [out_opts],
    fmt='mp4',                  # Force MP4 format
    pix_fmt_out='yuv420p',      # Output as YUV420P for H.264
    lib_opts=lib_opts,
    metadata=metadata,
    overwrite=True              # Overwrite existing file
)

# Generate and write frames
size = w * h * 3
for i in range(150):  # 5 seconds at 30fps
    # Create gradient frame
    buf = bytearray([int((x + i * 1000) % 256) for x in range(size)])
    img = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))
    writer.write_frame(img=img, pts=i / 30.0, stream=0)

writer.close()
print("Video saved as output.mp4")
```

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

### Set FFmpeg Shared Library Path

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/installation.md

Configures the LD_LIBRARY_PATH environment variable to include the directory where FFmpeg shared libraries are installed. This allows the system to find and load the FFmpeg libraries at runtime.

```bash
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/ffmpeg_build/lib
```

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

### Convert Images with ffpyplayer.pic.SWScale

Source: https://context7.com/matham/ffpyplayer/llms.txt

Utilizes the SWScale class for converting images between different pixel formats and sizes using FFmpeg's swscale library. Examples include resizing, format conversion (e.g., RGB24 to YUV420P, RGB24 to grayscale), and scaling into pre-allocated buffers for performance.

```python
from ffpyplayer.pic import Image, SWScale
import math

w, h = 500, 100

# Create source RGB image
size = w * h * 3
buf = bytearray([int(x * 255 / size) for x in range(size)])
img = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))

# Convert to different size (half width, maintain aspect)
sws_resize = SWScale(w, h, img.get_pixel_format(), ow=w//2, oh=-1)
img_resized = sws_resize.scale(img)
print(f"Resized: {img_resized.get_size()}")  # (250, 50)

# Use source dimensions
sws_same = SWScale(w, h, img.get_pixel_format(), ow=0, oh=0)
img_same = sws_same.scale(img)
print(f"Same size: {img_same.get_size()}")  # (500, 100)

# Convert RGB24 to YUV420P
sws_yuv = SWScale(w, h, 'rgb24', ofmt='yuv420p')
img_yuv = sws_yuv.scale(img)
print(f"YUV format: {img_yuv.get_pixel_format()}")
print(f"YUV planes: {[len(p) for p in img_yuv.to_bytearray()]}")

# Convert RGB24 to grayscale
sws_gray = SWScale(w, h, 'rgb24', ofmt='gray')
img_gray = sws_gray.scale(img)
print(f"Gray format: {img_gray.get_pixel_format()}")

# Scale into pre-allocated buffer (for performance)
align = lambda x: int(math.ceil(x / 32.0) * 32)
out_w, out_h = w // 2, h // 2
linesize = [align(out_w * 3)]
dst_img = Image(pix_fmt='rgb24', size=(out_w, out_h), linesize=linesize)

sws_prealoc = SWScale(w, h, 'rgb24', ow=out_w, oh=out_h)
result = sws_prealoc.scale(img, dst=dst_img)
print(f"Pre-allocated result: {result.get_size()}, aligned: {result.get_linesizes(keep_align=True)}")
```

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

### Write Uncompressed Video Frames with MediaWriter

Source: https://context7.com/matham/ffpyplayer/llms.txt

This example shows how to use the MediaWriter class to write uncompressed video frames to an AVI file. It configures input and output options, including pixel format, dimensions, and frame rate. The code demonstrates creating sample images and writing them to multiple streams within the output file. Dependencies include ffpyplayer.writer and ffpyplayer.pic.

```Python
from ffpyplayer.writer import MediaWriter
from ffpyplayer.pic import Image

w, h = 640, 480

# Configure output stream
out_opts = {
    'pix_fmt_in': 'rgb24',     # Input pixel format from Image
    'width_in': w,              # Input width
    'height_in': h,             # Input height
    'pix_fmt_out': 'rgb24',     # Output pixel format (optional, defaults to input)
    'width_out': w // 2,        # Output width (optional, defaults to input)
    'height_out': h // 2,       # Output height (optional, defaults to input)
    'codec': 'rawvideo',        # Codec to use
    'frame_rate': (30, 1)       # 30 fps (numerator, denominator)
}

# Create writer with two identical streams
writer = MediaWriter('output.avi', [out_opts, out_opts])

# Get actual configuration used
print(writer.get_configuration())

# Create sample images
size = w * h * 3
buf1 = bytearray([int(x * 255 / size) for x in range(size)])
buf2 = bytearray([int((size - x) * 255 / size) for x in range(size)])

img1 = Image(plane_buffers=[buf1], pix_fmt='rgb24', size=(w, h))
img2 = Image(plane_buffers=[buf2], pix_fmt='rgb24', size=(w, h))

# Write 60 frames (2 seconds at 30fps)
for i in range(60):
    pts = i / 30.0  # Timestamp in seconds
    bytes_written = writer.write_frame(img=img1, pts=pts, stream=0)
    bytes_written = writer.write_frame(img=img2, pts=pts, stream=1)
    print(f"Written approximately {bytes_written} bytes")

writer.close()
```

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

### Configure Advanced Playback and Metadata Retrieval

Source: https://context7.com/matham/ffpyplayer/llms.txt

Demonstrates advanced configuration of MediaPlayer using ff_opts and lib_opts. It includes event callbacks, metadata retrieval, and dynamic playback control methods like seeking and volume adjustment.

```python
from ffpyplayer.player import MediaPlayer
import time

ff_opts = {'out_fmt': 'yuv420p', 'x': 640, 'y': 480, 'paused': True, 'ss': 10.0, 't': 60.0, 'loop': 2, 'an': False, 'vn': False, 'sync': 'audio', 'volume': 0.8, 'vf': 'hflip'}
lib_opts = {'threads': 'auto', 'lowres': '0'}

def callback(selector, value):
    if selector == 'eof':
        print("End of file reached")

player = MediaPlayer('/path/to/video.mp4', callback=callback, ff_opts=ff_opts, lib_opts=lib_opts, loglevel='warning')
metadata = player.get_metadata()
player.set_pause(False)
player.set_volume(0.5)
player.seek(30.0, relative=False)

while True:
    frame, val = player.get_frame()
    if val == 'eof': break
    elif frame is None: time.sleep(0.01)
    else:
        img, t = frame
        print(f"PTS: {t}, Size: {img.get_buffer_size()}")
        time.sleep(val)
player.close_player()
```

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

### Save Images to Disk

Source: https://context7.com/matham/ffpyplayer/llms.txt

Illustrates how to create a raw image buffer, convert it to a supported pixel format using SWScale, and save it as an image file like TIFF using MediaWriter.

```python
from ffpyplayer.writer import MediaWriter
from ffpyplayer.pic import Image, SWScale
from ffpyplayer.tools import get_supported_pixfmts
img = Image(plane_buffers=[bytearray(800*600*3)], pix_fmt='rgb24', size=(800, 600))
codec = 'tiff'
out_fmt = get_supported_pixfmts(codec, 'rgb24')[0]
sws = SWScale(800, 600, 'rgb24', ofmt=out_fmt)
img = sws.scale(img)
writer = MediaWriter('output.tiff', [{'codec': codec, 'width_in': 800, 'height_in': 600}], overwrite=True)
writer.write_frame(img=img, pts=0, stream=0)
writer.close()
```

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

### Inspect Media Formats and Codec Capabilities

Source: https://context7.com/matham/ffpyplayer/llms.txt

Demonstrates how to retrieve supported input/output formats, identify the best codec for specific file extensions, and query supported pixel formats and frame rates for video processing.

```python
print("Input formats:", formats_in[:10])
print("Output formats:", formats_out[:10])
fmts, names, exts = get_fmts(output=True)
for f, n, e in zip(fmts[:5], names[:5], exts[:5]):
    print(f"Format: {f}, Name: {n}, Extensions: {e}")
print("Best codec for .mkv:", get_format_codec('output.mkv'))
print("MPEG1 frame rates:", get_supported_framerates('mpeg1video'))
print("x264 pixel formats:", get_supported_pixfmts('libx264')[:5])
```

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

### Implement Basic Video Playback with MediaPlayer

Source: https://context7.com/matham/ffpyplayer/llms.txt

This snippet demonstrates how to initialize a MediaPlayer instance and iterate through video frames. It handles the retrieval of image data and timing information for smooth playback.

```python
from ffpyplayer.player import MediaPlayer
import time

player = MediaPlayer('/path/to/video.mp4')

while True:
    frame, val = player.get_frame()
    if val == 'eof':
        break
    elif frame is None:
        time.sleep(0.01)
    else:
        img, t = frame
        print(f"Frame at {t}s, format: {img.get_pixel_format()}, size: {img.get_size()}")
        time.sleep(val)
```

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

### Enumerate and Capture from DirectShow Devices

Source: https://context7.com/matham/ffpyplayer/llms.txt

Shows how to list available DirectShow devices on Windows using the tools module. This is a prerequisite for configuring the MediaPlayer to capture from webcams or external capture cards.

```python
from ffpyplayer.player import MediaPlayer
from ffpyplayer.tools import list_dshow_devices
import time

video_devs, audio_devs, names = list_dshow_devices()
print("Video devices:", list(video_devs.keys()))
print("Audio devices:", list(audio_devs.keys()))
```

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

### MediaPlayer - Capture Webcam Input

Source: https://context7.com/matham/ffpyplayer/llms.txt

Initializes a media player to capture video and audio from a webcam device using DirectShow.

```APIDOC
## GET /player/capture

### Description
Initializes the MediaPlayer to stream from a hardware device (e.g., webcam) and captures frames in a loop.

### Method
GET

### Parameters
#### Request Body
- **ff_opts** (dict) - Required - FFmpeg format options (e.g., 'f': 'dshow').
- **lib_opts** (dict) - Required - Library options for frame rate and buffer size.

### Request Example
{
  "device": "video=Logitech HD Webcam C525",
  "ff_opts": {"f": "dshow", "out_fmt": "rgb24"},
  "lib_opts": {"framerate": "30", "video_size": "320x240"}
}

### Response
#### Success Response (200)
- **frame** (object) - The captured image frame data.
- **val** (string) - Status indicator (e.g., 'eof').
```

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

### Capture Frames from Webcam using MediaPlayer

Source: https://context7.com/matham/ffpyplayer/llms.txt

This snippet demonstrates how to open a webcam using MediaPlayer, configure video and audio streams, and capture frames. It includes error handling for empty frames and EOF conditions, and prints the pixel format and size of captured frames. Dependencies include the ffpyplayer library.

```Python
from ffpyplayer.player import MediaPlayer
import time

lib_opts = {
    'framerate': '30',
    'video_size': '320x240',
    'pixel_format': 'yuv420p',
    'rtbufsize': '27648000'  # 320*240*3 @ 30fps for 4 seconds
}

ff_opts = {
    'f': 'dshow',              # Force DirectShow format
    'out_fmt': 'rgb24'         # Output as RGB24
}

# Open webcam with audio
player = MediaPlayer(
    'video=Logitech HD Webcam C525:audio=Microphone (HD Webcam C525)',
    ff_opts=ff_opts,
    lib_opts=lib_opts
)

# Capture frames
for _ in range(100):
    frame, val = player.get_frame()
    if val == 'eof':
        break
    elif frame is None:
        time.sleep(0.01)
    else:
        img, t = frame
        print(f"Captured: {img.get_pixel_format()}, {img.get_size()}")
        time.sleep(val)

player.close_player()
```

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

### Set FFmpeg and SDL2 Library and Include Directories

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/installation.md

Specifies the exact directories for FFmpeg and SDL2 shared libraries and header files using environment variables. This is an alternative to setting the root directories when libraries and headers are in non-standard locations.

```bash
export FFMPEG_LIB_DIR=/path/to/ffmpeg/lib
export FFMPEG_INCLUDE_DIR=/path/to/ffmpeg/include
export SDL_LIB_DIR=/path/to/sdl2/lib
export SDL_INCLUDE_DIR=/path/to/sdl2/include
```

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

### MediaPlayer - Advanced Playback Options

Source: https://context7.com/matham/ffpyplayer/llms.txt

Illustrates advanced playback configurations for MediaPlayer, including custom output formats, seeking, looping, and event callbacks.

```APIDOC
## MediaPlayer - Advanced Playback Options

### Description
This example demonstrates how to use `MediaPlayer` with advanced options for customizing playback, such as setting output format, controlling playback start/end times, looping, and applying video filters. It also shows how to set up callbacks for player events and control playback after initialization.

### Method
`MediaPlayer(filepath, callback=None, ff_opts={}, lib_opts={}, loglevel='warning', ...)`

### Endpoint
N/A (Local file playback)

### Parameters
#### Path Parameters
- **filepath** (str) - Required - Path to the media file or stream URL.

#### Query Parameters
None

#### Request Body
None

#### Other Parameters
- **callback** (function) - Optional - A function to be called for player events (e.g., 'eof', 'display_sub').
- **ff_opts** (dict) - Optional - Dictionary of FFmpeg player options (e.g., 'out_fmt', 'x', 'y', 'paused', 'ss', 't', 'loop', 'an', 'vn', 'sync', 'volume', 'vf').
- **lib_opts** (dict) - Optional - Dictionary of FFmpeg library options (e.g., 'threads', 'lowres').
- **loglevel** (str) - Optional - FFmpeg logging level (e.g., 'quiet', 'warning', 'info').

### Request Example
```python
from ffpyplayer.player import MediaPlayer
import time

ff_opts = {
    'out_fmt': 'yuv420p',
    'x': 640,
    'y': 480,
    'paused': True,
    'ss': 10.0,
    't': 60.0,
    'loop': 2,
    'an': False,
    'vn': False,
    'sync': 'audio',
    'volume': 0.8,
    'vf': 'hflip',
}

lib_opts = {
    'threads': 'auto',
    'lowres': '0',
}

def callback(selector, value):
    if selector == 'eof':
        print("End of file reached")
    elif selector.startswith('display_sub'):
        text, fmt, pts, start, end = value
        print(f"Subtitle: {text}")

player = MediaPlayer('/path/to/video.mp4',
                     callback=callback,
                     ff_opts=ff_opts,
                     lib_opts=lib_opts,
                     loglevel='warning')

metadata = player.get_metadata()
print(f"Duration: {metadata['duration']}s")

player.set_pause(False)
player.set_volume(0.5)
player.seek(30.0, relative=False)

while True:
    frame, val = player.get_frame()
    if val == 'eof':
        break
    elif frame is None:
        time.sleep(0.01)
    else:
        img, t = frame
        print(f"PTS: {t}, Size: {img.get_buffer_size()}")
        time.sleep(val)

player.close_player()
```

### Response
#### Success Response (200)
- **metadata** (dict) - Dictionary containing media metadata like 'duration', 'src_vid_size', 'frame_rate'.
- **frame** (tuple) - A tuple containing the image data and timestamp (PTS).
- **val** (float or str) - The recommended time to sleep before the next frame, or 'eof' if the end of the file is reached.

#### Response Example
```
Duration: 120.5s
Source size: (1920, 1080)
Frame rate: 24.0
PTS: 0.0416, Size: 2211840
...
```
```

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

### Create and Manipulate Images with ffpyplayer.pic.Image

Source: https://context7.com/matham/ffpyplayer/llms.txt

Demonstrates how to create Image objects from raw byte buffers, specifying pixel formats and sizes. It covers accessing image properties, handling internal FFmpeg buffers, custom alignment, copying images (shallow and deep), and exporting image data to byte arrays or memory views.

```python
from ffpyplayer.pic import Image
import copy

# Assume w and h are defined
w, h = 100, 50 # Example dimensions

# Create RGB24 image from buffer
size = w * h * 3
buf = bytearray([int(x * 255 / size) for x in range(size)])
img_rgb = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))

print(f"Pixel format: {img_rgb.get_pixel_format()}")
print(f"Size: {img_rgb.get_size()}")
print(f"Buffer sizes: {img_rgb.get_buffer_size()}")
print(f"Line sizes: {img_rgb.get_linesizes()}")
print(f"Is referenced: {img_rgb.is_ref()}")

# Create image with internal FFmpeg buffers (aligned)
img_internal = Image(pix_fmt='yuv420p', size=(w, h))
print(f"Internal buffer aligned: {img_internal.get_linesizes(keep_align=True)}")
print(f"Is referenced: {img_internal.is_ref()}")

# Create image with custom alignment (32-byte)
import math
align = lambda x: int(math.ceil(x / 32.0) * 32)
linesize = [align(w * 3)]  # RGB24 has 3 bytes per pixel
aligned_size = h * linesize[0]
buf_aligned = bytearray(aligned_size)
img_aligned = Image(
    plane_buffers=[buf_aligned],
    pix_fmt='rgb24',
    size=(w, h),
    linesize=linesize
)
print(f"Custom alignment: {img_aligned.get_linesizes(keep_align=True)}")

# Copy images
img_shallow = copy.copy(img_rgb)      # Shallow copy (reference if possible)
img_deep = copy.deepcopy(img_rgb)     # Deep copy (always copies data)
print(f"Shallow copy is_ref: {img_shallow.is_ref()}")
print(f"Deep copy is_ref: {img_deep.is_ref()}")

# Export to bytearray
planes = img_rgb.to_bytearray()
print(f"Exported plane sizes: {[len(p) for p in planes]}")

# Export to memoryview (zero-copy when possible)
memviews = img_rgb.to_memoryview()
if memviews[0] is not None:
    print(f"Memoryview size: {memviews[0].memview.size}")
```

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

### MediaPlayer - Basic Video Playback

Source: https://context7.com/matham/ffpyplayer/llms.txt

Demonstrates basic video playback using the MediaPlayer class, including retrieving frames and handling end-of-file conditions.

```APIDOC
## MediaPlayer - Basic Video Playback

### Description
This example shows how to initialize and play a video file using `MediaPlayer`. It demonstrates retrieving video frames, checking for the end of the file (EOF), and handling frame data.

### Method
`MediaPlayer(filepath, ...)`

### Endpoint
N/A (Local file playback)

### Parameters
#### Path Parameters
- **filepath** (str) - Required - Path to the media file or stream URL.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from ffpyplayer.player import MediaPlayer
import time

player = MediaPlayer('/path/to/video.mp4')

while True:
    frame, val = player.get_frame()
    if val == 'eof':
        break
    elif frame is None:
        time.sleep(0.01)
    else:
        img, t = frame
        print(f"Frame at {t}s, format: {img.get_pixel_format()}, size: {img.get_size()}")
        time.sleep(val)
```

### Response
#### Success Response (200)
- **frame** (tuple) - A tuple containing the image data and timestamp (PTS).
- **val** (float or str) - The recommended time to sleep before the next frame, or 'eof' if the end of the file is reached.

#### Response Example
```
Frame at 0.0s, format: rgb24, size: (1920, 1080)
Frame at 0.0416s, format: rgb24, size: (1920, 1080)
...
```
```

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

### Configure FFmpeg Logging Callbacks

Source: https://context7.com/matham/ffpyplayer/llms.txt

Shows how to set global FFmpeg log levels and redirect logs to custom Python handlers or functions for better monitoring and debugging of library operations.

```python
from ffpyplayer.tools import set_log_callback, set_loglevel, loglevels, emit_library_info
import logging
set_loglevel('warning')
def my_log_callback(message, level):
    if loglevels[level] <= loglevels['error']:
        print(f"[{level.upper()}] {message.strip()}")
set_log_callback(my_log_callback)
logger = logging.getLogger('ffpyplayer')
set_log_callback(logger=logger)
emit_library_info()
```

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

### Add FFmpeg and SDL2 Shared Libraries to PATH

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/installation.md

Appends the directories containing FFmpeg and SDL2 shared libraries (.so files) to the system's PATH environment variable. This ensures that the dynamic linker can find these libraries when the ffpyplayer is executed.

```bash
export PATH=$FFMPEG_LIB_DIR:$SDL_LIB_DIR:$PATH
```

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

### Play Media File with FFPyPlayer

Source: https://github.com/matham/ffpyplayer/blob/master/README.rst

This snippet shows how to initialize a MediaPlayer object to play a media file. It continuously retrieves frames and their status until the end of the file (eof) is reached. The retrieved frames can then be processed or displayed.

```python
from ffpyplayer.player import MediaPlayer
import time

player = MediaPlayer(filename)
val = ''
while val != 'eof':
    frame, val = player.get_frame()
    if val != 'eof' and frame is not None:
        img, t = frame
        # display img
```

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

### Load Images and Animations with ffpyplayer.pic.ImageLoader

Source: https://context7.com/matham/ffpyplayer/llms.txt

Demonstrates the ImageLoader class for reading single image files (like PNG) and animated image sequences (like GIFs). It shows how to iterate through frames, retrieve frame timestamps (PTS), and collect all frames into a list.

```python
from ffpyplayer.pic import ImageLoader

# Read a single PNG image
# Assume 'image.png' exists
# loader = ImageLoader('image.png')
# for img, pts in loader:
#     print(f"Image: {img.get_size()}, {img.get_pixel_format()}, pts={pts}")
# Output: Image: (800, 600), rgb24, pts=0.0

# Read animated GIF with timestamps
# Assume 'animation.gif' exists
# gif_loader = ImageLoader('animation.gif')
# frames = list(gif_loader)  # Collect all frames
# print(f"Total frames: {len(frames)}")
# for img, pts in frames:
#     print(f"Frame at {pts}s: {img.get_size()}")

# Manual frame iteration
# loader2 = ImageLoader('animation.gif')
# while True:
#     result = loader2.next_frame()
#     if result == (None, 0):
#         break
#     img, pts = result
#     print(f"Frame: pts={pts}")
```

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

### Configure FFmpeg Compilation for Shared Libraries

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/installation.md

Instructions for compiling FFmpeg with shared library support. This involves enabling the '--enable-shared' flag and '--extra-cflags="-fPIC"' during the compilation process, and ensuring these are also applied to its dependencies. Static compilation flags should be removed if present.

```bash
# Example compilation flags (actual configure command may vary)
# ./configure --enable-shared --extra-cflags="-fPIC" [other options]
```

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

### Perform Video Transcoding with MediaWriter

Source: https://context7.com/matham/ffpyplayer/llms.txt

A complete workflow for reading a video file, resizing it, and re-encoding it into a new format using MediaPlayer and MediaWriter.

```python
from ffpyplayer.player import MediaPlayer
from ffpyplayer.writer import MediaWriter
import time
player = MediaPlayer('input.mp4', ff_opts={'an': True, 'sync': 'video'})
writer = MediaWriter('output.avi', [{'width_out': 640, 'height_out': 360, 'codec': 'libx264'}], fmt='mp4', overwrite=True)
while True:
    frame, val = player.get_frame()
    if val == 'eof': break
    if frame:
        img, pts = frame
        writer.write_frame(img=img, pts=pts, stream=0)
writer.close()
player.close_player()
```

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

### Convert Images with FFPyPlayer SWScale

Source: https://github.com/matham/ffpyplayer/blob/master/README.rst

This snippet illustrates image conversion using FFPyPlayer's SWScale. It creates an image with a specified format and dimensions, then uses SWScale to convert it to a different pixel format (yuv420p). The resulting image's pixel data is then extracted.

```python
from ffpyplayer.pic import Image, SWScale
w, h = 500, 100
size = w * h * 3
buf = bytearray([int(x * 255 / size) for x in range(size)])

img = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))
sws = SWScale(w, h, img.get_pixel_format(), ofmt='yuv420p')

img2 = sws.scale(img)
img2.get_pixel_format()
planes = img2.to_bytearray()
[len(plane) for plane in planes]
```

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

### Write Raw Video to File with MediaWriter

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/examples.md

This code snippet demonstrates how to write raw video frames to a file using ffpyplayer. It initializes a MediaWriter with specific output options for raw video, constructs image data, and writes frames to two streams. The output format is AVI, and the output resolution is half the input resolution.

```python
from ffpyplayer.writer import MediaWriter
from ffpyplayer.pic import Image

w, h = 640, 480
# write at 5 fps.
out_opts = {'pix_fmt_in':'rgb24', 'width_in':w, 'height_in':h, 'codec':'rawvideo',
            'frame_rate':(5, 1)}
# write using rgb24 frames into a two stream rawvideo file where the output
# is half the input size for both streams. Avi format will be used.
writer = MediaWriter('output.avi', [out_opts] * 2, width_out=w/2,
                     height_out=h/2)

# Construct images
size = w * h * 3
buf = bytearray([int(x * 255 / size) for x in range(size)])
img = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))

buf = bytearray([int((size - x) * 255 / size) for x in range(size)])
img2 = Image(plane_buffers=[buf], pix_fmt='rgb24', size=(w, h))

for i in range(20):
    writer.write_frame(img=img, pts=i / 5., stream=0)  # stream 1
    writer.write_frame(img=img2, pts=i / 5., stream=1)  # stream 2
```

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

### Set PKG_CONFIG_PATH for FFmpeg and SDL2

Source: https://github.com/matham/ffpyplayer/blob/master/doc/source/installation.md

Sets the PKG_CONFIG_PATH environment variable to include directories containing .pc files for FFmpeg and SDL2. This helps the pkg-config tool locate the necessary metadata for these libraries during the build process.

```bash
# Example: Assuming .pc files are in $HOME/ffmpeg_build/lib/pkgconfig and $HOME/sdl2_build/lib/pkgconfig
export PKG_CONFIG_PATH=$HOME/ffmpeg_build/lib/pkgconfig:$HOME/sdl2_build/lib/pkgconfig:$PKG_CONFIG_PATH
```

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

### Save Compressed TIFF with LZW using MediaWriter

Source: https://context7.com/matham/ffpyplayer/llms.txt

This snippet demonstrates how to save an image to a compressed TIFF file using the LZW compression algorithm with FFPyPlayer's MediaWriter. It configures the writer with specific output options and compression settings, then writes a single frame before closing the writer.

```python
writer = MediaWriter(
    'output_compressed.tiff',
    [out_opts],
    lib_opts={'compression_algo': 'lzw'},
    overwrite=True
)
writer.write_frame(img=img, pts=0, stream=0)
writer.close()

print("Images saved successfully")
```