Skip to content

Commit 024dbda

Browse files
tikuma-lsuhsctikuma-lsuhsc
committed
docs update
1 parent 272fe00 commit 024dbda

10 files changed

Lines changed: 164 additions & 152 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
66

77
## [Unreleased]
88

9+
### Changed
10+
11+
- allow writers' `extra_inputs` arguments to be `str` or `tuple[str, dict|None]`
12+
- `probe` functions accepts PathLike object as the media url
13+
14+
### Added
15+
16+
- `media` module - block
17+
- `PipedStreams` module - media stream classes with multiple inputs and outputs.
18+
19+
### Removed
20+
21+
- `build_basic_vf()` options from video readers and filters. Users can generate
22+
equivalent filter chains via `filtergraph.presets.filter_video_basic()`.
23+
924
## [0.12.0] - 2026-05-25
1025

1126
### Added

‎Makefile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
# You can set these variables from the command line, and also
55
# from the environment for the first two.
6-
SPHINXOPTS ?=
6+
SPHINXOPTS ?= -j auto -n -v -W -T
77
SPHINXBUILD ?= sphinx-build
88
SOURCEDIR = docsrc
99
BUILDDIR = build

‎docsrc/analysis.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88

99
There are a number of `FFmpeg filters <https://ffmpeg.org/ffmpeg-filters.html>`_ which analyze video
1010
and audio streams and inject per-frame results into frame metadata to be used in a later stage of
11-
a filtergraph. :py:mod:`ffmpegio.analyze.run` retrieves the injected metadata by appending ``metadata``
11+
a filtergraph. :py:mod:`run` retrieves the injected metadata by appending ``metadata``
1212
and ``ametadata`` filters and logs the frame metadata outputs. You can use either the supplied Python
1313
classes or a custom class, which conforms to :py:class:`MetadataLogger` interface to specify the FFmpeg
1414
filter and to log its output.
@@ -88,10 +88,10 @@ Analyze API Reference
8888
:nosignatures:
8989
:recursive:
9090

91-
ffmpegio.analyze.run
91+
run
9292
ffmpegio.video.detect
9393
ffmpegio.audio.detect
94-
ffmpegio.analyze.MetadataLogger
94+
MetadataLogger
9595

9696
.. autofunction:: ffmpegio.analyze.run
9797
.. autofunction:: ffmpegio.video.detect

‎docsrc/conf.py‎

Lines changed: 47 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
project = "python-ffmpegio"
2222
copyright = (
23-
"2021-2022, Takeshi (Kesh) Ikuma, Louisiana State University Health Sciences Center"
23+
"2021-2026, Takeshi (Kesh) Ikuma, Louisiana State University Health Sciences Center"
2424
)
2525
author = "Takeshi (Kesh) Ikuma"
2626
release = ffmpegio.__version__
@@ -36,12 +36,37 @@
3636
"sphinx.ext.intersphinx",
3737
"sphinx.ext.autosummary",
3838
"sphinx.ext.todo",
39-
"sphinxcontrib.blockdiag",
40-
"sphinxcontrib.repl",
39+
# "sphinx.ext.graphviz",
40+
# "sphinxcontrib.repl",
4141
"matplotlib.sphinxext.plot_directive",
4242
]
4343
# Looks for objects in external projects
4444

45+
46+
# Autodoc configuration
47+
autodoc_member_order = "groupwise"
48+
autodoc_type_aliases = {
49+
"ArrayLike": "~numpy.typing.ArrayLike",
50+
"NDArray": "~numpy.typing.NDArray",
51+
"ff": "ffmpegio",
52+
}
53+
autodoc_mock_imports = ["builtins"]
54+
autodoc_typehints_format = "short"
55+
# autodoc_class_signature = "separated"
56+
autodoc_default_options = {"exclude-members": "__new__", "class-doc-from": "init"}
57+
autodoc_typehints = "description"
58+
59+
overloads_location = "signature"
60+
61+
# Intersphinx configuration
62+
intersphinx_mapping = {
63+
"python": ("https://docs.python.org/3", None),
64+
"numpy": ("https://numpy.org/doc/stable/", None),
65+
"scipy": ("https://docs.scipy.org/doc/scipy/", None),
66+
"matplotlib": ("https://matplotlib.org/stable/", None),
67+
"python": ("https://docs.python.org/3/", None),
68+
}
69+
4570
autodoc_typehints = "description"
4671
# autodoc_type_aliases = {'AgentAssignment': 'AgentAssignment'}
4772

