libcsound 0.9.0__py3-none-any.whl

libcsound/__init__.py

@@ -0,0 +1,112 @@
+#   libcsound
+#
+#   fork of ctcsound.py, made to be pip installable and support any
+#   version of csound 6 and csound 7
+#
+#   Copyright (C) 2024 Eduardo Moguillansky
+#
+#   Original copyright follows:
+#
+#   ctcsound.py:
+#
+#   Copyright (C) 2016 Francois Pinot
+#
+#   This file is part of Csound.
+#
+#   This code is free software; you can redistribute it
+#   and/or modify it under the terms of the GNU Lesser General Public
+#   License as published by the Free Software Foundation; either
+#   version 2.1 of the License, or (at your option) any later version.
+#
+#   Csound is distributed in the hope that it will be useful,
+#   but WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#   GNU Lesser General Public License for more details.
+#
+#   You should have received a copy of the GNU Lesser General Public
+#   License along with Csound; if not, write to the Free Software
+#   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+#   02110-1301 USA
+#
+
+from . import common
+
+if not common.BUILDING_DOCS:
+    from . import _dll
+    libcsound, libcsoundPath = _dll.csoundDLL()
+    VERSION = libcsound.csoundGetVersion()
+    if VERSION >= 7000:
+        APIVERSION = VERSION
+    else:
+        APIVERSION = libcsound.csoundGetAPIVersion()
+
+    if VERSION < 7000:
+        from .api6 import *
+    else:
+        from .api7 import *
+else:
+    print("------------- Building documentation -------------")
+    VERSION = 0
+    from . import api7
+    from . import api6
+
+
+#Instantiation
+def csoundInitialize(signalHandler=True, atExitHandler=True) -> int:
+    """
+    Initializes Csound library with specific flags.
+
+    There is generally no need to use it explicitly unless you need to
+    avoid default initialization that sets signal handlers and atexit()
+    callbacks.
+
+    Within a python context, it is often necessary to call this function
+    with `signalHandler=False` in order for csound not to obstruct
+    python's own SIGINT (Keyboard Interrupt) handler. If called explicitely,
+    it needs to be called prior to any other function within the API.
+
+    Args:
+        signalHandler: if True, add a signal handler
+        atExitHandler: if True, adds a callback to destroy all instances of csound
+            when exiting
+
+    Returns:
+        zero on success, positive if initialization was done already, and negative on error.
+
+    """
+    flags = 0
+    if not signalHandler:
+        flags |= common.CSOUNDINIT_NO_SIGNAL_HANDLER
+    if not atExitHandler:
+        flags |= common.CSOUNDINIT_NO_ATEXIT
+    return libcsound.csoundInitialize(flags)
+
+
+def setOpcodedir(path: str) -> None:
+    """
+    Overrides the folder used to locate plugins
+
+    Args:
+        path: folder where to search for plugins.
+    """
+    libcsound.csoundSetOpcodedir(common.cstring(path))
+
+
+def setDefaultMessageCallback(function):
+    """
+    Not fully implemented but useful for disabling messaging
+
+    Args:
+        function: function of the form ``(csound, attr, flags, *args) -> None``,
+            will be called each time csound would print any message to the
+            console.
+
+    .. code-block:: python
+
+        def noMessage(csound, attr, flags, *args):
+            pass
+
+        ctcsound.setDefaultMessageCallback(noMessage)
+
+    """
+    libcsound.csoundSetDefaultMessageCallback(common.DEFMSGFUNC(function))

libcsound/_dll.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+import ctypes as ct
+import ctypes.util
+import sys
+import os
+from .common import BUILDING_DOCS
+
+
+def csoundLibraryName() -> str:
+    platform = sys.platform
+    if platform.startswith('linux'):
+        return 'csound64'
+    elif platform.startswith('win'):
+        return 'csound64'
+    elif platform.startswith('darwin'):
+        return 'CsoundLib64'
+    else:
+        raise RuntimeError(f"Platform '{platform}' not supported")
+
+
+_libcsound = None
+_libcsoundpath = ''
+
+
+def csoundDLL() -> tuple[ct.CDLL, str]:
+    global _libcsound
+    global _libcsoundpath
+
+    if _libcsound is not None:
+        return _libcsound, _libcsoundpath
+
+    if BUILDING_DOCS:
+        raise RuntimeError("Cannot access the dll while building docs")
+
+    if sys.platform == 'linux':
+        try:
+            dll = ct.CDLL("libcsound64.so")
+            _libcsound = dll
+            _libcsoundpath = "libcsound64.so"
+            return dll, "libcsound64.so"
+        except OSError:
+            libname = ctypes.util.find_library("csound64")
+            if libname is None:
+                raise ImportError("Did not find csound library in linux")
+    else:
+        libname = csoundLibraryName()
+    path = ctypes.util.find_library(libname)
+    if path is None:
+        if sys.platform.startswith('win'):
+            PATH = os.environ.get('PATH')
+            raise ImportError(f"Csound library not found (searched for '{libname}'. "
+                              f"Make sure that csound is installed and the directory containing "
+                              f"csound64.dll is in the path. PATH='{PATH}'")
+        raise ImportError(f"Csound library not found (searched for '{libname}') - Make sure that csound is installed")
+    _libcsound = ct.CDLL(path)
+    _libcsoundpath = path
+
+    return _libcsound, _libcsoundpath

