Tweak wording and fix wrong references in RoomSimulator docs

audiomentations/augmentations/room_simulator.py

@@ -15,8 +15,8 @@ class RoomSimulator(BaseWaveformTransform):
     average surface absorption coefficient. It also includes a source \
     and microphones in parametrized locations.
 
-    Use it when you want a ton of synthetic room impulse responses of specific configurations
-    characteristics or simply to quickly add reverb for augmentation purposes
+    Use it when you need a large number of synthetic room impulse responses with specific configuration
+    characteristics or simply to quickly add reverb for augmentation purposes.
 
     Some examples:
 
@@ -26,10 +26,10 @@ class RoomSimulator(BaseWaveformTransform):
     > augment = RoomSimulator(calculation_mode="rt60", min_target_rt60=0.06, max_target_rt60=0.06, min_size_x = ...)
     Augment with randomly selected room impulse responses that have an RT60 of 0.06.
 
-    > augment = RoomSimulator(min_mic_radius=1.0, max_min_radius=1.0)
+    > augment = RoomSimulator(min_mic_distance=1.0, max_mic_distance=1.0)
     Augment with a RIR captured by all positions of the microphone on a sphere, centred around the source at 1m
 
-    > augment = RoomSimulator(min_mic_radius=1.0, max_min_radius=1.0, min_mic_elevation=0.0, max_mic_elevation=0.0)
+    > augment = RoomSimulator(min_mic_distance=1.0, max_mic_distance=1.0, min_mic_elevation=0.0, max_mic_elevation=0.0)
     Augment with a RIR captured by all positions of the microphone on a circle, centred around the source at 1m    
     """
 
@@ -57,8 +57,8 @@ def __init__(
         max_mic_distance: float = 0.35,
         min_mic_azimuth: float = -np.pi,
         max_mic_azimuth: float = np.pi,
-        min_mic_elevation: float = -np.pi,
-        max_mic_elevation: float = np.pi,
+        min_mic_elevation: float = -np.pi,  # TODO: Check if it should default to -np.pi / 2 instead
+        max_mic_elevation: float = np.pi,  # TODO: Check if it should default to np.pi / 2 instead
         calculation_mode: str = "absorption",
         use_ray_tracing: bool = True,
         max_order: int = 1,
@@ -86,7 +86,7 @@ def __init__(
         :param max_absorption_value:
 
         :param min_target_rt60: When `calculation_mode` is `rt60`, it tries to set the absorption value
-            of the surfaces of the room to achieve a target rt60 (in seconds). Note that this parameter
+            of the surfaces of the room to achieve a target RT60 (in seconds). Note that this parameter
             changes only the materials (absorption coefficients) of the surfaces, NOT the dimension of the rooms.
 
             Example values (may differ!):
@@ -105,14 +105,13 @@ def __init__(
         :param min_mic_azimuth: Minimum azimuth (angle around z axis) of the microphone
             relative to the source, in radians.
         :param max_mic_azimuth:
-        :param min_mic_elevation:
-            Minimum elevation of the microphone relative to the source, in radians.
-        :param max_mic_elevation:
+        :param min_mic_elevation: Minimum elevation of the microphone relative to the source, in radians.
+        :param max_mic_elevation: Maximum elevation of the microphone relative to the source, in radians.
         :param calculation_mode: When set to `absorption`, it will create the room with surfaces based on
             `min_absorption_value` and `max_absorption_value`. If set to `rt60` it will try to assign surface
-            materials that lead to a room impulse response with target rt60 given by `min_target_rt60` and `max_target_rt60`
+            materials that lead to a room impulse response with target RT60 given by `min_target_rt60` and `max_target_rt60`
         :param use_ray_tracing: Whether to use ray_tracing or not (slower but much more accurate).
-            Disable this if you need speed but do not really care for incorrect results.
+            Disable this if you prioritize speed over accuracy.
         :param max_order: Maximum order of reflections for the Image Source Model. E.g. a value of
             1 will only add first order reflections while a value of 4 will add a
             diffuse reverberation tail. *Warning* Placing this higher than 11-12 will result

docs/waveform_transforms/room_simulator.md

@@ -5,8 +5,8 @@ _Added in v0.23.0_
 A ShoeBox Room Simulator. Simulates a cuboid of parametrized size and average surface absorption coefficient. It also includes a source
 and microphones in parametrized locations.
 
-Use it when you want a ton of synthetic room impulse responses of specific configurations
-characteristics or simply to quickly add reverb for augmentation purposes
+Use it when you need a large number of synthetic room impulse responses with specific configuration
+characteristics or simply to quickly add reverb for augmentation purposes.
 
 ## RoomSimulator API
 
@@ -78,13 +78,13 @@ characteristics or simply to quickly add reverb for augmentation purposes
 [`min_source_y`](#min_source_y){ #min_source_y }: `float` • unit: meters
 :   :octicons-milestone-24: Default: `0.1`. Minimum y location of the source
 
-[`max_source_x`](#max_source_x){ #max_source_x }: `float` • unit: meters
+[`max_source_y`](#max_source_y){ #max_source_y }: `float` • unit: meters
 :   :octicons-milestone-24: Default: `2.7`. Maximum y location of the source
 
 [`min_source_z`](#min_source_z){ #min_source_z }: `float` • unit: meters
 :   :octicons-milestone-24: Default: `1.0`. Minimum z location of the source
 
-[`max_source_x`](#max_source_x){ #max_source_x }: `float` • unit: meters
+[`max_source_z`](#max_source_z){ #max_source_z }: `float` • unit: meters
 :   :octicons-milestone-24: Default: `2.1`. Maximum z location of the source
 
 [`min_mic_distance`](#min_mic_distance){ #min_mic_distance }: `float` • unit: meters
@@ -117,14 +117,13 @@ characteristics or simply to quickly add reverb for augmentation purposes
     [`min_absorption_value`](#min_absorption_value){ #min_absorption_value } and
     [`max_absorption_value`](#max_absorption_value){ #max_absorption_value }. If set to
     `"rt60"` it will try to assign surface materials that lead to a room impulse
-    response with target rt60 given by
+    response with target RT60 given by
     [`min_target_rt60`](#min_target_rt60){ #min_target_rt60 } and
     [`max_target_rt60`](#max_target_rt60){ #max_target_rt60 }
 
 [`use_ray_tracing`](#use_ray_tracing){ #use_ray_tracing }: `bool`
 :   :octicons-milestone-24: Default: `True`. Whether to use ray_tracing or not (slower
-    but much more accurate). Disable this if you need speed but do not really care for
-    incorrect results.
+    but much more accurate). Disable this if you prioritize speed over accuracy.
 
 [`max_order`](#max_order){ #max_order }: `int` • range: [1, ∞)
 :   :octicons-milestone-24: Default: `1`. Maximum order of reflections for the Image