FFPyPlayer

https://matham.github.io/ffpyplayer/
Admin
FFPyPlayer is a Python library for audio and video playback, writing, and manipulation using FFmpeg...
Tokens:30,022
Snippets:207
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install ffpyplayer from source

Source: https://matham.github.io/ffpyplayer/_sources/installation.rst.txt

Commands to install the master branch or build from a local directory.

```bash
pip install https://github.com/matham/ffpyplayer/archive/master.zip
```

```bash
make
```

```bash
python setup.py build_ext --inplace
```

```bash
pip install -e .
```

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

### Initialize MediaWriter with Output Options

Source: https://matham.github.io/ffpyplayer/writer.html

Example of initializing MediaWriter with specific input and output options for video streams. Ensure 'rgb24' pixel format and 'rawvideo' codec are compatible with your FFmpeg setup.

```python
from ffpyplayer.writer import MediaWriter

w, h = 640, 480
out_opts = {'pix_fmt_in':'rgb24', 'width_in':w, 'height_in':h, 'codec':'rawvideo',
```

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

### Initialize Image with Internal Buffers

Source: https://matham.github.io/ffpyplayer/pic.html

Example of initializing an Image object by specifying pixel format and size, letting the class create and manage the internal buffers. This is often simpler when starting from scratch.

```python
>>> img2 = Image(pix_fmt='rgb24', size=(w, h))
```

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

### Install ffpyplayer from master branch

Source: https://matham.github.io/ffpyplayer/installation.html

Install the latest development version of ffpyplayer directly from its GitHub master branch.

```bash
pip install https://github.com/matham/ffpyplayer/archive/master.zip
```

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

### Import ffpyplayer

Source: https://matham.github.io/ffpyplayer/_sources/installation.rst.txt

Verify the installation by importing the module in Python.

```python
import ffpyplayer
```

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

### Install Cython

Source: https://matham.github.io/ffpyplayer/installation.html

Install or upgrade Cython to the specified version, a requirement for compiling ffpyplayer.

```bash
pip install --upgrade cython~=3.0.11
```

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

### Install FFmpeg and SDL2 using Homebrew (OSX)

Source: https://matham.github.io/ffpyplayer/installation.html

Install FFmpeg and SDL2 libraries on macOS using the Homebrew package manager.

```bash
brew update
brew install sdl2 sdl2_mixer ffmpeg
```

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

### Install ffpyplayer using pip

Source: https://matham.github.io/ffpyplayer/installation.html

Use this command to install ffpyplayer wheels for Python 3.5+ on Windows and Linux.

```bash
pip install ffpyplayer
```

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

### Install ffpyplayer in editable mode

Source: https://matham.github.io/ffpyplayer/installation.html

Install ffpyplayer from a local source directory in editable mode, allowing for direct changes to the source code.

```bash
pip install -e .
```

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

### Install Python Development Headers

Source: https://matham.github.io/ffpyplayer/installation.html

Command to install the required Python 3 development headers on Ubuntu systems.

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

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

### Install FFmpeg and SDL2 dependencies (Other Linux)

Source: https://matham.github.io/ffpyplayer/installation.html

Install SDL2 development libraries on other Linux platforms, such as Ubuntu 16.04, for compiling ffpyplayer.

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

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

### Get Frames with YUV420p Pixel Format

Source: https://matham.github.io/ffpyplayer/player.html

Retrieves frames and displays them at their correct presentation timestamps, specifically for the yuv420p pixel format. This example shows how to check the pixel format and buffer size.

```python
>>> player = MediaPlayer(filename, callback=weakref.ref(callback), 
... ff_opts={'out_fmt':'yuv420p'})
>>> while 1:
...     frame, val = player.get_frame()
...     if val == 'eof':
...         break
...     elif frame is None:
...         time.sleep(0.01)
...         print 'not ready'
...     else:
...         img, t = frame
...         print val, t, img.get_pixel_format(), img.get_buffer_size()
...         time.sleep(val)
... 
0.0 0.0 yuv420p (309760, 77440, 77440, 0)
0.0361273288727 0.0611284 yuv420p (309760, 77440, 77440, 0)
0.0502526760101 0.1222568 yuv420p (309760, 77440, 77440, 0)
0.12150645256 0.1833852 yuv420p (309760, 77440, 77440, 0)
0.122756242752 0.2445136 yuv420p (309760, 77440, 77440, 0)

```

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

