From 70fad1daa6d49609d680f62b575239c2c4ac9352 Mon Sep 17 00:00:00 2001
From: Dudemanguy <random342@airmail.cc>
Date: Thu, 8 Aug 2024 12:37:20 -0500
Subject: [PATCH] DOCS/man: improve explanation on how to shift notes with
 --pitch

Previously, this was in the rubberband filter but it gives out random
numbers without explaning where they come from. Move it to the --pitch
section instead and reword it a bit. Closes #14652.
---
 DOCS/man/af.rst      |  5 +----
 DOCS/man/options.rst | 19 +++++++++++++++++++
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/DOCS/man/af.rst b/DOCS/man/af.rst
index 98f9a9597a..3a75c0822d 100644
--- a/DOCS/man/af.rst
+++ b/DOCS/man/af.rst
@@ -226,10 +226,7 @@ Available filters are:
         using the standard ``speed`` property, not ``af-command``.
 
     ``multiply-pitch <factor>``
-        Multiply the current value of ``<pitch-scale>`` dynamically.  For
-        example: 0.5 to go down by an octave, 1.5 to go up by a perfect fifth.
-        If you want to go up or down by semi-tones, use 1.059463094352953 and
-        0.9438743126816935
+        Multiply the current value of ``<pitch-scale>`` dynamically.
 
 ``lavfi=graph``
     Filter audio using FFmpeg's libavfilter.
diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst
index 9192b93cb3..ae4662c95d 100644
--- a/DOCS/man/options.rst
+++ b/DOCS/man/options.rst
@@ -242,6 +242,25 @@ Playback Control
     affect playback speed. Playing with an altered pitch automatically inserts
     the ``scaletempo2`` audio filter.
 
+    In a standard 12-tone scale system, octaves are separated by a factor of 2
+    whereas semitones are represented by a factor of 2^(1/12). This means
+    pitches can easily be shifted up or down with a simple multiplier.
+
+    .. admonition:: Examples
+
+        ``--pitch=2``
+            Shifts the pitch up a full octave.
+        ``--pitch=0.5``
+            Shifts the pitch down an octave.
+        ``--pitch=1.498307`` (2^(7/12))
+            Shifts the pitch up a perfect fifth.
+        ``--pitch=0.667420`` (2^(-7/12))
+            Shifts the pitch down a perfect fifth.
+        ``--pitch=1.059463`` (2^(1/12))
+            Shifts the pitch up a semitone.
+        ``--pitch=0.943874`` (2^(-1/12))
+            Shifts the pitch down a semitone.
+
 ``--pause``
     Start the player in paused state.