Skip to content

Commit 4e46de9

Browse files
tikuma-lsuhschokiedsp
tikuma-lsuhsc
authored and
hokiedsp
committed
doc/typehint/format updates
1 parent 1cbfa00 commit 4e46de9

8 files changed

Lines changed: 87 additions & 33 deletions

File tree

‎docsrc/options.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ ncomp dtype pix_fmt Description
9292
4 <u2 rgba64le 16-bit RGB with alpha channel
9393
===== ===== ========= ===================================
9494

95-
Note that each video pixel format has a specific `dtype` (or `dtype_in`) str argument, which
95+
Note that each video pixel format has a specific `dtype` (or `input_dtype`) str argument, which
9696
follows the NumPy array data type convention.
9797

9898
Audio Sample Formats :code:`sample_fmt`

‎src/ffmpegio/_typing.py‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
from fractions import Fraction
99
from pathlib import Path
10-
from urllib.parse import ParseResult
10+
from urllib.parse import ParseResult as UrlParseResult
1111

1212

1313
if TYPE_CHECKING:
@@ -77,13 +77,58 @@
7777
"""
7878

7979
MediaType = Literal["audio", "video"]
80+
"""supported media stream types
81+
82+
=============== ================================================================
83+
value description
84+
=============== ================================================================
85+
`'video'` video stream
86+
`'audio'` audio stream
87+
=============== ================================================================
88+
"""
8089

8190
FFmpegMediaType = Literal["video", "audio", "subtitle", "data", "attachments"]
91+
"""FFmpeg media stream types
92+
93+
=============== ================================================================
94+
value description
95+
=============== ================================================================
96+
`'video'` video stream
97+
`'audio'` audio stream
98+
`'subtitle'` subtitle stream
99+
`'data'` data stream
100+
`'attachments'` attachments stream
101+
=============== ================================================================
102+
"""
82103

83-
FFmpegUrlType = str | Path | ParseResult
104+
FFmpegUrlType = str | Path | UrlParseResult
105+
"""input and output file/stream urls
106+
"""
84107

85108
FFmpegInputType = Literal["url", "filtergraph", "buffer", "fileobj"]
109+
"""mechanisms to feed input data to FFmpeg
110+
111+
=============== ================================================================
112+
value description
113+
=============== ================================================================
114+
`'url'` path to the input file or streaming url
115+
`'filtergraph'` input filtergraph
116+
`'buffer'` binary input data given as a bytes-like object or to be piped in
117+
`'fileobj'` open readable file object
118+
=============== ================================================================
119+
"""
120+
86121
FFmpegOutputType = Literal["url", "fileobj", "buffer"]
122+
"""mechanisms to extract output data from FFmpeg
123+
124+
=============== ============================================================================
125+
value description
126+
=============== ============================================================================
127+
`'url'` path to the output file or streaming url
128+
`'buffer'` buffer output data as `RawDataBlob` (raw stream) or `bytes` (encoded stream)
129+
`'fileobj'` open readable file object
130+
=============== ============================================================================
131+
"""
87132

88133

89134
class InputSourceDict(TypedDict):

‎src/ffmpegio/_utils.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ def is_non_str_sequence(
6969

7070
def as_multi_option(
7171
value: Any, exclude_classes: tuple[type] = str, SeqCls: type = list
72-
) -> Sequence[Any]:
72+
) -> Sequence[Any] | None:
7373
"""Put value in a list if it is not already a sequence
7474
7575
:param value: value to be put in a list
@@ -94,7 +94,7 @@ def dtype_itemsize(dtype: DTypeString) -> int:
9494
9595
:param dtype: numpy-style data type string
9696
:return: number of bytes per audio sample/video pixel
97-
"""
97+
"""
9898
return int(dtype[-1])
9999

100100

‎src/ffmpegio/configure.py‎

Lines changed: 19 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,26 @@
11
from __future__ import annotations
22