### Install FFmpeg and SDL2 dependencies (Ubuntu 18.04)

Source: https://matham.github.io/ffpyplayer/installation.html

Install necessary FFmpeg and SDL2 development libraries on Ubuntu 18.04 for compiling ffpyplayer.

```bash
sudo apt install ffmpeg libavcodec-dev libavdevice-dev libavfilter-dev libavformat-dev \
libavutil-dev libswscale-dev libswresample-dev libpostproc-dev libsdl2-dev libsdl2-2.0-0 \
libsdl2-mixer-2.0-0 libsdl2-mixer-dev python3-dev
```

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

### Initialize Image with Provided Buffers

Source: https://matham.github.io/ffpyplayer/pic.html

Example of initializing an Image object by providing existing byte buffers for its planes, along with pixel format and size. This is useful when data is already in memory.

```python
>>> w, h = 640, 480
>>> 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))
```

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

### Get YUV420P Image Buffers

Source: https://matham.github.io/ffpyplayer/pic.html

Manage YUV420P image buffers with alignment considerations and re-initialization.

```python
>>> img = Image(pix_fmt='yuv420p', size=(w, h))
>>> linesize = img.get_linesizes(keep_align=True)
>>> linesize
(100, 50, 50, 0)
>>> align = lambda x: int(math.ceil(x / 32.) * 32)
>>> linesize = map(align, linesize)
>>> linesize
[128, 64, 64, 0]

>>> img = Image(pix_fmt='yuv420p', size=(w, h), linesize=linesize)
>>> map(len, img.to_bytearray())
[1000, 250, 250, 0]
>>> map(len, img.to_bytearray(keep_align=True))
[1280, 320, 320, 0]

>>> # now initialize a new Image with it
>>> img2 = Image(plane_buffers=img.to_bytearray(),
... pix_fmt=img.get_pixel_format(), size=img.get_size())
>>> img2.get_buffer_size(keep_align=True)
(1000, 250, 250, 0)

>>> # keep alignment
>>> img2 = Image(plane_buffers=img.to_bytearray(keep_align=True),
... pix_fmt=img.get_pixel_format(), size=img.get_size(),
... linesize=img.get_linesizes(keep_align=True))
>>> img2.get_buffer_size(keep_align=True)
(1280, 320, 320, 0)
```

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

### Convert Image to YUV420P and Get Buffers

Source: https://matham.github.io/ffpyplayer/pic.html

Illustrates converting an Image to the 'yuv420p' pixel format using SWScale and retrieving the resulting plane buffers as bytearrays. Note the differing lengths of the planes for YUV formats.

```python
>>> 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]
```

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

### Complex Transcoding with ffpyplayer (YUV420p Output)

Source: https://matham.github.io/ffpyplayer/_sources/examples.rst.txt

An advanced transcoding example that outputs frames in YUV420p format. It reads video from a file, processes it, and writes to another file, ensuring synchronization with the video stream.

```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']
```

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

### Program Information

Source: https://matham.github.io/ffpyplayer/player.html

APIs to get and request specific programs within the media.