libcsound/_util.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+import warnings
+import signal
+import ctypes
+import numpy as np
+import sys
+
+from .common import (MYFLT,
+                     CSOUND_CONTROL_CHANNEL,
+                     CSOUND_AUDIO_CHANNEL,
+                     CSOUND_ARRAY_CHANNEL,
+                     CSOUND_PVS_CHANNEL,
+                     CSOUND_OUTPUT_CHANNEL,
+                     CSOUND_INPUT_CHANNEL,
+                     CSOUND_CHANNEL_TYPE_MASK,
+                     CSOUND_STRING_CHANNEL)
+
+
+def asciistr(s) -> str:
+    if isinstance(s, str):
+        return s
+    elif isinstance(s, bytes):
+        return s.decode('ascii')
+    else:
+        raise TypeError(f"Expected a bytes or str instance, got {s}")
+
+
+def packChannelType(kind: str, output: bool, input: bool) -> int:
+    chantype = {'control': CSOUND_CONTROL_CHANNEL,
+                'audio': CSOUND_AUDIO_CHANNEL,
+                'str': CSOUND_STRING_CHANNEL,
+                'string': CSOUND_STRING_CHANNEL,
+                'array': CSOUND_ARRAY_CHANNEL,
+                'pvs': CSOUND_PVS_CHANNEL}[kind]
+    chanmode = CSOUND_OUTPUT_CHANNEL * int(output) + CSOUND_INPUT_CHANNEL * int(input)
+    return chantype + chanmode
+
+
+def unpackChannelType(chantype: int) -> tuple[str, int]:
+    """
+    Returns:
+        a tuple (type: str, mode: int)
+        Where type is one of 'control', 'audio', 'string', 'array' or 'pvs', mode
+        is CSOUND_OUTPUT_CHANNEL, CSOUND_INPUT_CHANNEL or
+        CSOUND_OUTPUT_CHANNEL + CSOUND_INPUT_CHANNEL
+    """
+    typecode = chantype & CSOUND_CHANNEL_TYPE_MASK
+    typename = {
+        CSOUND_CONTROL_CHANNEL: 'control',
+        CSOUND_AUDIO_CHANNEL: 'audio',
+        CSOUND_STRING_CHANNEL: 'string',
+        CSOUND_ARRAY_CHANNEL: 'array',
+        CSOUND_PVS_CHANNEL: 'pvs'
+    }.get(typecode)
+    if typename is None:
+        raise ValueError(f"Invalid channel type: {chantype}")
+    modecode = chantype - typecode
+    return typename, modecode
+
+
+_sigintHandler = None
+
+
+def setupSigint(handler=lambda: sys.exit(0)):
+    """
+    Set a SIGINT handler
+
+    This can be used in context with csound to avoid the situation where
+    ctrl-c is hit during a performance and is handled by csound, making
+    it exit without notifying the underlying python process. This results
+    often in an unrecoverable situation
+
+    Args:
+        handler: a function taking to args and returning nothing. It will be called
+            whenever SIGINT (ctrl-c) is signaled
+
+    .. note:: to restore the previous sigint handler, call :func:`restoreSigint`
+    """
+    global _sigintHandler
+    _sigintHandler = signal.getsignal(signal.SIGINT)
+    def _handler(signal, frame):
+        handler()
+    signal.signal(signal.SIGINT, _handler)
+
+
+def restoreSigint() -> None:
+    """
+    Restores the SIGINT handler previously replaced via :func:`setupSigint`
+    """
+    global _sigintHandler
+    if _sigintHandler is not None:
+        signal.signal(signal.SIGINT, _sigintHandler)
+
+
+def defaultRealtimeModule() -> str:
+    """
+    Determines the default realtime module for the current architecture
+    """
+    if sys.platform == 'linux':
+        return 'jack'
+    elif sys.platform == 'darwin':
+        return 'auhal'
+    return 'pa_cb'
+
+
+def realtimeModulesForPlatform(platform='') -> set[str]:
+    if not platform:
+        platform = sys.platform
+    if platform == 'linux':
+        return {'portaudio', 'jack', 'pulse', 'alsa'}
+    elif platform == 'darwin':
+        return {'portaudio', 'auhal', 'jack'}
+    elif platform == 'windows':
+        return {'portaudio', 'winmme'}
+    else:
+        return {}
+
+
+def testCsound(module: str = '',
+               sr: float = 0.,
+               outdev='',
+               nchnls=2,
+               dur=10.,
+               signal='pinker() * 0.2'
+               ) -> None:
+    """
+    Test csound
+
+    Args:
+        module: the realtime audio module ('jack', 'auhal', 'portaudio', etc.). A default
+            is used if not given
+        sr: the samplerate to use. Leave unset to use the system sr or the default sr according
+            to the module used
+        outdev: the output device (unset to use default)
+        nchnls: number of output channels
+        signal: which signal to use. Any valid sound-generating csound code
+    """
+    if not module:
+        module = defaultRealtimeModule()
+    from . import Csound
+    csound = Csound()
+    if outdev:
+        csound.setOption(f'-o{outdev}')
+    elif module == 'jack':
+        csound.setOption('-odac:_')
+    else:
+        csound.setOption('-odac')
+
+    csound.setOption(f'-+rtaudio={module}')
+    if sr <= 0:
+        csound.setOption('--use-system-sr')
+    else:
+        csound.setOption(f'--sample-rate={sr}')
+    csound.compileOrc(fr"""
+    0dbfs = 1
+    ksmps = 64
+    nchnls = {nchnls}
+
+    instr 1
+      kchan init -1
+      kchan = (kchan + metro:k(1)) % nchnls
+      if changed:k(kchan) == 1 then
+        println "Channel: %d", kchan + 1
+      endif
+      asig = {signal}
+      outch kchan + 1, asig
+    endin
+    """)
+    csound.start()
+    pt = csound.performanceThread()
+    pt.play()
+    pt.scoreEvent(0, "i", [1, 0, dur])
+    setupSigint(lambda: (pt.stop()))
+    input(">>> Press any key to stop <<< \n")
+    restoreSigint()
+    pt.stop()
+    csound.stop()
+
+
+def castarray(ptr: ctypes._Pointer | ctypes.c_void_p, shape: tuple[int, ...]) -> np.ndarray:
+    """
+    Cast a ctypes pointer to an array
+    """
+    arrtype = np.ctypeslib.ndpointer(dtype=MYFLT, ndim=len(shape), shape=shape, flags='C_CONTIGUOUS')
+    return ctypes.cast(ptr, arrtype).contents
+
+
+def deprecated(func):
+    """
+    Decorator used to mark functions as deprecated
+
+    It will result in a warning being emitted
+    when the function is used."""
+    import functools
+    @functools.wraps(func)
+    def newfunc(*args, **kwargs):
+        warnings.simplefilter('always', DeprecationWarning)  # turn off filter
+        warnings.warn("Call to deprecated function {}.".format(func.__name__),
+                      category=DeprecationWarning,
+                      stacklevel=2)
+        warnings.simplefilter('default', DeprecationWarning)  # reset filter
+        return func(*args, **kwargs)
+    return newfunc
+
+
+def splitCommandLine(args: str) -> list[str]:
+    import re
+    return re.findall(r"(?:\".*?\"|\S)+", args)
+
+
+def waveplot(samples: np.ndarray, samplerate: int):
+    def sec2str(seconds):
+        s = seconds % 60
+        sfrac = str(round((s - int(s)), 3)).split(".")[1]
+        return f"{int(seconds//60)}:{int(s):>02}.{sfrac}"
+    import matplotlib.pyplot as plt
+    import matplotlib.ticker
+    numch = 1 if len(samples.shape) == 1 else samples.shape[1]
+    fig = plt.figure(figsize=(24, 4))
+    formatter = matplotlib.ticker.FuncFormatter(lambda idx, x:sec2str(idx/samplerate))
+    axes = ax1 = fig.add_subplot(numch, 1, 1)
+    for i in range(numch):
+        if i > 0:
+            axes = fig.add_subplot(numch, 1, i + 1, sharex=ax1, sharey=ax1)
+        if i < numch - 1:
+            plt.setp(axes.get_xticklabels(), visible=False)
+        chan = samples[:, i] if len(samples.shape) > 1 else samples
+        axes.plot(chan, linewidth=1)
+        axes.xaxis.set_major_formatter(formatter)
+    ax1.set_xlim(0, samples.shape[0])
+    fig.tight_layout()
+    return fig