changeset 359:63871bac77f6

Rename functions

--- a/auditok/signal.py	Thu Apr 02 22:02:20 2020 +0200
+++ b/auditok/signal.py	Thu Apr 02 22:29:43 2020 +0200
@@ -18,7 +18,7 @@
     return samples[selected::channels]
 
 
-def average_channels(data, fmt, channels):
+def compute_average_channel(data, fmt, channels):
     all_channels = array(fmt, data)
     mono_channels = [
         array(fmt, all_channels[ch::channels]) for ch in range(channels)
@@ -30,7 +30,23 @@
     return avg_arr
 
 
-def average_channels_stereo(data, sample_width):
+def compute_average_channel_stereo(data, sample_width):
+    """Compute and return average channel (i.e., mix down channels) of stereo
+    data. When data is 2-channel, using standard `audioop` module is *much*
+    faster.
+
+    Parameters
+    ----------
+    data : bytes
+        2-channel audio data to mix down.
+    sample_width : int
+        size of audio samples (for 1 channel) in bytes.
+
+    Returns
+    -------
+    mono_audio : bytes
+        mixed down audio data.
+    """
     fmt = FORMAT[sample_width]
     arr = array(fmt, audioop.tomono(data, sample_width, 0.5, 0.5))
     return arr

--- a/auditok/signal_numpy.py	Thu Apr 02 22:02:20 2020 +0200
+++ b/auditok/signal_numpy.py	Thu Apr 02 22:29:43 2020 +0200
@@ -1,6 +1,6 @@
 import numpy as np
 from .signal import (
-    average_channels_stereo,
+    compute_average_channel_stereo,
     calculate_energy_single_channel,
     calculate_energy_multichannel,
 )
@@ -20,7 +20,7 @@
     return np.asanyarray(samples[selected::channels], order="C")
 
 
-def average_channels(data, fmt, channels):
+def compute_average_channel(data, fmt, channels):
     array = np.frombuffer(data, dtype=fmt).astype(np.float64)
     return array.reshape(-1, channels).mean(axis=1).round().astype(fmt)
 

--- a/auditok/util.py	Thu Apr 02 22:02:20 2020 +0200
+++ b/auditok/util.py	Thu Apr 02 22:29:43 2020 +0200
@@ -157,10 +157,13 @@
         if channels == 2:
             # when data is stereo, using audioop when possible is much faster
             return partial(
-                signal.average_channels_stereo, sample_width=sample_width
+                signal.compute_average_channel_stereo,
+                sample_width=sample_width,
             )
 
-        return partial(signal.average_channels, fmt=fmt, channels=channels)
+        return partial(
+            signal.compute_average_channel, fmt=fmt, channels=channels
+        )
 
     if selected in (None, "any"):
         return partial(signal.separate_channels, fmt=fmt, channels=channels)

--- a/tests/test_signal.py	Thu Apr 02 22:02:20 2020 +0200
+++ b/tests/test_signal.py	Thu Apr 02 22:29:43 2020 +0200
@@ -89,12 +89,12 @@
         int16_2channel=("h", 2, [12849, 13877, 16958]),
         int32_3channel=("i", 3, [971214132]),
     )
-    def test_average_channels(self, fmt, channels, expected):
-        result = signal_.average_channels(self.data, fmt, channels)
+    def test_compute_average_channel(self, fmt, channels, expected):
+        result = signal_.compute_average_channel(self.data, fmt, channels)
         expected = array_(fmt, expected)
         expected_numpy_fmt = self.numpy_fmt[fmt]
         self.assertEqual(result, expected)
-        result_numpy = signal_numpy.average_channels(
+        result_numpy = signal_numpy.compute_average_channel(
             self.data, self.numpy_fmt[fmt], channels
         )
         self.assertTrue(all(result_numpy == expected))
@@ -104,8 +104,10 @@
         int8_2channel=(1, [48, 50, 52, 54, 61, 66]),
         int16_2channel=(2, [12849, 13877, 16957]),
     )
-    def test_average_channels_stereo(self, sample_width, expected):
-        result = signal_.average_channels_stereo(self.data, sample_width)
+    def test_compute_average_channel_stereo(self, sample_width, expected):
+        result = signal_.compute_average_channel_stereo(
+            self.data, sample_width
+        )
         fmt = signal_.FORMAT[sample_width]
         expected = array_(fmt, expected)
         self.assertEqual(result, expected)