```APIDOC
## GET /api/player/programs

### Description
Retrieves a list of available program IDs within the media.

### Method
GET

### Endpoint
/api/player/programs

### Parameters
None

### Request Example
```json
{
  "example": "player.get_programs()"
}
```

### Response
#### Success Response (200)
- **programs** (list of integers) - A list of available program IDs.

#### Response Example
```json
{
  "programs": [0, 1, 2, 3, 4]
}
```

## POST /api/player/request_program

### Description
Opens video, audio, and subtitle streams associated with a specific program. This action closes all current streams and opens the first streams found for the requested program.

### Method
POST

### Endpoint
/api/player/request_program

### Parameters
#### Request Body
- **requested_program** (int) - Required - The program ID to open streams for.

### Request Example
```json
{
  "requested_program": 1
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the program streams have been requested.

#### Response Example
```json
{
  "message": "Program streams requested successfully."
}
```
```

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

### Get MediaWriter Configuration

Source: https://matham.github.io/ffpyplayer/writer.html

Retrieve the current configuration of the MediaWriter object. This is useful for verifying settings before writing.

```python
print writer.get_configuration()
```

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

### Get FFmpeg Formats

Source: https://matham.github.io/ffpyplayer/tools.html

Returns available FFmpeg formats, including their full names and extensions. Can filter for input or output formats.

```python
ffpyplayer.tools.get_fmts(input=True, output=True)
```

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

### Get Metadata from Media File

Source: https://matham.github.io/ffpyplayer/player.html

Retrieves metadata associated with the media file being played. The metadata is returned as a dictionary.

```python
get_metadata(_self_)
    
Returns metadata of the file being played. 

Returns:
     
dict:
    
```

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

### Get Format Codec

Source: https://matham.github.io/ffpyplayer/tools.html

Determines the best codec for a given file format, either by filename extension or by explicitly providing the format name.

```python
>>> get_format_codecs('test.png')
'mjpeg'
>>> get_format_codecs('test.jpg')
'mjpeg'
>>> get_format_codecs('test.mkv')
'libx264'
>>> get_format_codecs(fmt='h264')
'libx264'
```

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

### Get Frames with Immediate Display

Source: https://matham.github.io/ffpyplayer/player.html

Retrieves frames and displays them as soon as they are read. Use this when real-time display is not critical and you want to process frames quickly.

```python
>>> while 1:
...     frame, val = player.get_frame()
...     if val == 'eof':
...         break
...     elif frame is None:
...         time.sleep(0.01)
...         print 'not ready'
...     else:
...         img, t = frame
...         print val, t, img
not ready
0.0 0.0 <ffpyplayer.pic.Image object at 0x023D17B0>
not ready
0.0351264476776 0.0611284 <ffpyplayer.pic.Image object at 0x023D1828>
0.096254825592 0.1222568 <ffpyplayer.pic.Image object at 0x02411800>
not ready
0.208511352539 0.1833852 <ffpyplayer.pic.Image object at 0x02411B70>

```

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

### Write Video to File with MediaWriter

Source: https://matham.github.io/ffpyplayer/_sources/examples.rst.txt

Configures a MediaWriter to output raw video streams. The example demonstrates writing two streams with custom dimensions and frame rates.

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

```python
writer = MediaWriter('output.mp4', [out_opts] * 2, fmt='avi',
                      width_out=w/2, height_out=h/2)
```

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

### Get Player Programs

Source: https://matham.github.io/ffpyplayer/player.html

Returns a list of available program IDs within the media file. These programs can contain associated video, audio, and subtitle streams.

```python
>>> print(player.get_programs())
[0, 1, 2, 3, 4]
```

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

### Get Output Pixel Format

Source: https://matham.github.io/ffpyplayer/player.html

Returns the pixel format for output images. This can be set during instance creation using `out_fmt` in `ff_opts` or changed dynamically with `set_output_pix_fmt()` if avfilter is enabled.

```python
>>> print(player.get_output_pix_fmt())
rgb24
```

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

### Compile ffpyplayer locally (setup.py)

Source: https://matham.github.io/ffpyplayer/installation.html

Use this command to build ffpyplayer extensions from a local source directory.

```bash
python setup.py build_ext --inplace
```

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

### Initialize MediaWriter with Output Options

Source: https://matham.github.io/ffpyplayer/writer.html

Instantiate MediaWriter with output configurations, specifying dimensions and codec options. The output options list should match the number of streams.

```python
out_opts = {'height_in': 480, 'codec': 'rawvideo', 'width_in': 640, 'frame_rate':(5, 1)}
writer = MediaWriter('output.avi', [out_opts] * 2, width_out=w/2, height_out=h/2)
```

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

### Play Webcam with DirectShow

Source: https://matham.github.io/ffpyplayer/examples.html

Shows how to initialize a MediaPlayer with specific DirectShow device options and process frames in a loop.

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

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

### Calculate Buffer Sizes for YUV420P

Source: https://matham.github.io/ffpyplayer/pic.html

Demonstrates calculating buffer sizes for a YUV420P image with and without 32-bit alignment.

```python
>>> w, h = 100, 10
>>> img = Image(pix_fmt='yuv420p', size=(w, h))
>>> img.get_linesizes(keep_align=True)
(100, 50, 50, 0)
>>> img.get_buffer_size()
(1000, 250, 250, 0)

>>> # align to 32 bits
>>> linesize = img.get_linesizes(keep_align=True)
>>> align = lambda x: int(math.ceil(x / 32.) * 32)
>>> linesize = map(align, linesize)
>>> linesize
[128, 64, 64, 0]
>>> img = Image(pix_fmt='yuv420p', size=(w, h), linesize=linesize)
>>> img.get_linesizes(keep_align=True)
(128, 64, 64, 0)
>>> img.get_buffer_size(keep_align=True)
(1280, 320, 320, 0)
>>> img.get_buffer_size()
(1000, 250, 250, 0)
```

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

### Get Image Size

Source: https://matham.github.io/ffpyplayer/pic.html

Retrieves the dimensions of the frame.

```python
>>> img.get_size()
(640, 480)
```

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

### Get Pixel Format

Source: https://matham.github.io/ffpyplayer/pic.html

Retrieves the pixel format of an image instance.

```python
>>> img.get_pixel_format()
'rgb24'
```

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

### Create Image with Default FFmpeg Buffers

Source: https://matham.github.io/ffpyplayer/pic.html

Demonstrates creating an Image object with specified pixel format and size, allowing FFmpeg to allocate and manage the internal buffers.

```python
>>> img = Image(pix_fmt='rgb24', size=(w, h))
```

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

### Scale images with SWScale

Source: https://matham.github.io/ffpyplayer/pic.html

Demonstrates various scaling configurations including aspect ratio maintenance, pixel format conversion, and using pre-allocated destination images.

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

>>> # specify output w,h
>>> sws = SWScale(w, h, img.get_pixel_format(), ow=w/2, oh=h/3)
>>> img2 = sws.scale(img)
>>> img2.get_size()
(250, 33)

>>> # use input height
>>> sws = SWScale(w, h, img.get_pixel_format(), ow=w/2, oh=0)
>>> img2 = sws.scale(img)
>>> img2.get_size()
(250, 100)

>>> # keep aspect ratio
>>> sws = SWScale(w, h, img.get_pixel_format(), ow=w/2)
>>> img2 = sws.scale(img)
>>> img2.get_size()
(250, 50)

>>> # convert rgb24 to yuv420p
>>> sws = SWScale(w, h, img.get_pixel_format(), ofmt='yuv420p')
>>> img2 = sws.scale(img)
>>> img2.get_pixel_format()
'yuv420p'

>>> # convert into a previously allocated and aligned image
>>> import math
>>> align = lambda x: int(math.ceil(x / 32.) * 32)
>>> img2 = Image(pix_fmt=img.get_pixel_format(), size=(w/2, h/2))
>>> img2.get_linesizes(keep_align=True)
(750, 0, 0, 0)
>>> linesize = map(align, img2.get_linesizes())
>>> linesize
[768, 0, 0, 0]
>>> img2 = Image(pix_fmt=img2.get_pixel_format(), size=img2.get_size(), linesize=linesize)
>>> img2.get_linesizes(keep_align=True)
(768, 0, 0, 0)
>>> sws.scale(img, dst=img2)
<ffpyplayer.pic.Image object at 0x02B44440>
>>> img2
<ffpyplayer.pic.Image object at 0x02B44440>
```

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

### Output Pixel Format

Source: https://matham.github.io/ffpyplayer/player.html

Gets the pixel format in which output images are returned.

```APIDOC
## GET /api/player/output_pix_fmt

### Description
Returns the pixel format in which output images are returned when calling `get_frame()`.

### Method
GET

### Endpoint
/api/player/output_pix_fmt

### Parameters
None

### Request Example
```json
{
  "example": "player.get_output_pix_fmt()"
}
```

### Response
#### Success Response (200)
- **output_pix_fmt** (string) - The pixel format of the output images (e.g., 'rgb24').

#### Response Example
```json
{
  "output_pix_fmt": "rgb24"
}
```
```

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

### Create Image in RGB24 Format

Source: https://matham.github.io/ffpyplayer/pic.html

Demonstrates creating an Image object with a specified pixel format (rgb24) and size, initializing its buffer with sample data.

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

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

### Get RGB Image Buffer

Source: https://matham.github.io/ffpyplayer/pic.html

Retrieve the linesizes and bytearray representation of an RGB image.

```python
>>> w, h = 100, 10
>>> img = Image(pix_fmt='rgb24', size=(w, h))
>>> img.get_linesizes(keep_align=True)
(300, 0, 0, 0)
>>> map(len, img.to_bytearray())
[3000, 0, 0, 0]
```

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

### Player State Information

Source: https://matham.github.io/ffpyplayer/player.html

APIs to get the current state of the player, such as mute status, pause status, and volume.

```APIDOC
## GET /api/player/state

### Description
Retrieves the current state of the player, including mute status, pause status, and volume level.

### Method
GET

### Endpoint
/api/player/state

### Parameters
None

### Request Example
```json
{
  "example": "player.get_mute()",
  "example": "player.get_pause()",
  "example": "player.get_volume()"
}
```

### Response
#### Success Response (200)
- **muted** (boolean) - True if the player is muted, False otherwise.
- **paused** (boolean) - True if the player is paused, False otherwise.
- **volume** (float) - The current volume level, a value between 0.0 and 1.0.

#### Response Example
```json
{
  "muted": false,
  "paused": false,
  "volume": 0.8
}
```
```

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

### MediaWriter Class Initialization

Source: https://matham.github.io/ffpyplayer/writer.html

Initializes a new MediaWriter instance to create a video file with specified stream configurations.

```APIDOC
## MediaWriter Initialization

### Description
Creates an instance of the MediaWriter to write video frames to a file.

### Parameters
#### Request Body
- **filename** (str) - Required - The path of the media file to create.
- **streams** (list of dicts) - Required - Configuration for each stream (pix_fmt_in, width_in, height_in, pix_fmt_out, width_out, height_out, codec, frame_rate).
- **fmt** (str) - Optional - The output format.
- **lib_opts** (dict or list of dicts) - Optional - Options passed to ffmpeg libraries.
- **metadata** (dict or list of dicts) - Optional - Metadata for the streams.
- **overwrite** (bool) - Optional - Whether to overwrite an existing file.
- **kwargs** (dict) - Optional - Default values for stream configurations.
```

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

### Compress Video to H.264

Source: https://matham.github.io/ffpyplayer/_sources/examples.rst.txt

Demonstrates writing compressed H.264 video files using libx264. Includes setting compression options, metadata, and verifying supported pixel formats.

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

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

### ffpyplayer.tools.list_dshow_devices

Source: https://matham.github.io/ffpyplayer/tools.html

Lists all available DirectShow devices (video and audio) on the system, along with their configurations and human-readable names.

```APIDOC
## ffpyplayer.tools.list_dshow_devices

### Description
Returns a list of the dshow devices available.

### Method
GET

### Endpoint
/ffpyplayer/tools/dshow_devices

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **video_devices** (dict) - A dictionary of DirectShow video devices. Keys are device names, values are lists of configurations `(pix_fmt, codec_fmt, (width, height), (min_rate, max_rate))`.
- **audio_devices** (dict) - A dictionary of DirectShow audio devices. Keys are device names, values are lists of configurations `((min_channels, max_channels), (min_bits, max_bits), (min_rate, max_rate))`.
- **device_names** (dict) - A dictionary mapping device names to more human-friendly names.

#### Response Example
```json
{
  "video_devices": {
    "@device_pnp_...223196\global": [
      ["bgr24", "", [160, 120], [5, 30]],
      ["bgr24", "", [176, 144], [5, 30]]
    ]
  },
  "audio_devices": {
    "@device_cm_...- HD Webcam C615)": [
      [[1, 2], [8, 16], [11025, 44100]]
    ]
  },
  "device_names": {
    "@device_cm_...- HD Webcam C615)": "Microphone (2- HD Webcam C615)"
  }
}
```
```

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

### ffpyplayer.tools.get_supported_framerates

Source: https://matham.github.io/ffpyplayer/tools.html

Gets the supported frame rates for a given encoding codec. Optionally, it can return the closest valid frame rate to a specified rate.

```APIDOC
## ffpyplayer.tools.get_supported_framerates

### Description
Returns the supported frame rates for encoding codecs. If a desired rate is provided, it also returns the closest valid rate.

### Method
GET

### Endpoint
/ffpyplayer/tools/supported_framerates

### Parameters
#### Query Parameters
- **codec_name** (string) - Required - The name of an encoding codec.
- **rate** (tuple) - Optional - A 2-tuple representing the desired frame rate (numerator, denominator), e.g., (2997, 100) for 29.97.

### Request Example
```json
{
  "codec_name": "mpeg1video"
}
```
```json
{
  "codec_name": "mpeg1video",
  "rate": [2997, 100]
}
```

### Response
#### Success Response (200)
- **supported_rates** (list of tuples) - A list of supported frame rates, where each rate is a tuple (numerator, denominator). If a rate was provided and restrictions exist, the closest rate is the first element.

#### Response Example
```json
{
  "supported_rates": [
    [24000, 1001],
    [24, 1],
    [25, 1],
    [30000, 1001],
    [30, 1],
    [50, 1],
    [60000, 1001],
    [60, 1],
    [15, 1],
    [5, 1],
    [10, 1],
    [12, 1],
    [15, 1]
  ]
}
```
```

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

### ffpyplayer.player Module

Source: https://matham.github.io/ffpyplayer/genindex.html

Documentation for the ffpyplayer.player module, which handles media playback.

```APIDOC
## ffpyplayer.player Module

### Description
This module provides functionalities for playing media files.

### Classes
- **MediaPlayer** (class in ffpyplayer.player)

### Methods
- close_player()
- get_frame()
- get_metadata()
- get_mute()
- get_output_pix_fmt()
- get_pause()
- get_programs()
- get_pts()
- get_volume()
- request_channel()
- request_program()
- seek()
- seek_to_chapter()
- select_video_filter()
- set_mute()
- set_output_pix_fmt()
- set_pause()
- set_size()
- set_volume()
- toggle_pause()
```

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

### Get FFmpeg Codecs

Source: https://matham.github.io/ffpyplayer/tools.html

Retrieves a list of available FFmpeg codecs for encoding or decoding, filtered by media type (video, audio, etc.).

```python
ffpyplayer.tools.get_codecs(encode=True, video=True)
```

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

### List DirectShow devices

Source: https://matham.github.io/ffpyplayer/tools.html

Enumerates available DirectShow video and audio devices along with their configurations.

```python
>>> from ffpyplayer.player import MediaPlayer
>>> from ffpyplayer.tools import list_dshow_devices
>>> import time, weakref
>>> dev = list_dshow_devices()
>>> print dev
({'@device_pnp_...223196\global': [('bgr24', '', (160, 120), (5, 30)),
('bgr24', '', (176, 144), (5, 30)), ('bgr24', '', (320, 176), (5, 30)),
('bgr24', '', (320, 240), (5, 30)), ('bgr24', '', (352, 288), (5, 30)),
...
('yuv420p', '', (320, 240), (5, 30)), ('yuv420p', '', (352, 288), (5, 30))],
'@device_pnp_...223196\global': [('bgr24', '', (160, 120), (30, 30)),
...
('yuyv422', '', (352, 288), (30, 30)),
('yuyv422', '', (640, 480), (30, 30))]},
{'@device_cm_...2- HD Webcam C615)': [((1, 2), (8, 16), (11025, 44100))],
'@device_cm_...HD Webcam C615)': [((1, 2), (8, 16), (11025, 44100))]},
{'@device_cm_...- HD Webcam C615)': 'Microphone (2- HD Webcam C615)',
 '@device_cm_...2- HD Webcam C615)': 'Microphone (3- HD Webcam C615)'}
```

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

### Convert Image Formats

Source: https://matham.github.io/ffpyplayer/examples.html

Demonstrates how to use SWScale to convert an image buffer from one pixel format to another.

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

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

### Get supported pixel formats for a codec

Source: https://matham.github.io/ffpyplayer/tools.html

Retrieves valid pixel formats for a specified encoding codec, optionally finding the format with minimum conversion loss.

```python
>>> print get_supported_pixfmts('ffv1')
['yuv420p', 'yuva420p', 'yuva422p', 'yuv444p', 'yuva444p', 'yuv440p', ...
'gray16le', 'gray', 'gbrp9le', 'gbrp10le', 'gbrp12le', 'gbrp14le']

>>> print get_supported_pixfmts('ffv1', 'gray')
['gray', 'yuv420p', 'yuva420p', 'yuva422p', 'yuv444p', 'yuva444p', ...
'gray16le', 'gbrp9le', 'gbrp10le', 'gbrp12le', 'gbrp14le']
```

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

### Configure FFmpeg Log Callback

Source: https://matham.github.io/ffpyplayer/tools.html

Demonstrates how to set a custom callback function to capture and filter FFmpeg log messages.

```python
>>> from ffpyplayer.tools import set_log_callback, loglevels
>>> loglevel_emit = 'error' # This and worse errors will be emitted.
>>> def log_callback(message, level):
...     message = message.strip()
...     if message and loglevels[level] <= loglevels[loglevel_emit]:
...         print '%s: %s' %(level, message.strip())
>>> set_log_callback(log_callback)
...
>>> set_log_callback(None)
```

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

### Get supported frame rates for a codec

Source: https://matham.github.io/ffpyplayer/tools.html

Retrieves valid frame rates for a specified encoding codec, optionally finding the closest match to a desired rate.

```python
>>> print get_supported_framerates('mpeg1video')
[(24000, 1001), (24, 1), (25, 1), (30000, 1001), (30, 1), (50, 1),
(60000, 1001), (60, 1), (15, 1), (5, 1), (10, 1), (12, 1), (15, 1)]

>>> print get_supported_framerates('mpeg1video', (2997, 100))
[(30000, 1001), (24000, 1001), (24, 1), (25, 1), (30, 1), (50, 1),
(60000, 1001), (60, 1), (15, 1), (5, 1), (10, 1), (12, 1), (15, 1)]
```

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

### Save Image to Disk

Source: https://matham.github.io/ffpyplayer/examples.html

Demonstrates creating an image and using MediaWriter to save it to a file, including optional 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()
```

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

### Compile ffpyplayer locally (Linux)

Source: https://matham.github.io/ffpyplayer/installation.html

Commands to compile ffpyplayer from a local source directory on Linux systems.

```bash
make
```

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

### Get Best Pixel Format

Source: https://matham.github.io/ffpyplayer/tools.html

Returns the best pixel format with the least conversion loss from a given list. The order of pixel formats in the input list can affect the result.

```python
>>> get_best_pix_fmt('yuv420p', ['rgb24', 'rgba', 'yuv444p', 'gray'])
'rgb24'
>>> get_best_pix_fmt('gray', ['rgb24', 'rgba', 'yuv444p', 'gray'])
'gray'
>>> get_best_pix_fmt('rgb8', ['rgb24', 'yuv420p', 'rgba', 'yuv444p', 'gray'])
'rgb24'
```

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

### Manage YUV420P Alignment

Source: https://matham.github.io/ffpyplayer/pic.html

Demonstrates checking and modifying linesize alignment for YUV420P images.

```python
>>> img = Image(pix_fmt='yuv420p', size=(w, h))
>>> img.get_linesizes(keep_align=True)
(100, 50, 50, 0)
>>> img.get_size()
(100, 10)

>>> # now try align to 32 bit
>>> linesize = img.get_linesizes(keep_align=True)
>>> align = lambda x: int(math.ceil(x / 32.) * 32)
>>> linesize = map(align, linesize)
>>> linesize
[128, 64, 64, 0]
>>> img = Image(pix_fmt='yuv420p', size=(w, h), linesize=linesize)
>>> img.get_linesizes(keep_align=True)
(128, 64, 64, 0)
>>> img.get_linesizes()
(100, 50, 50, 0)
>>> img.get_size()
(100, 10)
```

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

### ffpyplayer.pic Module

Source: https://matham.github.io/ffpyplayer/genindex.html

Documentation for the ffpyplayer.pic module, which contains classes and functions related to image handling.

```APIDOC
## ffpyplayer.pic Module

### Description
This module provides image-related functionalities.

### Classes
- **Image** (class in ffpyplayer.pic)
- **ImageLoader** (class in ffpyplayer.pic)
- **SWScale** (class in ffpyplayer.pic)

### Methods
- get_image_size()
- get_linesizes(self)
- get_pixel_format()
- get_required_buffers()
- get_size()
- is_key_frame(self)
- is_ref(self)
- next_frame()
- scale()
- to_bytearray()
- to_memoryview()
```

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

### Get Frames at Proper Display Times

Source: https://matham.github.io/ffpyplayer/player.html

Retrieves frames and displays them at their correct presentation timestamps. This ensures accurate playback timing. Requires careful handling of sleep durations.

```python
>>> while 1:
...     frame, val = player.get_frame()
...     if val == 'eof':
...         break
...     elif frame is None:
...         time.sleep(0.01)
...         print 'not ready'
...     else:
...         img, t = frame
...         print val, t, img
...         time.sleep(val)
not ready
0.0 0.0 <ffpyplayer.pic.Image object at 0x02411800>
not ready
0.0351274013519 0.0611284 <ffpyplayer.pic.Image object at 0x02411878>
0.0602538585663 0.1222568 <ffpyplayer.pic.Image object at 0x024118A0>
0.122507572174 0.1833852 <ffpyplayer.pic.Image object at 0x024118C8>
...
0.0607514381409 1.222568 <ffpyplayer.pic.Image object at 0x02411B70>
0.0618767738342 1.2836964 <ffpyplayer.pic.Image object at 0x02411B98>
0.0610010623932 1.3448248 <ffpyplayer.pic.Image object at 0x02411BC0>
0.0611264705658 1.4059532 <ffpyplayer.pic.Image object at 0x02411BE8>

```

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

### Implement a simple media player

Source: https://matham.github.io/ffpyplayer/player.html

A basic loop to retrieve and process frames from a media file using MediaPlayer.

```python
from ffpyplayer.player import MediaPlayer
player = MediaPlayer(filename)
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)
```

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

### Get Media Metadata

Source: https://matham.github.io/ffpyplayer/player.html

Retrieves metadata for the media file. The dictionary may contain default values until the file is opened and read. Values are updated after the first frame is read or when streams are manipulated.

```python
>>> print player.get_metadata()
{'duration': 71.972, 'sink_vid_size': (0, 0), 'src_vid_size':
 (704, 480), 'frame_rate': (13978, 583),
 'title': 'The Melancholy of Haruhi Suzumiya: Special Ending',
 'src_pix_fmt': 'yuv420p'}
