Changes in / [4bc10e2:ed596f7]

Location:

python/lib/aubio

Files:

• midiconv.py (modified) (3 diffs)
• slicing.py (modified) (1 diff)

python/lib/aubio/midiconv.py

@@ -16 +16 @@
 
 def note2midi(note):
-    " convert note name to midi note number, e.g. [C-1, G9] -> [0, 127] "
+    """Convert note name to midi note number.
+
+    Input string `note` should be composed of one note root
+    and one octave, with optionally one modifier in between.
+
+    List of valid components:
+
+    - note roots: `C`, `D`, `E`, `F`, `G`, `A`, `B`,
+    - modifiers: `b`, `#`, as well as unicode characters
+      `𝄫`, `♭`, `♮`, `♯` and `𝄪`,
+    - octave numbers: `-1` -> `11`.
+
+    Parameters
+    ----------
+    note : str
+        note name
+
+    Returns
+    -------
+    int
+        corresponding midi note number
+
+    Examples
+    --------
+    >>> aubio.note2midi('C#4')
+    61
+    >>> aubio.note2midi('B♭5')
+    82
+
+    Raises
+    ------
+    TypeError
+        If `note` was not a string.
+    ValueError
+        If an error was found while converting `note`.
+
+    See Also
+    --------
+    midi2note, freqtomidi, miditofreq
+    """
     _valid_notenames = {'C': 0, 'D': 2, 'E': 4, 'F': 5, 'G': 7, 'A': 9, 'B': 11}
     _valid_modifiers = {
@@ -62 +101 @@
 
 def midi2note(midi):
-    " convert midi note number to note name, e.g. [0, 127] -> [C-1, G9] "
+    """Convert midi note number to note name.
+
+    Parameters
+    ----------
+    midi : int [0, 128]
+        input midi note number
+
+    Returns
+    -------
+    str
+        note name
+
+    Examples
+    --------
+    >>> aubio.midi2note(70)
+    'A#4'
+    >>> aubio.midi2note(59)
+    'B3'
+
+    Raises
+    ------
+    TypeError
+        If `midi` was not an integer.
+    ValueError
+        If `midi` is out of the range `[0, 128]`.
+
+    See Also
+    --------
+    note2midi, miditofreq, freqtomidi
+    """
     if not isinstance(midi, int_instances):
         raise TypeError("an integer is required, got %s" % midi)
@@ -73 +141 @@
 
 def freq2note(freq):
-    " convert frequency in Hz to nearest note name, e.g. [0, 22050.] -> [C-1, G9] "
+    """Convert frequency in Hz to nearest note name.
+
+    Parameters
+    ----------
+    freq : float [0, 23000[
+        input frequency, in Hz
+
+    Returns
+    -------
+    str
+        name of the nearest note
+
+    Example
+    -------
+    >>> aubio.freq2note(440)
+    'A4'
+    >>> aubio.freq2note(220.1)
+    'A3'
+    """
     nearest_note = int(freqtomidi(freq) + .5)
     return midi2note(nearest_note)

python/lib/aubio/slicing.py

@@ -9 +9 @@
                            output_dir=None, samplerate=0, hopsize=256,
                            create_first=False):
-    """ slice a sound file at given timestamps """
+    """Slice a sound file at given timestamps.
+
+    This function reads `source_file` and creates slices, new smaller
+    files each starting at `t` in `timestamps`, a list of integer
+    corresponding to time locations in `source_file`, in samples.
+
+    If `timestamps_end` is unspecified, the slices will end at
+    `timestamps_end[n] = timestamps[n+1]-1`, or the end of file.
+    Otherwise, `timestamps_end` should be a list with the same length
+    as `timestamps` containing the locations of the end of each slice.
+
+    If `output_dir` is unspecified, the new slices will be written in
+    the current directory. If `output_dir` is a string, new slices
+    will be written in `output_dir`, after creating the directory if
+    required.
+
+    The default `samplerate` is 0, meaning the original sampling rate
+    of `source_file` will be used. When using a sampling rate
+    different to the one of the original files, `timestamps` and
+    `timestamps_end` should be expressed in the re-sampled signal.
+
+    The `hopsize` parameter simply tells :class:`source` to use this
+    hopsize and does not change the output slices.
+
+    If `create_first` is True and `timestamps` does not start with `0`, the
+    first slice from `0` to `timestamps[0] - 1` will be automatically added.
+
+    Parameters
+    ----------
+    source_file : str
+        path of the resource to slice
+    timestamps : :obj:`list` of :obj:`int`
+        time stamps at which to slice, in samples
+    timestamps_end : :obj:`list` of :obj:`int` (optional)
+        time stamps at which to end the slices
+    output_dir : str (optional)
+        output directory to write the slices to
+    samplerate : int (optional)
+        samplerate to read the file at
+    hopsize : int (optional)
+        number of samples read from source per iteration
+    create_first : bool (optional)
+        always create the slice at the start of the file
+
+    Examples
+    --------
+    Create two slices: the first slice starts at the beginning of the
+    input file `loop.wav` and lasts exactly one second, starting at
+    sample `0` and ending at sample `44099`; the second slice starts
+    at sample `44100` and lasts until the end of the input file:
+
+    >>> aubio.slice_source_at_stamps('loop.wav', [0, 44100])
+
+    Create one slice, from 1 second to 2 seconds:
+
+    >>> aubio.slice_source_at_stamps('loop.wav', [44100], [44100 * 2 - 1])
+
+    Notes
+    -----
+    Slices may be overlapping. If `timestamps_end` is `1` element
+    shorter than `timestamps`, the last slice will end at the end of
+    the file.
+    """
 
     if timestamps is None or len(timestamps) == 0: