Changeset 07382d8 for python/lib


Ignore:
Timestamp:
Oct 31, 2018, 5:37:35 PM (6 years ago)
Author:
Paul Brossier <piem@piem.org>
Branches:
feature/autosink, feature/cnn, feature/cnn_org, feature/constantq, feature/crepe, feature/crepe_org, feature/pitchshift, feature/pydocstrings, feature/timestretch, fix/ffmpeg5, master
Children:
7a54b37
Parents:
9b23815e (diff), 78561f7 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.
Message:

Merge branch 'feature/docstrings' (see #73)

Location:
python/lib/aubio
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • python/lib/aubio/__init__.py

    r9b23815e r07382d8  
    11#! /usr/bin/env python
     2# -*- coding: utf8 -*-
     3
     4"""
     5aubio
     6=====
     7
     8Provides a number of classes and functions for music and audio signal
     9analysis.
     10
     11How to use the documentation
     12----------------------------
     13
     14Documentation of the python module is available as docstrings provided
     15within the code, and a reference guide available online from `the
     16aubio homepage <https://aubio.org/documentation>`_.
     17
     18The docstrings examples are written assuming `aubio` and `numpy` have been
     19imported with:
     20
     21>>> import aubio
     22>>> import numpy as np
     23"""
    224
    325import numpy
    … …  
    931
    1032class fvec(numpy.ndarray):
    11     """a numpy vector holding audio samples"""
     33    """fvec(input_arg=1024, **kwargs)
     34    A vector holding float samples.
    1235
     36    If `input_arg` is an `int`, a 1-dimensional vector of length `input_arg`
     37    will be created and filled with zeros. Otherwise, if `input_arg` is an
     38    `array_like` object, it will be converted to a 1-dimensional vector of
     39    type :data:`float_type`.
     40
     41    Parameters
     42    ----------
     43    input_arg : `int` or `array_like`
     44        Can be a positive integer, or any object that can be converted to
     45        a numpy array with :func:`numpy.array`.
     46    **kwargs
     47        Additional keyword arguments passed to :func:`numpy.zeros`, if
     48        `input_arg` is an integer, or to :func:`numpy.array`. Should not
     49        include `dtype`, which is already specified as
     50        :data:`aubio.float_type`.
     51
     52    Returns
     53    -------
     54    numpy.ndarray
     55        Array of shape `(length,)`.
     56
     57    Examples
     58    --------
     59    >>> aubio.fvec(10)
     60    array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0.], dtype=float32)
     61    >>> aubio.fvec([0,1,2])
     62    array([0., 1., 2.], dtype=float32)
     63    >>> a = np.arange(10); type(a), type(aubio.fvec(a))
     64    (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)
     65    >>> a.dtype, aubio.fvec(a).dtype
     66    (dtype('int64'), dtype('float32'))
     67
     68    Notes
     69    -----
     70
     71    In the Python world, `fvec` is simply a subclass of
     72    :class:`numpy.ndarray`. In practice, any 1-dimensional `numpy.ndarray` of
     73    `dtype` :data:`float_type` may be passed to methods accepting
     74    `fvec` as parameter. For instance, `sink()` or `pvoc()`.
     75
     76    See Also
     77    --------
     78    cvec : a container holding spectral data
     79    numpy.ndarray : parent class of :class:`fvec`
     80    numpy.zeros : create a numpy array filled with zeros
     81    numpy.array : create a numpy array from an existing object
     82    """
    1383    def __new__(cls, input_arg=1024, **kwargs):
    1484        if isinstance(input_arg, int):

  • python/lib/aubio/midiconv.py

    r9b23815e r07382d8  
    1616
    1717def note2midi(note):
    18     " convert note name to midi note number, e.g. [C-1, G9] -> [0, 127] "
     18    """Convert note name to midi note number.
     19
     20    Input string `note` should be composed of one note root
     21    and one octave, with optionally one modifier in between.
     22
     23    List of valid components:
     24
     25    - note roots: `C`, `D`, `E`, `F`, `G`, `A`, `B`,
     26    - modifiers: `b`, `#`, as well as unicode characters
     27      `𝄫`, `♭`, `♮`, `♯` and `𝄪`,
     28    - octave numbers: `-1` -> `11`.
     29
     30    Parameters
     31    ----------
     32    note : str
     33        note name
     34
     35    Returns
     36    -------
     37    int
     38        corresponding midi note number
     39
     40    Examples
     41    --------
     42    >>> aubio.note2midi('C#4')
     43    61
     44    >>> aubio.note2midi('B♭5')
     45    82
     46
     47    Raises
     48    ------
     49    TypeError
     50        If `note` was not a string.
     51    ValueError
     52        If an error was found while converting `note`.
     53
     54    See Also
     55    --------
     56    midi2note, freqtomidi, miditofreq
     57    """
    1958    _valid_notenames = {'C': 0, 'D': 2, 'E': 4, 'F': 5, 'G': 7, 'A': 9, 'B': 11}
    2059    _valid_modifiers = {
    … …  
    62101
    63102def midi2note(midi):
    64     " convert midi note number to note name, e.g. [0, 127] -> [C-1, G9] "
     103    """Convert midi note number to note name.
     104
     105    Parameters
     106    ----------
     107    midi : int [0, 128]
     108        input midi note number
     109
     110    Returns
     111    -------
     112    str
     113        note name
     114
     115    Examples
     116    --------
     117    >>> aubio.midi2note(70)
     118    'A#4'
     119    >>> aubio.midi2note(59)
     120    'B3'
     121
     122    Raises
     123    ------
     124    TypeError
     125        If `midi` was not an integer.
     126    ValueError
     127        If `midi` is out of the range `[0, 128]`.
     128
     129    See Also
     130    --------
     131    note2midi, miditofreq, freqtomidi
     132    """
    65133    if not isinstance(midi, int_instances):
    66134        raise TypeError("an integer is required, got %s" % midi)
    … …  
    73141
    74142def freq2note(freq):
    75     " convert frequency in Hz to nearest note name, e.g. [0, 22050.] -> [C-1, G9] "
     143    """Convert frequency in Hz to nearest note name.
     144
     145    Parameters
     146    ----------
     147    freq : float [0, 23000[
     148        input frequency, in Hz
     149
     150    Returns
     151    -------
     152    str
     153        name of the nearest note
     154
     155    Example
     156    -------
     157    >>> aubio.freq2note(440)
     158    'A4'
     159    >>> aubio.freq2note(220.1)
     160    'A3'
     161    """
    76162    nearest_note = int(freqtomidi(freq) + .5)
    77163    return midi2note(nearest_note)

  • python/lib/aubio/slicing.py

    r9b23815e r07382d8  
    99                           output_dir=None, samplerate=0, hopsize=256,
    1010                           create_first=False):
    11     """ slice a sound file at given timestamps """
     11    """Slice a sound file at given timestamps.
     12
     13    This function reads `source_file` and creates slices, new smaller
     14    files each starting at `t` in `timestamps`, a list of integer
     15    corresponding to time locations in `source_file`, in samples.
     16
     17    If `timestamps_end` is unspecified, the slices will end at
     18    `timestamps_end[n] = timestamps[n+1]-1`, or the end of file.
     19    Otherwise, `timestamps_end` should be a list with the same length
     20    as `timestamps` containing the locations of the end of each slice.
     21
     22    If `output_dir` is unspecified, the new slices will be written in
     23    the current directory. If `output_dir` is a string, new slices
     24    will be written in `output_dir`, after creating the directory if
     25    required.
     26
     27    The default `samplerate` is 0, meaning the original sampling rate
     28    of `source_file` will be used. When using a sampling rate
     29    different to the one of the original files, `timestamps` and
     30    `timestamps_end` should be expressed in the re-sampled signal.
     31
     32    The `hopsize` parameter simply tells :class:`source` to use this
     33    hopsize and does not change the output slices.
     34
     35    If `create_first` is True and `timestamps` does not start with `0`, the
     36    first slice from `0` to `timestamps[0] - 1` will be automatically added.
     37
     38    Parameters
     39    ----------
     40    source_file : str
     41        path of the resource to slice
     42    timestamps : :obj:`list` of :obj:`int`
     43        time stamps at which to slice, in samples
     44    timestamps_end : :obj:`list` of :obj:`int` (optional)
     45        time stamps at which to end the slices
     46    output_dir : str (optional)
     47        output directory to write the slices to
     48    samplerate : int (optional)
     49        samplerate to read the file at
     50    hopsize : int (optional)
     51        number of samples read from source per iteration
     52    create_first : bool (optional)
     53        always create the slice at the start of the file
     54
     55    Examples
     56    --------
     57    Create two slices: the first slice starts at the beginning of the
     58    input file `loop.wav` and lasts exactly one second, starting at
     59    sample `0` and ending at sample `44099`; the second slice starts
     60    at sample `44100` and lasts until the end of the input file:
     61
     62    >>> aubio.slice_source_at_stamps('loop.wav', [0, 44100])
     63
     64    Create one slice, from 1 second to 2 seconds:
     65
     66    >>> aubio.slice_source_at_stamps('loop.wav', [44100], [44100 * 2 - 1])
     67
     68    Notes
     69    -----
     70    Slices may be overlapping. If `timestamps_end` is `1` element
     71    shorter than `timestamps`, the last slice will end at the end of
     72    the file.
     73    """
    1274
    1375    if timestamps is None or len(timestamps) == 0:
Note: See TracChangeset for help on using the changeset viewer.