Enabling users to set the soundfont on midi playback (#2274)

Author: AlexanderGroeger

buildconfig/stubs/pygame/mixer.pyi

@@ -36,6 +36,8 @@ def set_num_channels(count: int) -> None: ...
 def get_num_channels() -> int: ...
 def set_reserved(count: int) -> int: ...
 def find_channel(force: bool = False) -> Channel: ...
+def set_soundfont(paths: Optional[str] = None) -> None: ...
+def get_soundfont() -> Optional[str]: ...
 def get_busy() -> bool: ...
 def get_sdl_mixer_version(linked: bool = True) -> Tuple[int, int, int]: ...
 

docs/reST/ref/mixer.rst

@@ -230,6 +230,43 @@ change the default buffer by calling :func:`pygame.mixer.pre_init` before
 
    .. ## pygame.mixer.find_channel ##
 
+.. function:: set_soundfont
+
+   | :sl:`set the soundfont for playing midi music`
+   | :sg:`set_soundfont(path) -> None`
+
+   This sets the soundfont file to be used in the playback of midi music.
+   The soundfont only affects the playback of ``MID``, ``MIDI``, and ``KAR`` file formats.
+   The optional ``path`` argument, a string (or multiple strings separated by a semi-colon),
+   must point to the soundfont file(s) to be searched for in order given if some
+   are missing. If ``path`` is an empty string or the default (``None``), any specified soundfont paths
+   will be cleared from the mixer.
+
+   Note on Windows, the mixer always uses the built-in soundfont instead of the one specified.
+
+   Function :func:`set_soundfont` calls underlying SDL_mixer function
+   ``Mix_SetSoundFonts``.
+
+   .. versionadded:: 2.3.1
+
+   .. ## pygame.mixer.set_soundfont ##
+
+.. function:: get_soundfont
+
+   | :sl:`get the soundfont for playing midi music`
+   | :sg:`get_soundfont() -> paths`
+
+   This gets the soundfont filepaths as a string (each path is separated by a semi-colon) 
+   to be used in the playback of ``MID``, ``MIDI``, and ``KAR`` music file formats. If no
+   soundfont is specified, the return type is ``None``.
+
+   Function :func:`get_soundfont` calls underlying SDL_mixer function
+   ``Mix_GetSoundFonts``.
+
+   .. versionadded:: 2.3.1
+
+   .. ## pygame.mixer.get_soundfont ##
+
 .. function:: get_busy
 
    | :sl:`test if any sound is being mixed`

src_c/_pygame.h

@@ -294,6 +294,17 @@ supported Python version. #endif */
 
 #define PyType_Init(x) (((x).ob_type) = &PyType_Type)
 
+/* Python macro for comparing to Py_None
+ * Py_IsNone is naturally supported by
+ * Python 3.10 or higher
+ * so this macro can be removed after the minimum
+ * supported
+ * Python version reaches 3.10
+ */
+#ifndef Py_IsNone
+#define Py_IsNone(x) (x == Py_None)
+#endif
+
 /* Update this function if new sequences are added to the fast sequence
  * type. */
 #ifndef pgSequenceFast_Check

src_c/doc/mixer_doc.h

@@ -12,6 +12,8 @@
 #define DOC_MIXER_GETNUMCHANNELS "get_num_channels() -> count\nget the total number of playback channels"
 #define DOC_MIXER_SETRESERVED "set_reserved(count) -> count\nreserve channels from being automatically used"
 #define DOC_MIXER_FINDCHANNEL "find_channel(force=False) -> Channel\nfind an unused channel"
+#define DOC_MIXER_SETSOUNDFONT "set_soundfont(path) -> None\nset the soundfont for playing midi music"
+#define DOC_MIXER_GETSOUNDFONT "get_soundfont() -> paths\nget the soundfont for playing midi music"
 #define DOC_MIXER_GETBUSY "get_busy() -> bool\ntest if any sound is being mixed"
 #define DOC_MIXER_GETSDLMIXERVERSION "get_sdl_mixer_version() -> (major, minor, patch)\nget_sdl_mixer_version(linked=True) -> (major, minor, patch)\nget the mixer's SDL version"
 #define DOC_MIXER_SOUND "Sound(filename) -> Sound\nSound(file=filename) -> Sound\nSound(file=pathlib_path) -> Sound\nSound(buffer) -> Sound\nSound(buffer=buffer) -> Sound\nSound(object) -> Sound\nSound(file=object) -> Sound\nSound(array=object) -> Sound\nCreate a new Sound object from a file or buffer object"

src_c/mixer.c

@@ -1460,6 +1460,58 @@ mixer_find_channel(PyObject *self, PyObject *args, PyObject *kwargs)
     return pgChannel_New(chan);
 }
 