@@ -53,29 +78,38 @@
5378
# This pattern also affects html_static_path and html_extra_path.
5479
exclude_patterns = []
5580

81+
# The name of the Pygments (syntax highlighting) style to use.
82+
pygments_style = "sphinx"
83+
84+
copybutton_selector = "div:not(.output_area) > div.highlight > pre"
85+
86+
graphviz_output_format = "svg"
5687

5788
# -- Options for HTML output -------------------------------------------------
5889

5990
# The theme to use for HTML and HTML Help pages. See the documentation for
6091
# a list of builtin themes.
6192
#
62-
html_theme = "sphinx_rtd_theme"
93+
html_theme = "sphinx_book_theme"
6394

6495
# Add any paths that contain custom static files (such as style sheets) here,
6596
# relative to this directory. They are copied after the builtin static files,
6697
# so a file named "default.css" will overwrite the builtin "default.css".
6798
html_static_path = ["_static"]
6899

69-
# html_sidebars = {
70-
# "**": ["globaltoc.html", "relations.html", "sourcelink.html", "searchbox.html"]
71-
# }
72-
73-
# Fontpath for blockdiag (truetype font)
74-
blockdiag_fontpath = "_static/ipagp.ttf"
75-
blockdiag_html_image_format = "SVG"
76100

77-
intersphinx_mapping = {
78-
"numpy": ("https://numpy.org/doc/stable", None),
101+
# html_logo = "images/logo.png"
102+
html_theme_options = {
103+
# "logo": {
104+
# "image_light": "images/wave-reflection-model-light.png",
105+
# "image_dark": "images/wave-reflection-model-dark.png",
106+
# },
107+
"path_to_docs": "docs/",
108+
"repository_url": "https://github.com/tikuma-lsuhsc/pyLeTalker",
109+
# "repository_branch": branch_or_commit,
110+
"use_repository_button": True,
111+
"use_source_button": True,
112+
"show_toc_level": 2,
79113
}
80114

81115
plot_html_show_source_link = False

‎docsrc/filtergraph.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,9 @@ These functions are served by three classes:
3030
:nosignatures:
3131
:recursive:
3232

33-
ffmpegio.filtergraph.Filter
34-
ffmpegio.filtergraph.Chain
35-
ffmpegio.filtergraph.Graph
33+
Filter
34+
Chain
35+
Graph
3636

3737
See :ref:`api` section below for the full documentation of these classes
3838
and other helper functions.
@@ -528,7 +528,7 @@ temporary script file. The previous example can also run as follows:
528528
with fg.as_script_file() as script_path:
529529
ffmpegio.ffmpegprocess.run(
530530
{
531-
'inputs': [('input.mp4', None)]
531+
'inputs': [('input.mp4', None)],
532532
'outputs': [('output.mp4', {'filter_script:v': script_path})]
533533
})
534534

‎docsrc/index.rst‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@
1414
.. |github-status| image:: https://img.shields.io/github/actions/workflow/status/python-ffmpegio/python-ffmpegio/test_n_pub.yml?branch=main
1515
:alt: GitHub Workflow Status
1616

17+
* GitHub Repository <https://github.com/python-ffmpegio/python-ffmpegio>
18+
* GitHub Discussion Board <https://github.com/python-ffmpegio/python-ffmpegio/discussions>
19+
1720
Python `ffmpegio` package aims to bring the full capability of `FFmpeg <https://ffmpeg.org>`__
1821
to read, write, probe, and manipulate multimedia data to Python. FFmpeg is an open-source cross-platform
1922
multimedia framework, which can handle most of the multimedia formats available today.
@@ -40,10 +43,13 @@ Main Features
4043
* I/O device enumeration to eliminate the need to look up device names. (currently supports only: Windows DirectShow)
4144
* More features to follow
4245

43-
Installation
44-
------------
4546

46-
Install the full `ffmpegio` package via ``pip``:
47+
Where to start
48+
--------------
49+
50+
* Read :ref:`Quick-start guide <quick>`
51+
52+
* Install via ``pip``:
4753

4854
.. code-block:: bash
4955
@@ -413,3 +419,45 @@ Run FFmpeg and FFprobe Directly
413419
}, capture_log=True)
414420
>>> print(out.stderr) # print the captured FFmpeg logs (banner text omitted)
415421
>>> b = out.stdout # width*height bytes of the first frame
422+
423+
Introductory Info
424+
-----------------
425+
426+
.. toctree::
427+
:maxdepth: 1
428+
429+
quick
430+
install
431+
432+
433+
High-level API Reference
434+
------------------------
435+
436+
.. toctree::
437+
:maxdepth: 1
438+
439+
basicio
440+
probe
441+
options
442+
filtergraph
443+
caps
444+
analysis
445+
devices
446+
concat
447+
448+
Advanced Topics
449+
---------------
450+
451+
.. toctree::
452+
:maxdepth: 1
453+
454+
adv-ffmpeg
455+
adv-args
456+
457+
External Links
458+
--------------
459+
460+
.. toctree::
461+
:maxdepth: 1
462+
463+
links

