# HG changeset patch # User Amine Sehili # Date 1611256094 -3600 # Node ID 562b7a64b7eae3d1d56e22625f6801d5846d4beb # Parent d653e3f58f3c028f2a3922b02cc94f2b996f98f8 Improve documentation diff -r d653e3f58f3c -r 562b7a64b7ea auditok/core.py --- a/auditok/core.py Fri Jan 15 21:02:29 2021 +0100 +++ b/auditok/core.py Thu Jan 21 20:08:14 2021 +0100 @@ -28,7 +28,57 @@ def load(input, skip=0, max_read=None, **kwargs): """Load audio data from a source and return it as an :class:`AudioRegion`. - For more information about the parameters see :meth:`AudioRegion.load` + + Parameters + ---------- + input : None, str, bytes, AudioSource + source to read audio data from. If `str`, it should be a path to a + valid audio file. If `bytes`, it is used as raw audio data. If it is + "-", raw data will be read from stdin. If None, read audio data from + the microphone using PyAudio. If of type `bytes` or is a path to a + raw audio file then `sampling_rate`, `sample_width` and `channels` + parameters (or their alias) are required. If it's an + :class:`AudioSource` object it's used directly to read data. + skip : float, default: 0 + amount, in seconds, of audio data to skip from source. If read from + a microphone, `skip` must be 0, otherwise a `ValueError` is raised. + max_read : float, default: None + amount, in seconds, of audio data to read from source. If read from + microphone, `max_read` should not be None, otherwise a `ValueError` is + raised. + audio_format, fmt : str + type of audio data (e.g., wav, ogg, flac, raw, etc.). This will only + be used if `input` is a string path to an audio file. If not given, + audio type will be guessed from file name extension or from file + header. + sampling_rate, sr : int + sampling rate of audio data. Required if `input` is a raw audio file, + a `bytes` object or None (i.e., read from microphone). + sample_width, sw : int + number of bytes used to encode one audio sample, typically 1, 2 or 4. + Required for raw data, see `sampling_rate`. + channels, ch : int + number of channels of audio data. Required for raw data, see + `sampling_rate`. + large_file : bool, default: False + If True, AND if `input` is a path to a *wav* of a *raw* audio file + (and **only** these two formats) then audio file is not fully loaded to + memory in order to create the region (but the portion of data needed to + create the region is of course loaded to memory). Set to True if + `max_read` is significantly smaller then the size of a large audio file + that shouldn't be entirely loaded to memory. + + Returns + ------- + region: AudioRegion + + Raises + ------ + ValueError + raised if `input` is None (i.e., read data from microphone) and `skip` + != 0 or `input` is None `max_read` is None (meaning that when reading + from the microphone, no data should be skipped, and maximum amount of + data to read should be explicitly provided). """ return AudioRegion.load(input, skip, max_read, **kwargs) @@ -560,48 +610,15 @@ @meta.setter def meta(self, new_meta): + """Meta data of audio region. + """ self._meta = _AudioRegionMetadata(new_meta) @classmethod def load(cls, input, skip=0, max_read=None, **kwargs): """ - Create an `AudioRegion` by loading data from `input`. - - Parameters - ---------- - input : None, str, bytes, AudioSource - source to read audio data from. If `str`, it should be a path to a - valid audio file. If `bytes`, it is used as raw audio data. If it is - "-", raw data will be read from stdin. If None, read audio data from - the microphone using PyAudio. If of type `bytes` or is a path to a - raw audio file then `sampling_rate`, `sample_width` and `channels` - parameters (or their alias) are required. If it's an - :class:`AudioSource` object it's used directly to read data. - skip : float, default: 0 - amount, in seconds, of audio data to skip from source. If read from - a microphone, `skip` must be 0, otherwise a `ValueError` is raised. - max_read : float, default: None - amount, in seconds, of audio data to read from source. If read from - microphone, `max_read` should not be None, otherwise a ValueError is - raised. - audio_format, fmt : str - type of audio data (e.g., wav, ogg, flac, raw, etc.). This will only - be used if `input` is a string path to an audio file. If not given, - audio type will be guessed from file name extension or from file - header. - sampling_rate, sr : int - sampling rate of audio data. Required if `input` is a raw audio file, - a bytes object or None (i.e., read from microphone). - sample_width, sw : int - number of bytes used to encode one audio sample, typically 1, 2 or 4. - Required for raw data, see `sampling_rate`. - channels, ch : int - number of channels of audio data. Required for raw data, see - `sampling_rate`. - large_file : bool, default: False - If True, AND if `input` is a path to a *wav* of a *raw* audio file - (and only these two formats) then audio file is not fully loaded to - memory. Set to True to only load `max_read` data from file. + Create an `AudioRegion` by loading data from `input`. See :func:`load` + for parameters descripion. Returns ------- @@ -634,10 +651,15 @@ @property def seconds(self): + """ + A view to slice audio region by seconds (using ``region.seconds[start:end]``). + """ return self._seconds_view @property def millis(self): + """A view to slice audio region by milliseconds (using ``region.millis[start:end]``). + """ return self._millis_view @property @@ -651,26 +673,38 @@ @property def sampling_rate(self): + """Samling rate of audio data. + """ return self._sampling_rate @property def sr(self): + """Samling rate of audio data, alias for `sampling_rate`. + """ return self._sampling_rate @property def sample_width(self): + """Number of bytes per sample, one channel considered. + """ return self._sample_width @property def sw(self): + """Number of bytes per sample, alias for `sampling_rate`. + """ return self._sample_width @property def channels(self): + """Number of channels of audio data. + """ return self._channels @property def ch(self): + """Number of channels of audio data, alias for `channels`. + """ return self._channels def play(self, progress_bar=False, player=None, **progress_bar_kwargs): @@ -769,7 +803,7 @@ ): """Split audio region. See :func:`auditok.split()` for a comprehensive description of split parameters. - See Also :func:`AudioRegio.split_and_plot`. + See Also :meth:`AudioRegio.split_and_plot`. """ if kwargs.get("max_read", kwargs.get("mr")) is not None: warn_msg = "'max_read' (or 'mr') should not be used with " @@ -795,7 +829,24 @@ dpi=120, theme="auditok", ): - """Plot audio region. + """Plot audio region, one sub-plot for each channel. + + Parameters + ---------- + scale_signal : bool, default: True + if true, scale signal by subtracting its mean and dividing by its + standard deviation before plotting. + show : bool + whether to show plotted signal right after the call. + figsize : tuple, default: None + width and height of the figure to pass to `matplotlib`. + save_as : str, default None. + if provided, also save plot to file. + dpi : int, default: 120 + plot dpi to pass to `matplotlib`. + theme : str or dict, default: "auditok" + plot theme to use. Currently only "auditok" theme is implemented. To + provide you own them see :attr:`auditok.plotting.AUDITOK_PLOT_THEME`. """ try: from auditok.plotting import plot @@ -829,7 +880,7 @@ ): """Split region and plot signal and detections. Alias: :meth:`splitp`. See :func:`auditok.split()` for a comprehensive description of split - parameters. + parameters. Also see :meth:`plot` for plot parameters. """ try: from auditok.plotting import plot @@ -867,6 +918,8 @@ @property def samples(self): + """Audio region as arrays of samples, one array per channel. + """ if self._samples is None: self._samples = signal.to_array( self._data, self.sample_width, self.channels