```

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

### Retrieve Linesizes for RGB24

Source: https://matham.github.io/ffpyplayer/pic.html

Shows how to retrieve linesizes for an RGB24 image and how to force 32-bit alignment.

```python
>>> w, h = 100, 10
>>> img = Image(plane_buffers=[bytes(' ') * (w * h * 3)],
... pix_fmt='rgb24', size=(w, h))
>>> img.get_linesizes(keep_align=True)
(300, 0, 0, 0)
```

```python
>>> import math
>>> linesize = [int(math.ceil(w * 3 / 32.) * 32)]
>>> linesize
[320]
>>> img = Image(plane_buffers=[bytes(' ') * (h * linesize[0])],
... pix_fmt='rgb24', size=(w, h), linesize=linesize)
>>> img.get_linesizes(keep_align=True)
(320, 0, 0, 0)
>>> img.get_size()
(100, 10)
```

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

### FFPyPlayer API Overview

Source: https://matham.github.io/ffpyplayer/api.html

This section outlines the primary modules available within the FFPyPlayer library.

```APIDOC
## FFPyPlayer API Modules

### Description
The FFPyPlayer library is organized into four primary modules for handling media streams and processing.

### Modules
- **Player**: Handles media playback functionality.
- **Writer**: Manages media file writing and encoding.
- **Images**: Provides utilities for image processing and manipulation.
- **Tools**: Contains various helper functions and utility tools for the library.
```

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

### Convert Image to Different Size

Source: https://matham.github.io/ffpyplayer/pic.html

Shows how to use the SWScale class to resize an existing Image object to a new width and height. The original pixel format is maintained.

```python
>>> sws = SWScale(w, h, img.get_pixel_format(), ow=w/2, oh=h/3)
>>> img2 = sws.scale(img)
>>> img2.get_size()
(250, 33)
```
Tokens:
Raw