Added semitones_to_ratio and ratio_to_semitones

Author: KentoNishi

docs/usage.md

@@ -169,6 +169,7 @@ Search for pitch-shift targets that can be computed quickly for a given sample r
     </tr>
   </tbody>
 </table>
+
 #### Return value
 
 <table>
@@ -186,6 +187,88 @@ Search for pitch-shift targets that can be computed quickly for a given sample r
   </tbody>
 </table>
 
+### `semitones_to_ratio`
+Convert semitonal shifts into ratios.
+
+<table>
+  <thead>
+    <tr>
+      <th>Argument</th>
+      <th>Required</th>
+      <th>Default Value</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>semitones</code></td>
+      <td>Yes</td>
+      <td></td>
+      <td><code>float</code></td>
+      <td>The number of semitones for a desired shift.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### Return value
+
+<table>
+  <thead>
+    <tr>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>Fraction</code></td>
+      <td>A Fraction indicating a pitch shift ratio</td>
+    </tr>
+  </tbody>
+</table>
+
+### `ratio_to_semitones`
+Convert rational shifts to semitones.
+
+<table>
+  <thead>
+    <tr>
+      <th>Argument</th>
+      <th>Required</th>
+      <th>Default Value</th>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>ratio</code></td>
+      <td>Yes</td>
+      <td></td>
+      <td><code>Fraction</code></td>
+      <td>The ratio for a desired shift.</td>
+    </tr>
+  </tbody>
+</table>
+
+#### Return value
+
+<table>
+  <thead>
+    <tr>
+      <th>Type</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>float</code></td>
+      <td>The magnitude of a pitch shift in semitones</td>
+    </tr>
+  </tbody>
+</table>
+
 ## Example
 
 See [example.py](https://github.com/KentoNishi/torch-pitch-shift/blob/master/example.py) to see an example of `torch-pitch-shift` in action!

torch_pitch_shift/main.py

@@ -2,11 +2,12 @@
 from fractions import Fraction
 from functools import reduce
 from itertools import chain, count, islice, repeat
-from typing import Union, Callable
+from typing import Union, Callable, List
 from torch.nn.functional import pad
 import torch
 import torchaudio.transforms as T
 from primePy import primes
+from math import log2
 import warnings
 
 warnings.simplefilter("ignore")
@@ -35,7 +36,7 @@ def _combinations_without_repetition(r, iterable=None, values=None, counts=None)
 
 def get_fast_shifts(
     sample_rate: int, condition: Callable = lambda x: x >= 0.5 and x <= 2 and x != 1
-):
+) -> List[Fraction]:
     """
     Search for pitch-shift targets that can be computed quickly for a given sample rate.
 
@@ -46,6 +47,11 @@ def get_fast_shifts(
     condition: Callable [optional]
         A function to validate fast shift ratios.
         Default is `lambda x: x >= 0.5 and x <= 2 and x != 1` (between -1 and +1 octaves).
+
+    Returns
+    -------
+    output: List[Fraction]
+        A list of fast pitch-shift target ratios
     """
     fast_shifts = set()
     factors = primes.factors(sample_rate)
@@ -65,6 +71,40 @@ def get_fast_shifts(
     return list(fast_shifts)
 
 
+def semitones_to_ratio(semitones: float) -> Fraction:
+    """
+    Convert semitonal shifts into ratios.
+
+    Parameters
+    ----------
+    semitones: float
+        The number of semitones for a desired shift.
+
+    Returns
+    -------
+    output: Fraction
+        A Fraction indicating a pitch shift ratio
+    """
+    return Fraction(2.0 ** (semitones / 12.0))
+
+
+def ratio_to_semitones(ratio: Fraction) -> float:
+    """
+    Convert rational shifts to semitones.
+
+    Parameters
+    ----------
+    ratio: Fraction
+        The ratio for a desired shift.
+
+    Returns
+    -------
+    output: float
+        The magnitude of a pitch shift in semitones
+    """
+    return float(12.0 * log2(ratio))
+
+
 def pitch_shift(
     input: torch.Tensor,
     shift: Union[float, Fraction],