better naming conventions

Author: jiaaro

Diff for: API.markdown

@@ -378,15 +378,33 @@ Creates an equivalent version of this `AudioSegment` with the specified number o
 
 Splits a stereo `AudioSegment` into two, one for each channel (Left/Right). Returns a list with the new `AudioSegment` objects with the left channel at index 0 and the right channel at index 1. 
 
-### AudioSegment(…).set_gain(left_channel_gain, right_channel_gain)
+### AudioSegment(…).apply_gain_stereo()
 
+```python
+from pydub import AudioSegment
+sound1 = AudioSegment.from_file("sound1.wav")
+
+# make left channel 6dB quieter and right channe 2dB louder
+stereo_balance_adjusted = sound1.apply_gain_stereo(-6, +2)
+```
 Apply gain to the left and right channel of a stereo `AudioSegment`. If the `AudioSegment` is mono, it will be converted to stereo before applying the gain.
 
 Both gain arguments are specified in dB.
 
-### AudioSegment(…).pan(pan_amount)
+### AudioSegment(…).pan()
+
+```python
+from pydub import AudioSegment
+sound1 = AudioSegment.from_file("sound1.wav")
+
+# pan the sound 15% to the right
+panned_right = sound1.pan(+0.15)
+
+# pan the sound 50% to the left
+panned_left = sound1.pan(-0.50)
+```
 
-Takes one argument, `pan_amount`, which should be between -1.0 (100% left) and +1.0 (100% right)
+Takes one positional argument, *pan amount*, which should be between -1.0 (100% left) and +1.0 (100% right)
 
 When pan_amount == 0.0 the left/right balance is not changed.
 

Diff for: pydub/effects.py

@@ -276,13 +276,13 @@ def pan(seg, pan_amount):
     boost_db = boost_db / 2.0
 
     if pan_amount < 0:
-        return seg.set_gain(boost_db, reduce_db)
+        return seg.apply_gain_stereo(boost_db, reduce_db)
     else:
-        return seg.set_gain(reduce_db, boost_db)
+        return seg.apply_gain_stereo(reduce_db, boost_db)
 
 
 @register_pydub_effect
-def set_gain(seg, left_gain=0.0, right_gain=0.0):
+def apply_gain_stereo(seg, left_gain=0.0, right_gain=0.0):
     """
     left_gain - amount of gain to apply to the left channel (in dB)
     right_gain - amount of gain to apply to the right channel (in dB)

Diff for: setup.py

@@ -8,7 +8,7 @@
 
 setup(
     name='pydub',
-    version='0.13.0',
+    version='0.14.0',
     author='James Robert',
     author_email='[email protected]',
     description='Manipulate audio with an simple and easy high level interface',

Diff for: test/test.py

@@ -270,7 +270,7 @@ def test_split_to_mono(self):
         self.assertEqual(seg_rchannel.frame_count(), seg.frame_count())
 
 
-    def test_set_gain(self):
+    def test_apply_gain_stereo(self):
         seg = self.seg1
 
         orig_l, orig_r = seg.split_to_mono()
@@ -286,20 +286,20 @@ def assertAlmostEqual(v1, v2, **kwargs):
             else:
                 self.assertAlmostEqual(v1, v2, **kwargs)
 
-        def test_gain(left_dbfs_change, right_dbfs_change):
-            panned = seg.set_gain(left_dbfs_change, right_dbfs_change)
+        def check_stereo_gain(left_dbfs_change, right_dbfs_change):
+            panned = seg.apply_gain_stereo(left_dbfs_change, right_dbfs_change)
             self.assertEqual(panned.channels, 2)
 
             l, r = panned.split_to_mono()
             assertAlmostEqual(l.dBFS, orig_dbfs_l + left_dbfs_change, places=2)
             assertAlmostEqual(r.dBFS, orig_dbfs_r + right_dbfs_change, places=2)
 
         # hard left
-        test_gain(0.0, -inf)
-        test_gain(0.0, -6.0)
-        test_gain(0.0, 0.0)
-        test_gain(-6.0, 0.0)
-        test_gain(-inf, 0.0)
+        check_stereo_gain(0.0, -inf)
+        check_stereo_gain(0.0, -6.0)
+        check_stereo_gain(0.0, 0.0)
+        check_stereo_gain(-6.0, 0.0)
+        check_stereo_gain(-inf, 0.0)
 
     def test_pan(self):
         seg = self.seg1