diff --git a/docs/source/_templates/autosummary/io_class.rst b/docs/source/_templates/autosummary/io_class.rst index 9d8692f4d9..1b748d93ff 100644 --- a/docs/source/_templates/autosummary/io_class.rst +++ b/docs/source/_templates/autosummary/io_class.rst @@ -14,6 +14,8 @@ .. autoclass:: {{ fullname }} +{%- if name not in ["StreamReader", "StreamWriter"] %} + {%- if attributes %} Properties @@ -54,37 +56,4 @@ Methods {%- endfor %} {%- endif %} - -{%- if name in ["StreamReader", "StreamWriter"] %} - -Support Structures ------------------- - -{%- if name == "StreamReader" %} -{%- for item in [ - "ChunkTensor", - "SourceStream", - "SourceAudioStream", - "SourceVideoStream", - "OutputStream", - "OutputAudioStream", - "OutputVideoStream", -] %} - -{{ item | underline("~") }} - -.. autoclass:: torio.io._streaming_media_decoder.{{item}}() - :members: - -{%- endfor %} - -{%- elif name == "StreamWriter" %} - -CodecConfig -~~~~~~~~~~~ - -.. autoclass:: torchaudio.io::CodecConfig - :members: - -{%- endif %} {%- endif %} diff --git a/docs/source/_templates/autosummary/torio_io_class.rst b/docs/source/_templates/autosummary/torio_io_class.rst new file mode 100644 index 0000000000..f83820ca6d --- /dev/null +++ b/docs/source/_templates/autosummary/torio_io_class.rst @@ -0,0 +1,90 @@ +.. + autogenerated from source/_templates/autosummary/torio_io_class.rst + +{#- + ################################################################################ + # autosummary template for torio.io module + # Since StreamingMediaDecoder/StreamingMediaEncoder have many methods/properties, + # we want to list them up in the table of contents. + # The default class template does not do this, so we use custom one here. + ################################################################################ +#} + +{{ name | underline }} + +.. autoclass:: {{ fullname }} + +{%- if attributes %} + +Properties +---------- + +{%- for item in attributes %} +{%- if not item.startswith('_') and item not in inherited_members %} + +{{ item | underline("~") }} + +.. container:: py attribute + + .. autoproperty:: {{[fullname, item] | join('.')}} + +{%- endif %} +{%- endfor %} +{%- endif %} + +{%- if members %} + +Methods +------- + +{%- for item in members %} +{%- if + not item.startswith('_') + and item not in inherited_members + and item not in attributes + %} + +{{ item | underline("~") }} + +.. container:: py attribute + + .. automethod:: {{[fullname, item] | join('.')}} + +{%- endif %} +{%- endfor %} +{%- endif %} + + +{%- if name in ["StreamingMediaDecoder", "StreamingMediaEncoder"] %} + +Support Structures +------------------ + +{%- if name == "StreamingMediaDecoder" %} +{%- for item in [ + "ChunkTensor", + "SourceStream", + "SourceAudioStream", + "SourceVideoStream", + "OutputStream", + "OutputAudioStream", + "OutputVideoStream", +] %} + +{{ item | underline("~") }} + +.. autoclass:: torio.io._streaming_media_decoder::{{item}}() + :members: + +{%- endfor %} + +{%- elif name == "StreamingMediaEncoder" %} + +CodecConfig +~~~~~~~~~~~ + +.. autoclass:: torio.io::CodecConfig + :members: + +{%- endif %} +{%- endif %} diff --git a/docs/source/conf.py b/docs/source/conf.py index 31b7c22b85..86fa180175 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -385,13 +385,6 @@ def inject_minigalleries(app, what, name, obj, options, lines): def setup(app): app.connect("autodoc-process-docstring", inject_minigalleries) - from torchaudio.io import StreamReader, StreamWriter - - # need to assign the names here, otherwise autodoc won't document these classes, - # and will instead just say 'alias of ...' - StreamReader.__name__ = "StreamReader" - StreamWriter.__name__ = "StreamWriter" - from custom_directives import CustomCardEnd, CustomCardItem, CustomCardStart, SupportedDevices, SupportedProperties diff --git a/docs/source/index.rst b/docs/source/index.rst index 98540d912a..bf6ffe7246 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -108,6 +108,13 @@ model implementations and application components. kaldi_io utils +.. toctree:: + :maxdepth: 1 + + torio + torio.io + torio.utils + .. toctree:: :maxdepth: 1 :caption: Python Prototype API Reference diff --git a/docs/source/installation.rst b/docs/source/installation.rst index dc4a52df78..b219f878fb 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -48,13 +48,13 @@ Optional Dependencies compatible FFmpeg libraries. If you need to specify the version of FFmpeg TorchAudio searches and links, you can - specify it via the environment variable ``TORCHAUDIO_USE_FFMPEG_VERSION``. For example, - by setting ``TORCHAUDIO_USE_FFMPEG_VERSION=5``, TorchAudio will only look for FFmpeg + specify it via the environment variable ``TORIO_USE_FFMPEG_VERSION``. For example, + by setting ``TORIO_USE_FFMPEG_VERSION=5``, TorchAudio will only look for FFmpeg 5. If for some reason, this search mechanism is causing an issue, you can disable the FFmpeg integration entirely by setting the environment variable - ``TORCHAUDIO_USE_FFMPEG=0``. + ``TORIO_USE_FFMPEG=0``. There are multiple ways to install FFmpeg libraries. If you are using Anaconda Python distribution, diff --git a/docs/source/torio.io.rst b/docs/source/torio.io.rst new file mode 100644 index 0000000000..9398418148 --- /dev/null +++ b/docs/source/torio.io.rst @@ -0,0 +1,20 @@ +.. py:module:: torio.io + +torio.io +======== + +.. currentmodule:: torio.io + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: autosummary/torio_io_class.rst + + StreamingMediaDecoder + StreamingMediaEncoder + +.. rubric:: Tutorials using ``torio.io`` + +.. minigallery:: torio.io + +.. minigallery:: torchaudio.io diff --git a/docs/source/torio.rst b/docs/source/torio.rst new file mode 100644 index 0000000000..c7da9bad4b --- /dev/null +++ b/docs/source/torio.rst @@ -0,0 +1,16 @@ +.. py:module:: torio + +torio +===== + +.. currentmodule:: torio.io + +``torio`` is an alternative top-level module for I/O features. The is the extraction of the core implementation of I/O feature of ``torchaudio``. + +If you want to use the multimedia processing features, but do not want to depend on the entire ``torchaudio`` package, you can use ``torio``. + +.. note:: + + Currently, ``torio`` is distributed alongside ``torchaudio``, and there is no stand-alone + procedure to install ``torio`` only. Please refer to https://pytorch.org/get-started/locally/ + for the installation of ``torchaudio``. diff --git a/docs/source/torio.utils.rst b/docs/source/torio.utils.rst new file mode 100644 index 0000000000..7f8712f4c2 --- /dev/null +++ b/docs/source/torio.utils.rst @@ -0,0 +1,15 @@ +.. py:module:: torio.utils + +torio.utils +=========== + +``torio.utils`` module contains utility functions to query and configure the global state of third party libraries. + +.. currentmodule:: torio.utils + +.. autosummary:: + :toctree: generated + :nosignatures: + :template: autosummary/utils.rst + + ffmpeg_utils