3-
from ._typing import (
3+
from typing_extensions import (
4+
IO,
45
Literal,
56
get_args,
7+
LiteralString,
68
Any,
7-
MediaType,
8-
FFmpegUrlType,
99
TypedDict,
10+
Unpack,
11+
Callable,
12+
)
13+
14+
from ._typing import (
1015
DTypeString,
1116
ShapeTuple,
1217
RawStreamInfoTuple,
1318
Buffer,
19+
MediaType,
20+
FFmpegUrlType,
1421
InputSourceDict,
1522
OutputDestinationDict,
1623
RawStreamDef,
17-
Unpack,
18-
Callable,
1924
RawDataBlob,
2025
FFmpegOptionDict,
2126
)
@@ -33,6 +38,7 @@
3338
from namedpipe import NPopen
3439
from contextlib import ExitStack
3540

41+
from . import ffmpegprocess as fp
3642
from . import utils, probe, plugins
3743
from . import filtergraph as fgb
3844
from .filtergraph.abc import FilterGraphObject
@@ -62,8 +68,10 @@
6268
UrlType = Literal["input", "output"]
6369

6470

65-
FFmpegInputOptionTuple = tuple[FFmpegUrlType | FilterGraphObject, FFmpegOptionDict]
66-
FFmpegOutputOptionTuple = tuple[FFmpegUrlType, FFmpegOptionDict]
71+
FFmpegInputOptionTuple = tuple[
72+
FFmpegUrlType | IO | Buffer | FilterGraphObject | FFConcat, FFmpegOptionDict
73+
]
74+
FFmpegOutputOptionTuple = tuple[FFmpegUrlType | IO, FFmpegOptionDict]
6775

6876
raw_formats = ("rawvideo", *(formats for _, formats in utils.audio_codecs.values()))
6977

@@ -672,13 +680,11 @@ def get_video_array_format(ffmpeg_args, type, file_id=0):
672680
return shape, dtype
673681

674682

675-
def move_global_options(args):
683+
def move_global_options(args: FFmpegArgs) -> FFmpegArgs:
676684
"""move global options from the output options dicts
677685
678686
:param args: FFmpeg arguments
679-
:type args: dict
680687
:returns: FFmpeg arguments (the same object as the input)
681-
:rtype: dict
682688
"""
683689

684690
from .caps import options
@@ -702,12 +708,10 @@ def move_global_options(args):
702708
return args
703709

704710

705-
def clear_loglevel(args):
711+
def clear_loglevel(args: FFmpegArgs):
706712
"""clear global loglevel option
707713
708714
:param args: FFmpeg argument dict
709-
:type args: dict
710-
711715
712716
"""
713717
try:
@@ -1251,7 +1255,7 @@ def process_url_inputs(
12511255
elif utils.is_url(url):
12521256
input_info = {"src_type": "url"}
12531257
elif isinstance(url, FFConcat):
1254-
#TODO - generalize this to handle an arbitrary Muxer class
1258+
# TODO - generalize this to handle an arbitrary Muxer class
12551259
opts["f"] = "concat"
12561260
url0 = url.url
12571261
if url0 in ("-", "unset"):
@@ -1731,7 +1735,7 @@ def init_media_read_outputs(
17311735
:param args: partial FFmpeg arguments (to be modified)
17321736
:param input_info: list of input information
17331737
:param output_options: tuple of mapping assignments and common output options
1734-
:param deferred_inputs: deferred (partial) input data, probable to retrieve
1738+
:param deferred_inputs: deferred (partial) input data, probable to retrieve
17351739
necessary stream information
17361740
:return output_info: output file information
17371741
"""

‎src/ffmpegio/filtergraph/presets.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
"""ffmpegio.filtergraph.presets Module - a collection of preset filtergraph generators
2-
"""
1+
"""ffmpegio.filtergraph.presets Module - a collection of preset filtergraph generators"""
32

43
from __future__ import annotations
54

‎src/ffmpegio/streams/PipedStreams.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
Literal,
1515
InputSourceDict,
1616
OutputDestinationDict,
17-
FFmpegOptionDict,
17+
FFmpegOptionDict,
1818
)
1919
from ..configure import (
2020
FFmpegArgs,

‎src/ffmpegio/threading.py‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
"""collection of thread classes for handling FFmpeg streams
2-
"""
1+
"""collection of thread classes for handling FFmpeg streams"""
32

43
from __future__ import annotations
54

@@ -32,6 +31,7 @@
3231

3332
class NotEmpty(Exception):
3433
"Exception raised by WriterThread.flush(timeout) if timedout."
34+
3535
pass
3636

3737

@@ -582,7 +582,6 @@ def run(self):
582582
if self.pipe is not None:
583583
self.pipe.close()
584584
elif not self.stdin.closed:
585-
print(f'{self.stdin.closed=}')
586585
self.stdin.close()
587586

588587
# completely flush the queue
@@ -988,7 +987,7 @@ def run(self):
988987
try:
989988
copyfileobj(src, dst, self.length)
990989
except:
991-
#TODO - test the behavior when FFmpeg is prematurely terminated
990+
# TODO - test the behavior when FFmpeg is prematurely terminated
992991
logger.warning("CopyFileObjThread runner failed to complete the job.")
993992
if self.auto_close:
994993
src.close()

‎src/ffmpegio/utils/__init__.py‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -538,6 +538,7 @@ def array_to_video_options(
538538
info,
539539
)
540540

541+
541542
def set_sp_kwargs_stdin(
542543
url: str | None, info: InputSourceDict, sp_kwargs: dict = {}
543544
) -> tuple[str, dict | None, Callable]:
@@ -613,8 +614,8 @@ def analyze_input_stream(
613614
fields: list[str],
614615
stream: str,
615616
media_type: MediaType,
616-
input_url: str | None,
617-
input_opts: dict,
617+
input_url: FFmpegUrlType | None,
618+
input_opts: FFmpegOptionDict,
618619
input_info: InputSourceDict,
619620
) -> list:
620621
"""analyze a stream and return requested field values
@@ -651,7 +652,10 @@ def video_fields_to_options(pix_fmt, width, height, r1, r2):
651652

652653

653654
def analyze_video_stream(
654-
stream_specifier: str, inurl: str, inopts: dict, input_info: InputSourceDict
655+
stream_specifier: str,
656+
inurl: FFmpegUrlType,
657+
inopts: FFmpegOptionDict,
658+
input_info: InputSourceDict,
655659
) -> tuple[int | Fraction | None, str | None, tuple[int, int] | None]:
656660
"""analyze video stream core attributes
657661
@@ -682,7 +686,10 @@ def analyze_video_stream(
682686

683687

684688
def analyze_audio_stream(
685-
stream_specifier: str, inurl: str, inopts: dict, input_info: InputSourceDict
689+
stream_specifier: str,
690+
inurl: FFmpegUrlType,
691+
inopts: FFmpegOptionDict,
692+
input_info: InputSourceDict,
686693
) -> tuple[int | None, str | None, int | None]:
687694
"""analyze input audio stream
688695
@@ -720,7 +727,7 @@ def analyze_audio_stream(
720727

721728
def analyze_complex_filtergraphs(
722729
filtergraphs: list[FilterGraphObject | str],
723-
inputs: list[tuple[str | None, dict]],
730+
inputs: list[tuple[FFmpegUrlType | None, FFmpegOptionDict]],
724731
inputs_info: list[InputSourceDict],
725732
) -> tuple[list[FilterGraphObject], dict[str, dict]]:
726733
"""analyze filtergraphs and return requested field values
@@ -858,7 +865,7 @@ def analyze_complex_filtergraphs(
858865

859866

860867
def are_input_pipes_ready(
861-
inputs: list[tuple[str, dict]],
868+
inputs: list[tuple[FFmpegUrlType, FFmpegOptionDict]],
862869
input_info: list[InputSourceDict],
863870
must_probe: bool = False,
864871
) -> list[bool]:

0 commit comments

Comments
 (0)