diff --git a/docs/porting.rst b/docs/porting.rst index 3d790e6..58074a6 100644 --- a/docs/porting.rst +++ b/docs/porting.rst @@ -10,9 +10,11 @@ Deprecated methods in csound 6 These methods do not exist in csound 7 but code can be written which supports the same functionality +spin / spout +~~~~~~~~~~~~ -setSpinSample and addSpinSample -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**setSpinSample and addSpinSample** .. code-block:: python @@ -26,8 +28,7 @@ setSpinSample and addSpinSample spin[nchnls * frame + channel] = sample -spoutSample -~~~~~~~~~~~ +**spoutSample** .. code-block:: python @@ -39,8 +40,7 @@ spoutSample samp = spout[nchnls * frame + channel] -clearSpin -~~~~~~~~~ +**clearSpin** .. code-block:: python diff --git a/libcsound/api6.py b/libcsound/api6.py index 2630c28..a20f903 100644 --- a/libcsound/api6.py +++ b/libcsound/api6.py @@ -660,11 +660,15 @@ def compileOrc(self, orc: str, block=True) -> int: .. code-block:: python cs = Csound() + cs.setOption(...) cs.compileOrc(r''' instr 1 a1 rand 0dbfs/4 out a1 endin + cs.scoreEvent(...) + cs.perform() + ''') """ @@ -873,12 +877,8 @@ def perform(self) -> int: """ Handles input events and performs audio output. - This is done until the end of score is reached (positive return value), - an error occurs (negative return value), or performance is stopped by - calling :py:meth:`stop()` from another thread (zero return value). - Returns: - 0 if OK, an error code otherwise + 0 if stopped, 1 if end of score is reached, negative on error Note that some form of compilation needs to happen before (:py:meth:`compileCommandLine()`, :py:meth:`compileOrc()`, diff --git a/libcsound/api7.py b/libcsound/api7.py index e9931e4..2529e63 100644 --- a/libcsound/api7.py +++ b/libcsound/api7.py @@ -194,8 +194,8 @@ def _declareAPI(libcsound, libcspt): libcsound.csoundStart.argtypes = [CSOUND_p] libcsound.csoundPerformKsmps.restype = ct.c_int32 libcsound.csoundPerformKsmps.argtypes = [CSOUND_p] - libcsound.csoundPerform.restype = ct.c_int32 - libcsound.csoundPerform.artypes = [CSOUND_p] + # libcsound.csoundPerform.restype = ct.c_int32 + # libcsound.csoundPerform.artypes = [CSOUND_p] libcsound.csoundRunUtility.restype = ct.c_int32 libcsound.csoundRunUtility.argtypes = [CSOUND_p, ct.c_char_p, ct.c_int32, ct.POINTER(ct.c_char_p)] libcsound.csoundReset.argtypes = [CSOUND_p] @@ -805,10 +805,13 @@ def compileCommandLine(self, *args): def compileOrc(self, orc: str, block=True) -> int: """ - Parses and compiles the given orchestra from an ASCII string. + Parses and compiles the given orchestra from a string. Args: orc: the code to compile + block: if True, any global code will be evaluated in synchronous + mode. Otherwise, this methods returns immediately but any + global code passed to csound might not still be available Returns: 0 if OK, an error code otherwise @@ -890,9 +893,9 @@ def compileCsd(self, path: str) -> int: Returns a non-zero error code on failure. - If start is called before this method, the + If start is called before this method, the ```` element is ignored (but setOption can be called any number of - times), the element is not pre-processed, but dispatched as + times), the ```` element **is not pre-processed**, but dispatched as real-time events; and performance continues indefinitely, or until ended by calling stop or some other logic. In this "real-time" mode, the sequence of calls should be: @@ -901,10 +904,11 @@ def compileCsd(self, path: str) -> int: .. code-block:: python + cs = Csound() cs.setOption(...) cs.start() cs.compileCsd(path) - while not cs.performKsmps(): + while cs.performKsmps() == CSOUND_SUCCESS: pass cs.reset() @@ -913,20 +917,19 @@ def compileCsd(self, path: str) -> int: this function can be called repeatedly during performance to replace or add new instruments and events. - But if this method is called before start, the - element is used, the section is pre-processed and dispatched - normally, and performance terminates when the score terminates, or - stop is called. In this "non-real-time" mode (which can still - output real-time audio and handle real-time events), the sequence of - calls should be: + But if this method is called before start, the ```` + element is used, the ```` section **is pre-processed and dispatched + normally**, and performance terminates when the score terminates, or + stop is called. .. rubric:: Example .. code-block:: python + cs = Csound() cs.compileCsd(path) cs.start() - while not cs.performKsmps(): + while cs.performKsmps() == CSOUND_SUCCESS: pass cs.reset() @@ -944,9 +947,9 @@ def compileCsdText(self, code: str) -> int: non-zero error code on failure. If start is called before this method, the ```` - element is ignored (but setOption can be called any number of - times), the ```` element is not pre-processed, but dispatched as - real-time events; and performance continues indefinitely, or until + element **is ignored** (but :py:meth:`setOption()` can be called any number of + times), the ```` element **is not pre-processed**, but *dispatched as + real-time events*; and **performance continues indefinitely**, or until ended by calling stop or some other logic. In this "real-time" mode, the sequence of calls should be: @@ -964,12 +967,10 @@ def compileCsdText(self, code: str) -> int: This function can be called repeatedly during performance to replace or add new instruments and events. - But if this method is called before start, the - element is used, the section is pre-processed and dispatched - normally, and performance terminates when the score terminates, or - stop is called. In this "non-real-time" mode (which can still - output real-time audio and handle real-time events), the sequence of - calls should be: + But if this method is called before start, the ```` + element is used, the ```` section **is pre-processed and dispatched + normally**, and performance terminates when the score terminates, or + stop is called. .. code-block:: python @@ -1036,7 +1037,7 @@ def perform(self) -> int: calling :py:meth:`stop()` from another thread (zero return value). Returns: - 0 if OK, an error code otherwise + 0 if stopped, 1 if end of score is reached, negative on error Note that some form of compilation needs to happen before (:py:meth:`compileCommandLine()`, :py:meth:`compileOrc()`, @@ -1047,10 +1048,21 @@ def perform(self) -> int: In the case of zero return value, :py:meth:`perform()` can be called again to continue the stopped performance. Otherwise, :py:meth:`reset()` should be called to clean up after the finished or failed performance. + + .. note:: + + The underlying function ``csoundPerform`` has been removed from the + API in csound 7. This method is included here for backwards compatibility + with csound 6 and might be removed in the future. + """ if not self._started: self.start() - return libcsound.csoundPerform(self.cs) + while (retcode := self.performKsmps()) == CSOUND_SUCCESS: + pass + if retcode == CSOUND_SUCCESS: + return 1 + return -1 def performKsmps(self) -> bool: """