‎docsrc/install.rst‎

Lines changed: 28 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -18,41 +18,54 @@ Install the :py:mod:`ffmpegio` package via :code:`pip`.
1818
Install FFmpeg program
1919
^^^^^^^^^^^^^^^^^^^^^^
2020

21-
There are two platform independent approaches to install FFmpeg for the use in Python:
21+
There are two Python libraries to install FFmpeg for the use in Python:
2222

23-
::code::`ffmpeg-downloader`
24-
"""""""""""""""""""""""""""
23+
The installation of FFmpeg is platform dependent. One platform agnostic approach
24+
is to use our sister package:
25+
`ffmpeg-downloader <https://github.com/python-ffmpegio/python-ffmpeg-downloader>`__.
26+
27+
Install with `ffmpeg-downloader`
28+
""""""""""""""""""""""""""""""""
29+
30+
First, install the `ffmpegio-downloader` package, then run its cli command `ffdl`:
2531

2632
.. code-block::
33+
2734
pip install ffmpeg-downloader
28-
ffdl install -U # grabs the latest version
35+
ffdl install
2936
30-
# optionally
31-
ffdl install -U --add-path to have it on the system path in Windows or MacOS
37+
If you wish to use the FFmpeg outside of `ffmpegio`, you can also install and add
38+
the installed directory to the user's system path (only for Windows and MacOS).
3239

33-
::code::`static-ffmpeg`
34-
"""""""""""""""""""""""
40+
.. code-block::
41+
42+
# optionally
43+
ffdl install --add-path
3544
45+
At a later date, you could re-run `ffdl` to look for an update (similar to `pip`):
46+
I
3647
.. code-block::
37-
pip install static-ffmpeg
38-
static_ffmpeg_paths
3948
40-
The installation of FFmpeg is platform dependent. For Ubuntu/Debian Linux,
49+
ffdl install -U
50+
51+
Install on Ubuntu/Debian Linux
52+
""""""""""""""""""""""""""""""
4153

4254
.. code-block::
4355
4456
sudo apt install ffmpeg
4557
46-
and for MacOS,
58+
Install on MacOS
59+
""""""""""""""""
4760

4861
.. code-block::
4962
5063
brew install ffmpeg
5164
52-
no other actions are needed as these commands will place the FFmpeg executables
53-
on the system path.
65+
Install on Windows
66+
""""""""""""""""""
5467

55-
For Windows, it is a bit more complicated.
68+
It is a bit more complicated in Windows.
5669

5770
1. Download pre-built packages from the links available on the `FFmpeg's Download page
5871
<https://ffmpeg.org/download.html#build-windows>`__.

0 commit comments

Comments
 (0)