Skip to content

Commit 216d37f

Browse files
tikuma-lsuhsctikuma-lsuhsc
committed
docs update
1 parent d646483 commit 216d37f

8 files changed

Lines changed: 213 additions & 80 deletions

File tree

‎README.rst‎

Lines changed: 93 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,13 @@
1515
:alt: GitHub Workflow Status
1616

1717
Python `ffmpegio` package aims to bring the full capability of `FFmpeg <https://ffmpeg.org>`__
18-
to read, write, and manipulate multimedia data to Python. FFmpeg is an open-source cross-platform
18+
to read, write, probe, and manipulate multimedia data to Python. FFmpeg is an open-source cross-platform
1919
multimedia framework, which can handle most of the multimedia formats available today.
2020

21-
Since v0.3.0, `ffmpegio` Python distribution package has been split into `ffmpegio-core` and `ffmpegio` to allow
22-
Numpy-independent installation.
21+
.. note::
22+
23+
Since v0.3.0, `ffmpegio` Python distribution package has been split into `ffmpegio-core` and `ffmpegio` to allow
24+
Numpy-independent installation.
2325

2426
Install the full `ffmpegio` package via ``pip``:
2527

@@ -46,7 +48,8 @@ Main Features
4648
* Accepts all FFmpeg options including filter graphs
4749
* Supports a user callback whenever FFmpeg updates its progress information file
4850
(see `-progress` FFmpeg option)
49-
* Advanced users can gain finer controls of FFmpeg I/O with `ffmpegio.ffmpegprocess` submodule
51+
* `ffconcat` scripter to make the use of `-f concat` demuxer easier
52+
* I/O device enumeration to eliminate the need to look up device names. (currently supports only: Windows DirectShow)
5053
* More features to follow
5154

5255
Documentation
@@ -63,6 +66,20 @@ To import `ffmpegio`
6366
6467
>>> import ffmpegio
6568
69+
- `Transcoding <ex_trancode>`__
70+
- `Read Audio Files <ex_read_audio>`__
71+
- `Read Image Files / Capture Video Frames <ex_read_image>`__
72+
- `Read Video Files <ex_read_video>`__
73+
- `Read Multiple Files or Streams <ex_read_media>`__
74+
- `Write Audio, Image, & Video Files <ex_write>`__
75+
- `Filter Audio, Image, & Video Data <ex_filter>`__
76+
- `Stream I/O <ex_stream>`__
77+
- `Device I/O Enumeration <ex_devices>`__
78+
- `Progress Callback <ex_progress>`__
79+
- `Run FFmpeg and FFprobe Directly <ex_direct>`__
80+
81+
.. _ex_trancode:
82+
6683
Transcoding
6784
^^^^^^^^^^^
6885

@@ -79,6 +96,15 @@ Transcoding
7996
>>> ffmpegio.transcode('input.avi', 'output.mkv', two_pass=True, show_log=True,
8097
>>> **{'c:v':'libx264', 'b:v':'2600k', 'c:a':'aac', 'b:a':'128k'})
8198
99+
>>> # concatenate videos using concat demuxer
100+
>>> files = ['/video/video1.mkv','/video/video2.mkv']
101+
>>> ffconcat = ffmpegio.FFConcat()
102+
>>> ffconcat.add_files(files)
103+
>>> with ffconcat: # generates temporary ffconcat file
104+
>>> ffmpegio.transcode(ffconcat, 'output.mkv', f_in='concat', codec='copy', safe_in=0)
105+
106+
.. _ex_read_audio:
107+
82108
Read Audio Files
83109
^^^^^^^^^^^^^^^^
84110

@@ -95,6 +121,8 @@ Read Audio Files
95121
>>> # filter: equalizer which attenuate 10 dB at 1 kHz with a bandwidth of 200 Hz
96122
>>> fs, x = ffmpegio.audio.read('myaudio.mp3', t=10.0, af='equalizer=f=1000:t=h:width=200:g=-10')
97123
124+
.. _ex_read_image:
125+
98126
Read Image Files / Capture Video Frames
99127
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
100128

@@ -125,6 +153,8 @@ Read Image Files / Capture Video Frames
125153
>>> I = ffmpegio.image.read('myaudio.mp3', filter_complex='showspectrumpic=s=960x540', pix_fmt='rgb24')
126154
127155
156+
.. _ex_read_video:
157+
128158
Read Video Files
129159
^^^^^^^^^^^^^^^^
130160

