7/8/24, 11:25 PM GitHub - python-ffmpegio/python-ffmpegio: Python package to read/write media files with FFmpeg

python-ffmpegio / python-ffmpegio Public

Python package to read/write media files with FFmpeg

GPL-2.0 license

58 stars 6 forks Branches Tags Activity

Star Notifications

Code Issues 1 Pull requests Discussions Actions Projects Wiki

main 10 Branches 36 Tags Go to file Go to file Code

tikuma-lsuhsc updated github action 6f324d7 · 1 hour ago

.github updated github action 1 hour ago

docs docs/.nojekyll is needed 3 years ago

docsrc added missing dependencies for docs build 4 months ago

src/ffmpegio fixed probe._exec() error reporting (utf-8 decod… 1 hour ago

tests allow writers' extra_inputs arguments to be st… 1 hour ago

.gitignore keep vscode/[Link] off git last year

[Link] fixed probe._exec() error reporting (utf-8 decod… 1 hour ago

LICENSE Initial commit 3 years ago

Makefile added sphinx-generated docs 3 years ago

[Link] Doc update (typo fix) 4 months ago

[Link] added sphinx-generated docs 3 years ago

[Link] * moved all setup data to [Link] 9 months ago

[Link] added -e . 2 years ago

ffmpegio-core: Media I/O with FFmpeg in Python

pypi v0.10.0 status beta python 3.8 | 3.9 | 3.10 | 3.11 | 3.12 license GPL-2.0 build [Link]

Python ffmpegio package aims to bring the full capability of FFmpeg to read, write, probe, and manipulate multimedia data to Python. FFmpeg
is an open-source cross-platform multimedia framework, which can handle most of the multimedia formats available today.

Note

Since v0.3.0, ffmpegio Python distribution package has been split into ffmpegio-core and ffmpegio to allow Numpy-independent installation.

Install the full ffmpegio package via pip :

pip install ffmpegio

If [Link] data I/O is not needed, instead use

pip install ffmpegio-core

[Link] 1/6
7/8/24, 11:25 PM GitHub - python-ffmpegio/python-ffmpegio: Python package to read/write media files with FFmpeg

Main Features

Pure-Python light-weight package interacting with FFmpeg executable found in the system
Transcode a media file to another in Python
Read, write, filter, and create functions for audio, image, and video data
Context-managing [Link] to perform stream read/write operations of video and audio
Automatically detect and convert audio & video formats to and from [Link] properties
Probe media file information
Accepts all FFmpeg options including filter graphs
Supports a user callback whenever FFmpeg updates its progress information file (see -progress FFmpeg option)
ffconcat scripter to make the use of -f concat demuxer easier
I/O device enumeration to eliminate the need to look up device names. (currently supports only: Windows DirectShow)
More features to follow

Documentation

Visit our GitHub page here

Examples

To import ffmpegio

>>> import ffmpegio

Transcoding
Read Audio Files
Read Image Files / Capture Video Frames
Read Video Files
Read Multiple Files or Streams
Write Audio, Image, & Video Files
Filter Audio, Image, & Video Data
Stream I/O
Device I/O Enumeration
Progress Callback
Filtergraph Builder
Run FFmpeg and FFprobe Directly

Transcoding

>>> # transcode, overwrite output file if exists, showing the FFmpeg log
>>> [Link]('[Link]', 'output.mp4', overwrite=True, show_log=True)

>>> # 1-pass H.264 transcoding

>>> [Link]('[Link]', '[Link]', vcodec='libx264', show_log=True,
>>> preset='slow', crf=22, acodec='copy')

>>> # 2-pass H.264 transcoding

>>> [Link]('[Link]', '[Link]', two_pass=True, show_log=True,
>>> **{'c:v':'libx264', 'b:v':'2600k', 'c:a':'aac', 'b:a':'128k'})

>>> # concatenate videos using concat demuxer

>>> files = ['/video/[Link]','/video/[Link]']
>>> ffconcat = [Link]()
>>> ffconcat.add_files(files)

[Link] 2/6
7/8/24, 11:25 PM GitHub - python-ffmpegio/python-ffmpegio: Python package to read/write media files with FFmpeg
>>> with ffconcat: # generates temporary ffconcat file
>>> [Link](ffconcat, '[Link]', f_in='concat', codec='copy', safe_in=0)

Read Audio Files

>>> # read audio samples in its native sample format and return all channels
>>> fs, x = [Link]('[Link]')
>>> # fs: sampling rate in samples/second, x: [nsamples x nchannels] numpy array

>>> # read audio samples from 24.15 seconds to 63.2 seconds, pre-convert to mono in float data type
>>> fs, x = [Link]('[Link]', ss=24.15, to=63.2, sample_fmt='dbl', ac=1)

>>> # read filtered audio samples first 10 seconds

>>> # filter: equalizer which attenuate 10 dB at 1 kHz with a bandwidth of 200 Hz
>>> fs, x = [Link]('myaudio.mp3', t=10.0, af='equalizer=f=1000:t=h:width=200:g=-10')

Read Image Files / Capture Video Frames

>>> # list supported image extensions

>>> [Link].muxer_info('image2')['extensions']
['bmp', 'dpx', 'exr', 'jls', 'jpeg', 'jpg', 'ljpg', 'pam', 'pbm', 'pcx', 'pfm', 'pgm', 'pgmyuv',
'png', 'ppm', 'sgi', 'tga', 'tif', 'tiff', 'jp2', 'j2c', 'j2k', 'xwd', 'sun', 'ras', 'rs', 'im1',
'im8', 'im24', 'sunras', 'xbm', 'xface', 'pix', 'y']

>>> # read BMP image with auto-detected pixel format (rgb24, gray, rgba, or ya8)
>>> I = [Link]('[Link]') # I: [height x width x ncomp] numpy array

>>> # read JPEG image, then convert to grayscale and proportionally scale so the width is 480 pixels
>>> I = [Link]('[Link]', pix_fmt='grayscale', s='480x-1')

>>> # read PNG image with transparency, convert it to plain RGB by filling transparent pixels orange
>>> I = [Link]('[Link]', pix_fmt='rgb24', fill_color='orange')

>>> # capture video frame at timestamp=4:25.3 and convert non-square pixels to square
>>> I = [Link]('[Link]', ss='4:25.3', square_pixels='upscale')

>>> # capture 5 video frames and tile them on 3x2 grid with 7px between them, and 2px of initial margin
>>> I = [Link]('myvideo.mp4', vf='tile=3x2:nb_frames=5:padding=7:margin=2')

>>> # create spectrogram of the audio input (must specify pix_fmt if input is audio)
>>> I = [Link]('myaudio.mp3', filter_complex='showspectrumpic=s=960x540', pix_fmt='rgb24')

Read Video Files

>>> # read 50 video frames at t=[Link] then convert to grayscale

>>> fs, F = [Link]('myvideo.mp4', ss='[Link]', vframes=50, pix_fmt='gray')
>>> # fs: frame rate in frames/second, F: [nframes x height x width x ncomp] numpy array

>>> # get running spectrogram of audio input (must specify pix_fmt if input is audio)
>>> fs, F = [Link]('myvideo.mp4', pix_fmt='rgb24', filter_complex='showspectrum=s=1280x480')

Read Multiple Files or Streams

>>> # read both video and audio streams (1 ea)

>>> rates, data = [Link]('mymedia.mp4')
>>> # rates: dict of frame rate and sampling rate: keys="v:0" and "a:0"
>>> # data: dict of video frame array and audio sample array: keys="v:0" and "a:0"

>>> # combine video and audio files

>>> rates, data = [Link]('myvideo.mp4','myaudio.mp3')

>>> # get output of complex filtergraph (can take multiple inputs)

>>> expr = "[v:0]split=2[out0][l1];[l1]edgedetect[out1]"
>>> rates, data = [Link]('myvideo.mp4',filter_complex=expr,map=['[out0]','[out1]'])

[Link] 3/6
7/8/24, 11:25 PM GitHub - python-ffmpegio/python-ffmpegio: Python package to read/write media files with FFmpeg
>>> # rates: dict of frame rates: keys="v:0" and "v:1"
>>> # data: dict of video frame arrays: keys="v:0" and "v:1"

Write Audio, Image, & Video Files

>>> # create a video file from a numpy array

>>> [Link]('myvideo.mp4', rate, F)

>>> # create an image file from a numpy array

>>> [Link]('[Link]', F)

>>> # create an audio file from a numpy array

>>> [Link]('myaudio.mp3', rate, x)

Filter Audio, Image, & Video Data

>>> # Add fade-in and fade-out effects to audio data

>>> fs_out, y = [Link]('afade=t=in:ss=0:d=15,afade=t=out:st=875:d=25', fs_in, x)

>>> # Apply mirror effect to an image

>>> I_out = [Link]('crop=iw/2:ih:0:0,split[left][tmp];[tmp]hflip[right];[left][right] hstack', I_in)

>>> # Add text at the center of the video frame

>>> filter = "drawtext=fontsize=30:fontfile=[Link]:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
>>> fs_out, F_out = [Link](filter, fs_in, F_in)

Stream I/O

>>> # process video 100 frames at a time and save output as a new video
>>> # with the same frame rate
>>> with [Link]('myvideo.mp4', 'rv', blocksize=100) as fin,
>>> [Link]('myoutput.mp4', 'wv', rate=[Link]) as fout:
>>> for frames in fin:
>>> [Link](myprocess(frames))

Filtergraph Builder

>>> # build complex filtergraph

>>> from ffmpegio import filtergraph as fgb
>>>
>>> v0 = "[0]" >> [Link](start_frame=10, end_frame=20)
>>> v1 = "[0]" >> [Link](start_frame=30, end_frame=40)
>>> v3 = "[1]" >> [Link]()
>>> v2 = (v0 | v1) + [Link](2)
>>> v5 = (v2|v3) + [Link](eof_action='repeat') + [Link](50, 50, 120, 120, 'red', t=5)
>>> v5
<[Link] object at 0x1e67f955b80>
FFmpeg expression: "[0]trim=start_frame=10:end_frame=20[L0];[0]trim=start_frame=30:end_frame=40[L1];[L0][L1]conca
Number of chains: 5
chain[0]: [0]trim=start_frame=10:end_frame=20[L0];
chain[1]: [0]trim=start_frame=30:end_frame=40[L1];
chain[2]: [L0][L1]concat=2[L2];
chain[3]: [1]hflip[L3];
chain[4]: [L2][L3]overlay=eof_action=repeat,drawbox=[Link]red:t=5
Available input pads (0):
Available output pads: (1): (4, 1, 0)

Device I/O Enumeration

>>> # record 5 minutes of audio from Windows microphone

>>> fs, x = [Link]('a:0', f_in='dshow', sample_fmt='dbl', t=300)

[Link] 4/6
7/8/24, 11:25 PM GitHub - python-ffmpegio/python-ffmpegio: Python package to read/write media files with FFmpeg
>>> # capture Windows' webcam frame
>>> with [Link]('v:0', 'rv', f_in='dshow') as webcam,
>>> for frame in webcam:
>>> process_frame(frame)

Progress Callback

>>> import pprint

>>> # progress callback

>>> def progress(info, done):
>>> pprint(info) # bunch of stats
>>> if done:
>>> print('video decoding completed')
>>> else:
>>> return check_cancel_command(): # return True to kill immediately

>>> # can be used in any butch processing

>>> rate, F = [Link]('myvideo.mp4', progress=progress)

>>> # as well as for stream processing

>>> with [Link]('myvideo.mp4', 'rv', blocksize=100, progress=progress) as fin:
>>> for frames in fin:
>>> myprocess(frames)

Run FFmpeg and FFprobe Directly

>>> from ffmpegio import ffmpeg, FFprobe, ffmpegprocess

>>> from subprocess import PIPE

>>> # call with options as a long string

>>> ffmpeg('-i [Link] -b:v 64k -bufsize 64k [Link]')

>>> # or call with list of options

>>> ffmpeg(['-i', '[Link]' ,'-r', '24', '[Link]'])

>>> # the same for ffprobe

>>> ffprobe('ffprobe -show_streams -select_streams a INPUT')

>>> # specify subprocess arguments to capture stdout

>>> out = ffprobe('ffprobe -of json -show_frames INPUT',
stdout=PIPE, universal_newlines=True).stdout

>>> # use ffmpegprocess to take advantage of ffmpegio's default behaviors

>>> out = [Link]({"inputs": [("[Link]", None)],
"outputs": [("out1.mp4", None),
("-", {"f": "rawvideo", "vframes": 1, "pix_fmt": "gray", "an": None})
} capture log=True)

README GPL-2.0 license

Releases 35

v0.10.0 Latest
5 days ago

+ 34 releases

Packages

No packages published

Contributors 3

tikuma-lsuhsc Kesh Ikuma

[Link] 5/6
7/8/24, 11:25 PM GitHub - python-ffmpegio/python-ffmpegio: Python package to read/write media files with FFmpeg

hokiedsp Kesh Ikuma

dependabot[bot]

Languages

Python 98.5% Jupyter Notebook 1.3% Other 0.2%

[Link] 6/6