Update docs with env vars used by Lhotse

README.md

@@ -99,6 +99,18 @@ This is an editable installation (`-e` option), meaning that your changes to the
 reflected when importing lhotse (no re-install needed). The `[dev]` part means you're installing extra dependencies
 that are used to run tests, build documentation or launch jupyter notebooks.
 
+### Environment variables
+
+Lhotse uses several environment variables to customize it's behavior. They are as follows:
+- `LHOTSE_REQUIRE_TORCHAUDIO` - when it's set and not any of `1|True|true|yes`, we'll not check for torchaudio being installed and remove it from the requirements. It will disable many functionalities of Lhotse but the basic capabilities will remain (including reading audio with `soundfile`).
+- `LHOTSE_AUDIO_DURATION_MISMATCH_TOLERANCE` - used when we load audio from a file and receive a different number of samples than declared in `Recording.num_samples`. This is sometimes necessary because different codecs (or even different versions of the same codec) may use different padding when decoding compressed audio. Typically values up to 0.1, or even 0.3 (second) are still reasonable, and anything beyond that indicates a serious issue.
+- `LHOTSE_AUDIO_BACKEND` - may be set to any of the values returned from CLI `lhotse list-audio-backends` to override the default behavior of trial-and-error and always use a specific audio backend.
+- `LHOTSE_AUDIO_LOADING_EXCEPTION_VERBOSE` - when set to `1` we'll emit full exception stack traces when every available audio backend fails to load a given file (they might be very large).
+- `LHOTSE_PREPARING_RELEASE` - used internally by developers when releasing a new version of Lhotse.
+- `TORCHAUDIO_USE_BACKEND_DISPATCHER` - when set to `1` and torchaudio version is below 2.1, we'll enable the experimental ffmpeg backend of torchaudio.
+- `RANK`, `WORLD_SIZE`, `WORKER`, and `NUM_WORKERS` are internally used to inform Lhotse Shar dataloading subprocesses.
+- `READTHEDOCS` is internally used for documentation builds.
+
 ### Optional dependencies
 
 **Other pip packages.** You can leverage optional features of Lhotse by installing the relevant supporting package like this: `pip install lhotse[package_name]`. The supported optional packages include:

docs/getting-started.rst

@@ -112,6 +112,27 @@ This is an editable installation (``-e`` option), meaning that your changes to t
 reflected when importing lhotse (no re-install needed). The ``[dev]`` part means you're installing extra dependencies
 that are used to run tests, build documentation or launch jupyter notebooks.
 
+Environment variables
+*********************
+
+Lhotse uses several environment variables to customize it's behavior. They are as follows:
+
+* ``LHOTSE_REQUIRE_TORCHAUDIO`` - when it's set and not any of ``1|True|true|yes``, we'll not check for torchaudio being installed and remove it from the requirements. It will disable many functionalities of Lhotse but the basic capabilities will remain (including reading audio with `soundfile`).
+
+* ``LHOTSE_AUDIO_DURATION_MISMATCH_TOLERANCE`` - used when we load audio from a file and receive a different number of samples than declared in ``Recording.num_samples``. This is sometimes necessary because different codecs (or even different versions of the same codec) may use different padding when decoding compressed audio. Typically values up to 0.1, or even 0.3 (second) are still reasonable, and anything beyond that indicates a serious issue.
+
+* ``LHOTSE_AUDIO_BACKEND`` - may be set to any of the values returned from CLI ``lhotse list-audio-backends`` to override the default behavior of trial-and-error and always use a specific audio backend.
+
+* ``LHOTSE_AUDIO_LOADING_EXCEPTION_VERBOSE`` - when set to 1 we'll emit full exception stack traces when every available audio backend fails to load a given file (they might be very large).
+
+* ``LHOTSE_PREPARING_RELEASE`` - used internally by developers when releasing a new version of Lhotse.
+
+* ``TORCHAUDIO_USE_BACKEND_DISPATCHER`` - when set to 1 and torchaudio version is below 2.1, we'll enable the experimental ffmpeg backend of torchaudio.
+
+* ``RANK``, ``WORLD_SIZE``, ``WORKER``, and ``NUM_WORKERS`` are internally used to inform Lhotse Shar dataloading subprocesses.
+
+* ``READTHEDOCS`` is internally used for documentation builds.
+
 
 Optional dependencies
 *********************