@@ -136,7 +166,9 @@ Read Video Files
136166
137167
>>> # get running spectrogram of audio input (must specify pix_fmt if input is audio)
138168
>>> fs, F = ffmpegio.video.read('myvideo.mp4', pix_fmt='rgb24', filter_complex='showspectrum=s=1280x480')
169+
139170
171+
.. _ex_read_media:
140172

141173
Read Multiple Files or Streams
142174
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -157,6 +189,8 @@ Read Multiple Files or Streams
157189
>>> # rates: dict of frame rates: keys="v:0" and "v:1"
158190
>>> # data: dict of video frame arrays: keys="v:0" and "v:1"
159191
192+
.. _ex_write:
193+
160194
Write Audio, Image, & Video Files
161195
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
162196

@@ -171,7 +205,9 @@ Write Audio, Image, & Video Files
171205
>>> # create an audio file from a numpy array
172206
>>> ffmpegio.audio.write('myaudio.mp3', rate, x)
173207
174-
Filter Audio, Image, & Video data
208+
.. _ex_filter:
209+
210+
Filter Audio, Image, & Video Data
175211
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
176212

177213
.. code-block:: python
@@ -186,6 +222,8 @@ Filter Audio, Image, & Video data
186222
>>> filter = "drawtext=fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
187223
>>> fs_out, F_out = ffmpegio.video.filter(filter, fs_in, F_in)
188224
225+
.. _ex_stream:
226+
189227
Stream I/O
190228
^^^^^^^^^^
191229

@@ -198,10 +236,28 @@ Stream I/O
198236
>>> for frames in fin:
199237
>>> fout.write(myprocess(frames))
200238
239+
.. _ex_devices:
240+
241+
Device I/O Enumeration
242+
^^^^^^^^^^^^^^^^^^^^^^
243+
244+
.. code-block:: python
245+
246+
>>> # record 5 minutes of audio from Windows microphone
247+
>>> fs, x = ffmpegio.audio.read('a:0', f_in='dshow', sample_fmt='dbl', t=300)
201248
202-
Progress callback
249+
>>> # capture Windows' webcam frame
250+
>>> with ffmpegio.open('v:0', 'rv', f_in='dshow') as webcam,
251+
>>> for frame in webcam:
252+
>>> process_frame(frame)
253+
254+
.. _ex_progress:
255+
256+
Progress Callback
203257
^^^^^^^^^^^^^^^^^
204258

