Update Documents and add tests for rbargs

README.md

@@ -30,4 +30,6 @@ Example usage
 >>> y, sr = sf.read("test.wav")
 >>> # Play back at double speed
 >>> y_stretch = pyrb.time_stretch(y, sr, 2.0)
+>>> # Pass rbargs supported in Rubberband CLI. See(rubberband -h or https://breakfastquay.com/rubberband/usage.txt)
+>>> y_stretch = pyrb.time_stretch(y, sr, 2.0, rbargs={'-c':'5', '--no_transients':''})
 ```

pyrubberband/pyrb.py

@@ -113,9 +113,11 @@ def time_stretch(y, sr, rate, rbargs=None):
     rate : float > 0
         Desired playback rate.
 
-    rbargs
+    rbargs : {key:value, key:value}
         Additional keyword parameters for rubberband
-
+        Accepts a dictionary of key:value pairs supported by `rubberband`.
+        type(key and value) == str()
+        For single valued `rbargs`, pass empty string for `value`.
         See `rubberband -h` for details.
 
     Returns
@@ -168,9 +170,11 @@ def timemap_stretch(y, sr, time_map, rbargs=None):
         `time_map[-1]` must correspond to the lengths of the source audio and
         target audio.
 
-    rbargs
+    rbargs : {key:value, key:value}
         Additional keyword parameters for rubberband
-
+        Accepts a dictionary of key:value pairs supported by `rubberband`.
+        type(key and value) == str()
+        For single valued `rbargs`, pass empty string for `value`.
         See `rubberband -h` for details.
 
     Returns
@@ -236,9 +240,11 @@ def pitch_shift(y, sr, n_steps, rbargs=None):
     n_steps : float
         Shift by `n_steps` semitones.
 
-    rbargs
+    rbargs : {key:value, key:value}
         Additional keyword parameters for rubberband
-
+        Accepts a dictionary of key:value pairs supported by `rubberband`.
+        type(key and value) == str()
+        For single valued `rbargs`, pass empty string for `value`.
         See `rubberband -h` for details.
 
     Returns

tests/test_pyrb.py

@@ -64,18 +64,28 @@ def random_signal(channels, num_samples):
     return np.random.random(shape)
 
 
+@pytest.fixture(params=[{'-c': '5'}, {'--realtime': '', '--pitch-hq': ''},
+                        {'--no-lamination': ''}, {'--formant': '', '--no-transients': ''}])
+def unit_pitch_rbargs(request):
+    return request.param
+
+
 @pytest.mark.parametrize(
-    "rate,ctx",
+    "rate,unit_stretch_rbargs,ctx",
     [
-        (0.5, dnr()),
-        (1.0, dnr()),
-        (2.0, dnr()),
-        (-1, pytest.raises(ValueError)),
-        (-0.5, pytest.raises(ValueError)),
-        (0, pytest.raises(ValueError)),
+        (0.5, {'-c': '0', '--formant': ''}, dnr()),
+        (0.5, {'-c': '5'}, dnr()),
+        (0.5, {}, dnr()),
+        (1.0, {'--loose': ''}, dnr()),
+        (1.0, {'--no-transients': ''}, dnr()),
+        (2.0, {'--no-lamination': '', '--no-transients': '', '--window-long': ''}, dnr()),
+        (-1, {'-c': '5'}, pytest.raises(ValueError)),
+        (-1, {'--no-lamination': '', '--no-transients': '', '--window-long': ''}, pytest.raises(ValueError)),
+        (-0.5, {}, pytest.raises(ValueError)),
+        (0, {}, pytest.raises(ValueError)),
     ]
 )
-def test_stretch(sr, random_signal, num_samples, rate, ctx):
+def test_stretch(sr, random_signal, num_samples, rate, ctx, unit_stretch_rbargs):
     '''Test shape of random signals with stretching
     factor of various rate.
     '''
@@ -84,7 +94,7 @@ def test_stretch(sr, random_signal, num_samples, rate, ctx):
     y = random_signal
 
     with ctx:
-        y_s = pyrubberband.time_stretch(y, sr, rate=rate)
+        y_s = pyrubberband.time_stretch(y, sr, rate=rate, rbargs=unit_stretch_rbargs)
 
         # test if output dimension matches input dimension
         assert y_s.ndim == y.ndim
@@ -98,11 +108,10 @@ def test_stretch(sr, random_signal, num_samples, rate, ctx):
             assert np.allclose(y_s.shape[0] * rate, y.shape[0])
 
 
-def test_pitch(sr, num_samples, freq, n_step):
-
+def test_pitch(sr, num_samples, freq, n_step, unit_pitch_rbargs):
     y = synth(sr, num_samples, freq)
 
-    y_s = pyrubberband.pitch_shift(y, sr, n_step)
+    y_s = pyrubberband.pitch_shift(y, sr, n_step, rbargs=unit_pitch_rbargs)
 
     # Make sure we have the same duration
     assert np.allclose(len(y), len(y_s))