+static PyObject *
+mixer_set_soundfont(PyObject *self, PyObject *args)
+{
+    int paths_set;
+    PyObject *path = Py_None;
+    const char *string_path = "";
+
+    if (!PyArg_ParseTuple(args, "|O", &path)) {
+        return NULL;
+    }
+
+    MIXER_INIT_CHECK();
+
+    if (PyUnicode_Check(path)) {
+        string_path = PyUnicode_AsUTF8(path);
+    }
+    else if (!Py_IsNone(path)) {
+        PyErr_SetString(PyExc_TypeError,
+                        "Must pass string or None to set_soundfont");
+        return NULL;
+    }
+
+    if (strlen(string_path) == 0) {
+        paths_set = Mix_SetSoundFonts(NULL);
+    }
+    else {
+        paths_set = Mix_SetSoundFonts(string_path);
+    }
+
+    if (paths_set == 0) {
+        return RAISE(pgExc_SDLError, SDL_GetError());
+    }
+
+    Py_RETURN_NONE;
+}
+
+static PyObject *
+mixer_get_soundfont(PyObject *self, PyObject *_null)
+{
+    const char *paths;
+
+    MIXER_INIT_CHECK();
+
+    paths = Mix_GetSoundFonts();
+
+    if (paths) {
+        return PyUnicode_FromString(paths);
+    }
+
+    Py_RETURN_NONE;
+}
+
 static PyObject *
 mixer_fadeout(PyObject *self, PyObject *args)
 {
@@ -1895,6 +1947,10 @@ static PyMethodDef _mixer_methods[] = {
     {"get_busy", (PyCFunction)get_busy, METH_NOARGS, DOC_MIXER_GETBUSY},
     {"find_channel", (PyCFunction)mixer_find_channel,
      METH_VARARGS | METH_KEYWORDS, DOC_MIXER_FINDCHANNEL},
+    {"set_soundfont", (PyCFunction)mixer_set_soundfont, METH_VARARGS,
+     DOC_MIXER_SETSOUNDFONT},
+    {"get_soundfont", (PyCFunction)mixer_get_soundfont, METH_NOARGS,
+     DOC_MIXER_GETSOUNDFONT},
     {"fadeout", mixer_fadeout, METH_VARARGS, DOC_MIXER_FADEOUT},
     {"stop", (PyCFunction)mixer_stop, METH_NOARGS, DOC_MIXER_STOP},
     {"pause", (PyCFunction)mixer_pause, METH_NOARGS, DOC_MIXER_PAUSE},

test/mixer_test.py

@@ -116,6 +116,25 @@ def test_set_num_channels(self):
             mixer.set_num_channels(i)
             self.assertEqual(mixer.get_num_channels(), i)
 
+    def test_set_soundfont(self):
+        """Ensure soundfonts can be set, cleared, and retrieved"""
+        mixer.init()
+
+        mixer.set_soundfont()
+        self.assertEqual(mixer.get_soundfont(), None)
+
+        mixer.set_soundfont(None)
+        self.assertEqual(mixer.get_soundfont(), None)
+
+        mixer.set_soundfont("")
+        self.assertEqual(mixer.get_soundfont(), None)
+
+        mixer.set_soundfont("test1.sf2;test2.sf2")
+        self.assertEqual(mixer.get_soundfont(), "test1.sf2;test2.sf2")
+
+        self.assertRaises(TypeError, mixer.set_soundfont, 0)
+        self.assertRaises(TypeError, mixer.set_soundfont, ["one", "two"])
+
     def test_quit(self):
         """get_num_channels() Should throw pygame.error if uninitialized
         after mixer.quit()"""