docs

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
 

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()`,

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 <CsOptions>
+        If start is called before this method, the ``<CsOptions>``
         element is ignored (but setOption can be called any number of
-        times), the <CsScore> element is not pre-processed, but dispatched as
+        times), the ``<CsScore>`` 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 <CsOptions>
-        element is used, the <CsScore> 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 ``<CsOptions>``
+        element is used, the ``<CsScore>`` 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 ``<CsOptions>``
-        element is ignored (but setOption can be called any number of
-        times), the ``<CsScore>`` 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 ``<CsScore>`` 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 <CsOptions>
-        element is used, the <CsScore> 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 ``<CsOptions>``
+        element is used, the ``<CsScore>`` 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:
         """