259+
.. code-block:: python
260+
205261
>>> import pprint
206262
207263
>>> # progress callback
@@ -219,3 +275,34 @@ Progress callback
219275
>>> with ffmpegio.open('myvideo.mp4', 'rv', blocksize=100, progress=progress) as fin:
220276
>>> for frames in fin:
221277
>>> myprocess(frames)
278+
279+
.. _ex_direct:
280+
281+
Run FFmpeg and FFprobe Directly
282+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
283+
284+
.. code-block:: python
285+
286+
>>> from ffmpegio import ffmpeg, FFprobe, ffmpegprocess
287+
>>> from subprocess import PIPE
288+
289+
>>> # call with options as a long string
290+
>>> ffmpeg('-i input.avi -b:v 64k -bufsize 64k output.avi')
291+
292+
>>> # or call with list of options
293+
>>> ffmpeg(['-i', 'input.avi' ,'-r', '24', 'output.avi'])
294+
295+
>>> # the same for ffprobe
296+
>>> ffprobe('ffprobe -show_streams -select_streams a INPUT')
297+
298+
>>> # specify subprocess arguments to capture stdout
299+
>>> out = ffprobe('ffprobe -of json -show_frames INPUT',
300+
stdout=PIPE, universal_newlines=True).stdout
301+
302+
>>> # use ffmpegprocess to take advantage of ffmpegio's default behaviors
303+
>>> out = ffmpegprocess.run({"inputs": [("input.avi", None)],
304+
"outputs": [("out1.mp4", None),
305+
("-", {"f": "rawvideo", "vframes": 1, "pix_fmt": "gray", "an": None})
306+
}, capture_log=True)
307+
>>> print(out.stderr) # print the captured FFmpeg logs (banner text omitted)
308+
>>> b = out.stdout # width*height bytes of the first frame

‎docsrc/index.rst‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ Features
3232
* Accepts all FFmpeg options including filter graphs
3333
* Supports a user callback whenever FFmpeg updates its progress information file
3434
(see `-progress` FFmpeg option)
35+
* `ffconcat` scripter to make the use of `-f concat` demuxer easier
36+
* I/O device enumeration to eliminate the need to look up device names. (currently supports only: Windows DirectShow)
3537
* Advanced users can gain finer controls of FFmpeg I/O with :py:mod:`ffmpegio.ffmpegprocess` submodule
3638

3739
.. * (planned) Multi-stream read/write
@@ -64,6 +66,21 @@ To import :py:mod:`ffmpegio`
6466
6567
>>> import ffmpegio
6668
69+
70+
- :ref:`ex_trancode`
71+
- :ref:`ex_read_audio`
72+
- :ref:`ex_read_image`
73+
- :ref:`ex_read_video`
74+
- :ref:`ex_read_media`
75+
- :ref:`ex_write`
76+
- :ref:`ex_filter`
77+
- :ref:`ex_stream`
78+
- :ref:`ex_devices`
79+
- :ref:`ex_progress`
80+
- :ref:`ex_direct`
81+
82+
.. _ex_trancode:
83+
6784
Transcoding
6885
^^^^^^^^^^^
6986

@@ -80,6 +97,15 @@ Transcoding
8097
>>> ffmpegio.transcode('input.avi', 'output.mkv', two_pass=True, show_log=True,
8198
>>> **{'c:v':'libx264', 'b:v':'2600k', 'c:a':'aac', 'b:a':'128k'})
8299
100+
>>> # concatenate videos using concat demuxer
101+
>>> files = ['/video/video1.mkv','/video/video2.mkv']
102+
>>> ffconcat = ffmpegio.FFConcat()
103+
>>> ffconcat.add_files(files)
104+
>>> with ffconcat: # generates temporary ffconcat file
105+
>>> ffmpegio.transcode(ffconcat, 'output.mkv', f_in='concat', codec='copy', safe_in=0)
106+
107+
.. _ex_read_audio:
108+
83109
Read Audio Files
84110
^^^^^^^^^^^^^^^^
85111

@@ -96,6 +122,8 @@ Read Audio Files
96122
>>> # filter: equalizer which attenuate 10 dB at 1 kHz with a bandwidth of 200 Hz
97123
>>> fs, x = ffmpegio.audio.read('myaudio.mp3', t=10.0, af='equalizer=f=1000:t=h:width=200:g=-10')
98124
125+
.. _ex_read_image:
126+
99127
Read Image Files / Capture Video Frames
100128
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
101129

@@ -126,6 +154,8 @@ Read Image Files / Capture Video Frames
126154
>>> I = ffmpegio.image.read('myaudio.mp3', filter_complex='showspectrumpic=s=960x540', pix_fmt='rgb24')
127155
128156
157+
.. _ex_read_video:
158+
129159
Read Video Files
130160
^^^^^^^^^^^^^^^^
131161

@@ -139,6 +169,8 @@ Read Video Files
139169
>>> fs, F = ffmpegio.video.read('myvideo.mp4', pix_fmt='rgb24', filter_complex='showspectrum=s=1280x480')
140170
141171
172+
.. _ex_read_media:
173+
142174
Read Multiple Files or Streams
143175
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
144176

@@ -158,6 +190,8 @@ Read Multiple Files or Streams
158190
>>> # rates: dict of frame rates: keys="v:0" and "v:1"
159191
>>> # data: dict of video frame arrays: keys="v:0" and "v:1"
160192
193+
.. _ex_write:
194+
161195
Write Audio, Image, & Video Files
162196
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
163197

@@ -172,6 +206,8 @@ Write Audio, Image, & Video Files
172206
>>> # create an audio file from a numpy array
173207
>>> ffmpegio.audio.write('myaudio.mp3', rate, x)
174208
209+
.. _ex_filter:
210+
175211
Filter Audio, Image, & Video data
176212
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
177213

@@ -187,6 +223,8 @@ Filter Audio, Image, & Video data
187223
>>> filter = "drawtext=fontsize=30:fontfile=FreeSerif.ttf:text='hello world':x=(w-text_w)/2:y=(h-text_h)/2"
188224
>>> fs_out, F_out = ffmpegio.video.filter(filter, fs_in, F_in)
189225
226+
.. _ex_stream:
227+
190228
Stream I/O
191229
^^^^^^^^^^
192230

@@ -199,9 +237,28 @@ Stream I/O
199237
>>> for frames in fin:
200238
>>> fout.write(myprocess(frames))
201239
240+
.. _ex_devices:
241+
242+
Device I/O Enumeration
243+
^^^^^^^^^^^^^^^^^^^^^^
244+
245+
.. code-block:: python
246+
247+
>>> # record 5 minutes of audio from Windows microphone
248+
>>> fs, x = ffmpegio.audio.read('a:0', f_in='dshow', sample_fmt='dbl', t=300)
249+
250+
>>> # capture Windows' webcam frame
251+
>>> with ffmpegio.open('v:0', 'rv', f_in='dshow') as webcam,
252+
>>> for frame in webcam:
253+
>>> process_frame(frame)
254+
255+
.. _ex_progress:
256+
202257
Progress callback
203258
^^^^^^^^^^^^^^^^^
204259

260+
.. code-block:: python
261+
205262
>>> import pprint
206263
207264
>>> # progress callback
@@ -220,6 +277,37 @@ Progress callback
220277
>>> for frames in fin:
221278
>>> myprocess(frames)
222279
280+
.. _ex_direct:
281+
282+
Run FFmpeg and FFprobe Directly
283+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
284+
285+
.. code-block:: python
286+
287+
>>> from ffmpegio import ffmpeg, FFprobe, ffmpegprocess
288+
>>> from subprocess import PIPE
289+
290+
>>> # call with options as a long string
291+
>>> ffmpeg('-i input.avi -b:v 64k -bufsize 64k output.avi')
292+
293+
>>> # or call with list of options
294+
>>> ffmpeg(['-i', 'input.avi' ,'-r', '24', 'output.avi'])
295+
296+
>>> # the same for ffprobe
297+
>>> ffprobe('ffprobe -show_streams -select_streams a INPUT')
298+
299+
>>> # specify subprocess arguments to capture stdout
300+
>>> out = ffprobe('ffprobe -of json -show_frames INPUT',
301+
stdout=PIPE, universal_newlines=True).stdout
302+
303+
>>> # use ffmpegprocess to take advantage of ffmpegio's default behaviors
304+
>>> out = ffmpegprocess.run({"inputs": [("input.avi", None)],
305+
"outputs": [("out1.mp4", None),
306+
("-", {"f": "rawvideo", "vframes": 1, "pix_fmt": "gray", "an": None})
307+
}, capture_log=True)
308+
>>> print(out.stderr) # print the captured FFmpeg logs (banner text omitted)
309+
>>> b = out.stdout # width*height bytes of the first frame
310+
223311
Introductory Info
224312
-----------------
225313

‎docsrc/probe.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ List of Functions
2020
ffmpegio.probe.audio_streams_basic
2121
ffmpegio.probe.full_details
2222
ffmpegio.probe.query
23+
ffmpegio.probe.frames
2324

2425
Function References
2526
-------------------
@@ -30,3 +31,4 @@ Function References
3031
.. autofunction:: ffmpegio.probe.audio_streams_basic
3132
.. autofunction:: ffmpegio.probe.full_details
3233
.. autofunction:: ffmpegio.probe.query
34+
.. autofunction:: ffmpegio.probe.frames

‎src/ffmpegio/audio.py‎

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -110,18 +110,7 @@ def create(
110110
111111
.. note:: Either `duration` or `nb_samples` filter options must be set.
112112
113-
Supported Audio Source Filters
114-
------------------------------
115-
116-
============= ==============================================================================
117-
filter name description
118-
============= ==============================================================================
119-
"aevalsrc" an audio signal specified by an expression
120-
"anoisesrc" a noise audio signal
121-
"sine" audio signal made of a sine wave with amplitude 1/8
122-
============= ==============================================================================
123-
124-
https://ffmpeg.org/ffmpeg-filters.html#Audio-Sources
113+
See https://ffmpeg.org/ffmpeg-filters.html#Audio-Sources for available video source filters
125114
126115
ouptut data object is determined by the selected `bytes_to_audio` hook
127116

‎src/ffmpegio/caps.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ def options(type=None, name_only=False, return_desc=False):
5555
"""get FFmpeg command options
5656
5757
:param type: specify option type to return, defaults to None
58-
:type type: "per-file"|"video"|"audio"|"subtitle"|"general"|"global"|None, optional
58+
:type type: "per-file"\|"video"\|"audio"\|"subtitle"\|"general"\|"global"\|None, optional
5959
:param name_only: True to only return option names, defaults to False
6060
:type name_only: bool, optional
6161
:param return_desc: True to also return option description, defaults to False

0 commit comments

Comments
 (0)