Supriya

https://github.com/supriya-project/supriya
Admin
Supriya is a Python API for SuperCollider, enabling programmatic control over its synthesis engine...
Tokens:90,920
Snippets:831
Trust Score:5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run the hello_world_contexts example

Source: https://github.com/supriya-project/supriya/blob/main/examples/hello_world_contexts/README.md

Invoke the example module from the command line to see complete options.

```bash
supriya$ python -m examples.hello_world_contexts
```

--------------------------------

### Install supriya from PyPI with examples extra

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install-examples.txt

Installs the supriya package from PyPI with the examples extra, which includes example files.

```console
josephine@laptop:~$ pip install supriya[examples]
```

--------------------------------

### Install supriya from source with examples extra

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install-examples.txt

Clones the supriya repository from GitHub, changes into the cloned directory, and installs the package in editable mode with the examples extra.

```console
josephine@laptop:~$ git clone https://github.com/supriya-project/supriya.git
josephine@laptop:~$ cd supriya
josephine@laptop:~/supriya$ pip install -e .[examples]
```

--------------------------------

### Run hello_world_debugged example

Source: https://github.com/supriya-project/supriya/blob/main/examples/hello_world_debugged/README.md

Run the hello_world_debugged example from the Supriya project root. This command executes the example module that plays a C-major chord while printing logs and debugging information about the server, scsynth process, and OSC messages.

```bash
supriya$ python -m examples.hello_world_debugged
```

--------------------------------

### Run hello_world example

Source: https://github.com/supriya-project/supriya/blob/main/examples/hello_world/README.md

Run the hello_world example from the command line. The prompt 'supriya$' indicates the shell prompt; execute the command from the project root.

```bash
supriya$ python -m examples.hello_world
```

--------------------------------

### Invoke keyboard_input example with help

Source: https://github.com/supriya-project/supriya/blob/main/examples/keyboard_input/README.md

Run this command to see the complete options for the keyboard_input example. The command uses the module path examples.keyboard_input and the --help flag.

```shell
supriya$ python -m examples.keyboard_input --help
```

--------------------------------

### Invoke the hello_world example with python -m examples.hello_world

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/hello_world.rst

Run the example script from the command line. The script plays a C-major chord for a few seconds, then fades out quickly before exiting.

```shell
python -m examples.hello_world
```

--------------------------------

### Install supriya from source

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install.txt

Clones the supriya repository from GitHub and installs it in editable mode for development.

```console
josephine@laptop:~$ git clone https://github.com/supriya-project/supriya.git
josephine@laptop:~$ cd supriya
josephine@laptop:~/supriya$ pip install -e .
```

--------------------------------

### Boot a server

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/buses.rst

Buses can only be added to running servers, so boot a server first. This example creates a Server instance and boots it.

```python
>>> server = supriya.Server().boot()
```

--------------------------------

### Get buffer samples with .get()

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/buffers.rst

Retrieves samples from the buffer. The example gets samples at indices 0, 2, and 4.

```python
>>> buffer_.get(0, 2, 4)
```

--------------------------------

### Install FFmpeg and LAME on Ubuntu via apt

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/introduction/installation.rst

Command to install FFmpeg and LAME on Ubuntu using apt. Requires sudo privileges.

```console
josephine@laptop:~$ sudo apt-get install ffmpeg lame
```

--------------------------------

### Example module with main() function

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/documenting.rst

A Python code block showing the required structure for example modules: a 'main()' function and an 'if __name__ == "__main__":' block that calls it. This is the recommended pattern for all examples.

```python
def main() -> None:
    print("this is an *example* example.")

if __name__ == "__main__":
    main()
```

--------------------------------

### Install from source with git clone and pip

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install-docs.txt

Clones the Supriya repository from GitHub, changes into the directory, and installs the package in editable mode with documentation dependencies.

```console
josephine@laptop:~$ git clone https://github.com/supriya-project/supriya.git
josephine@laptop:~$ cd supriya
josephine@laptop:~/supriya$ pip install -e .[docs]
```

--------------------------------

### Install Supriya from source with test dependencies

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install-test.txt

Clone the Supriya repository from GitHub, change into the directory, and install in editable mode with test dependencies.

```console
josephine@laptop:~$ git clone https://github.com/supriya-project/supriya.git
josephine@laptop:~$ cd supriya
josephine@laptop:~/supriya$ pip install -e .[test]
```

--------------------------------

### Install from PyPI with pip

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install-docs.txt

Installs the latest release of Supriya from PyPI, including the documentation dependencies.

```console
josephine@laptop:~$ pip install supriya[docs]
```

--------------------------------

### Install Graphviz on Ubuntu via apt

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/introduction/installation.rst

Command to install Graphviz on Ubuntu using apt. Requires sudo privileges.

```console
josephine@laptop:~$ sudo apt-get install graphviz
```

--------------------------------

### Reset server for deletion example

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/nodes.rst

Resets the server for a clean slate before adding a synth.

```python
>>> server.reset()
```

--------------------------------

### Start a threaded clock with clock.start()

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/clocks.rst

Start a threaded clock. Call this after creating the clock to begin processing scheduled callbacks.

```python
>>> clock.start()
```

--------------------------------

### Install Supriya with SHM from Source

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install-shm.txt

Clones the Supriya repository from GitHub, changes into the 'supriya' directory, and installs the package in editable mode with the SHM extra.

```console
josephine@laptop:~$ git clone https://github.com/supriya-project/supriya.git
josephine@laptop:~$ cd supriya
josephine@laptop:~/supriya$ pip install -e .[shm]

```

--------------------------------

### Install supriya from PyPI

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install.txt

Installs the latest release of supriya from the Python Package Index using pip.

```console
josephine@laptop$ pip install supriya
```

--------------------------------

### play_synths function from hello_world_contexts/__init__.py

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/hello_world_contexts.rst

Extracts the logic for starting the chord into a function that takes a context as an argument and returns a list of synths. It does not use Context.at to specify when the chord plays, as timestamp semantics differ between realtime and non-realtime contexts.

```python
..  literalinclude:: ../../../examples/hello_world_contexts/__init__.py
    :pyobject: play_synths
```

--------------------------------

### Allocate nodes, buffers, and buses with Server methods

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Allocate nodes (groups and synths), buffers, and buses on the server. The example shows adding a group, a synth, a buffer, a buffer group, a bus, and a bus group, then printing the node tree.

```python
>>> server.add_group()
>>> server.add_synth(supriya.default, amplitude=0.25, frequency=441.3)
>>> server.add_buffer(channel_count=1, frame_count=512)
>>> server.add_buffer_group(count=8, channel_count=2, frame_count=1024)
>>> server.add_bus()
>>> server.add_bus_group(count=2, calculation_rate="audio")
>>> print(server.query_tree())
```

--------------------------------

### Shell console session example

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/documenting.rst

A shell console session example that echoes a string. It demonstrates how to capture shell sessions in the documentation, with options for working directory, relative path, user, and host.

```shell
echo "hello, world!"
```

--------------------------------

### Coverage report output example

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/testing.rst

Example terminal output showing the coverage report that appears at the end of the test run.

```console
Name                                Stmts   Miss Branch BrPart  Cover
---------------------------------------------------------------------
supriya/__init__.py                    21      4      2      1    78%
supriya/_version.py                     2      0      0      0   100%
supriya/clocks/__init__.py              5      0      0      0   100%
supriya/clocks/asynchronous.py        115      6     40      5    93%
supriya/clocks/core.py                431     33    118     18    90%
supriya/clocks/offline.py              97     12     14      4    86%
supriya/clocks/threaded.py             72      3     22      4    93%
supriya/contexts/__init__.py            5      0      0      0   100%
supriya/contexts/allocators.py        154     10     42      8    91%
supriya/contexts/core.py              532     32    186     22    91%
supriya/contexts/entities.py          285     41     72     26    78%
supriya/contexts/nonrealtime.py       113      8     36      5    91%
supriya/contexts/realtime.py          791     28    262     25    95%
supriya/contexts/requests.py          718     29    142     14    95%
supriya/contexts/responses.py         356     12     64      5    96%
supriya/contexts/scopes.py             94     16     30     15    75%
supriya/conversions.py                 20      5      0      0    75%
supriya/enums.py                      381      8     24      3    97%
supriya/exceptions.py                  36      0      0      0   100%
supriya/ext/__init__.py                19      6     10      3    62%
supriya/ext/book.py                    99      2      2      0    98%
supriya/ext/ipython.py                 23     16      4      0    26%
supriya/ext/mypy.py                    63     49     18      0    17%
supriya/io.py                          78     25      8      2    64%
supriya/osc/__init__.py                 5      0      0      0   100%
supriya/osc/asynchronous.py            89      8     30      8    85%
supriya/osc/messages.py               279     35    116     16    85%
supriya/osc/protocols.py              209     15     68     13    90%
supriya/osc/threaded.py               115     10     36      7    89%
supriya/osc/utils.py                   26      5     12      1    84%
supriya/patterns/__init__.py            7      0      0      0   100%
supriya/patterns/eventpatterns.py     131     14     42      3    89%
supriya/patterns/events.py            168     15     52     12    85%
supriya/patterns/noise.py             114      7     38      8    90%
supriya/patterns/patterns.py          252      6     54      2    97%
```

--------------------------------

### pytest tests/test_examples.py::test_async

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/testing.rst

Command to run the async test example.

```shell
pytest tests/test_examples.py::test_async
```

--------------------------------

### Test Graphviz installation with dot -V

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/introduction/installation.rst

Command to verify Graphviz is installed and accessible from the command line. The expected output shows the version of Graphviz.

```console
josephine@laptop:~$ dot -V
dot - graphviz version 13.1.0 (20250701.0955)
```

--------------------------------

### Boot the server

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Boots the server and returns the server object, making the call chainable. This is the first step to start the SuperCollider server.

```python
server.boot()
```

--------------------------------

### Build documentation with make docs

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/documenting.rst

Use `make docs` to build Supriya's Sphinx documentation. This command requires the documentation dependencies to be installed.

```console
josephine@laptop:~/supriya$ make docs

```

--------------------------------

### Install Supriya from PyPI with test dependencies

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install-test.txt

Use pip to install the latest release of Supriya from PyPI, including the optional test dependencies.

```console
josephine@laptop:~$ pip install supriya[test]
```

--------------------------------

### Install Graphviz on Windows via Chocolatey

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/introduction/installation.rst

Command to install Graphviz on Windows using Chocolatey package manager.

```console
josephine@laptop:~$ choco install graphviz
```

--------------------------------

### Book block example

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/documenting.rst

A `.. book::` block without arguments behaves like Sphinx's `.. code-block::`. This example prints a message to the console. The `>>>` prompt indicates interpreter input.

```rst-example
..  book::

    >>> print("this is basically the same as a ``.. code-block::``")

```

--------------------------------

### Install FFmpeg and LAME on Windows via Chocolatey

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/introduction/installation.rst

Command to install FFmpeg and LAME on Windows using Chocolatey package manager.

```console
josephine@laptop:~$ choco install ffmpeg lame
```

--------------------------------

### Schedule and start a Clock callback

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Defines a clock callback that prints the context and returns a delta of 0.25 (quarter note) until the 5th invocation, then returns None to stop rescheduling. Schedules it immediately with clock.schedule() and starts the clock with clock.start().

```python
# define a simple callback
# this will print the "clock context"
# and return a delta of 1/4 (a quarter note)
# and on the 5th invocation will return a null delta, preventing re-scheduling
def clock_callback(context):
    print(context)
    if context.event.invocations == 4:
        return None
    return 0.25
```

```python
# schedule the callback to be run immediately
clock.schedule(clock_callback)
```

```text
Result:
0
```

```python
# start the clock
clock.start()
```

--------------------------------

### Locate a soundfile

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/buffers.rst

Gets the path to a sample soundfile for buffer creation.

```python
>>> file_path = supriya.samples_path / "birds-01.wav"
```

--------------------------------

### Import Supriya and boot the server

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/index.rst

Start a Python interpreter, import Supriya, and boot the SuperCollider server. The server object is used in subsequent steps.

```python
>>> import supriya

```

```python
>>> server = supriya.Server().boot()

```

--------------------------------

### Install Supriya with SHM from PyPI

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/includes/install-shm.txt

Installs Supriya and its SHM dependency from the Python Package Index using pip. The command includes the extra '[shm]'.

```console
josephine@laptop:~$ pip install supriya[shm]

```

--------------------------------

### Install FFmpeg and LAME on OSX via Homebrew

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/introduction/installation.rst

Command to install FFmpeg and LAME on macOS using Homebrew. These are needed for transcoding audio to websafe formats for IPython and Sphinx integrations.

```console
josephine@laptop:~$ brew install ffmpeg lame
```

--------------------------------

### run() function from keyboard_input_async

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/keyboard_input_async.rst

The async run() function that boots the server, creates an asyncio.Queue, starts a queue_consumer task, and runs input handlers. It uses call_soon_threadsafe to safely enqueue events from background threads and cancels the consumer task after the exit future resolves.

```python
..  literalinclude:: ../../../examples/keyboard_input_async/__init__.py
    :pyobject: run
```

--------------------------------

### Install Graphviz on OSX via Homebrew

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/introduction/installation.rst

Command to install Graphviz on macOS using Homebrew. Graphviz is used for creating graphs of rhythm-trees and visualizations of class hierarchies.

```console
josephine@laptop:~$ brew install graphviz
```

--------------------------------

### Hide code with book directive

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/documenting.rst

Use the `:hide:` option on a `.. book::` block to execute code without showing its textual input or output in the built docs. This example initializes a server while hiding the execution.

```rst-example
..  book::
    :hide:

    >>> hidden_server = supriya.Server()  # executed, but hidden from Sphinx output

```

--------------------------------

### Visualize SynthDef with Graphviz

Source: https://github.com/supriya-project/supriya/blob/main/README.md

Generate a graph visualization of the SynthDef using Graphviz (requires Graphviz installed).

```python
>>> supriya.graph(simple_sine)
```

--------------------------------

### Get buffer range

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Retrieves a range of sample values from a buffer, starting at index 0 and returning 16 values.

```python
# get a range of values
buffer.get_range(index=0, count=16)
```

--------------------------------

### Supriya node tree output

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Example node tree output from query_tree(), showing groups, synthdefs (default, delay, reverb), and system_link_audio_2 nodes with parameters.

```text
Output:
NODE TREE 0 group
    1 group
        1000 group
            1003 group
                1017 group
                    1021 default
                        amplitude: 0.1, frequency: 440.0, gate: 0.0, pan: -0.401104, out: 24.0
                    1019 delay
                        gate: 1.0, out: 24.0
                1018 system_link_audio_2
                    done_action: 2.0, fade_time: 0.25, gate: 1.0, in_: 24.0, out: 16.0
                1013 group
                    1015 delay
                        gate: 1.0, out: 22.0
                1014 system_link_audio_2
                    done_action: 2.0, fade_time: 0.25, gate: 1.0, in_: 22.0, out: 16.0
                1009 group
                    1011 delay
                        gate: 1.0, out: 20.0
                1010 system_link_audio_2
                    done_action: 2.0, fade_time: 0.25, gate: 1.0, in_: 20.0, out: 16.0
                1004 group
                    1006 delay
                        gate: 1.0, out: 18.0
                1005 system_link_audio_2
                    done_action: 2.0, fade_time: 0.25, gate: 1.0, in_: 18.0, out: 16.0
            1002 reverb
                gate: 1.0, out: 16.0
        1001 system_link_audio_2
            done_action: 2.0, fade_time: 0.25, gate: 1.0, in_: 16.0, out: 0.0
```

--------------------------------

### Create a single-channel buffer for filling

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/buffers.rst

Creates a single-channel buffer with 128 frames, used as a prerequisite for the filling examples that follow.

```python
>>> buffer_ = server.add_buffer(channel_count=1, frame_count=128)
```

--------------------------------

### Boot Server

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Boots a new server instance.

```python
server = Server().boot()

```

--------------------------------

### Boot a Server

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Brings an offline server online, using default scsynth settings unless overwritten.

```python
>>> server.boot()
```

--------------------------------

### Boot server and turn soundcheck on

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Boots a Supriya server and turns soundcheck on by adding a default synthdef and synth. Uses the server context manager and add_synthdefs.

```python
# turn soundcheck on
import supriya

server = supriya.Server().boot()
with server.at(), server.add_synthdefs(supriya.default):
    server.add_synth(supriya.default)
```

--------------------------------

### Main function: parse args, select handler, run (main function)

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/keyboard_input.rst

Parses the arguments, checks which flag was set, creates the appropriate InputHandler (MidiHandler or QwertyHandler), and calls the run function with it. This is the entry point for the script.

```python
..  literalinclude:: ../../../examples/keyboard_input/__init__.py
    :pyobject: main
```

--------------------------------

### Generate wavetable waveforms with as_wavetable=True

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/buffers.rst

Generates wavetable-format waveforms using the generate method with as_wavetable=True. The examples use cheby, sine1, sine2, and sine3 commands, each followed by a plot. These calls are compared against non-wavetable versions demonstrated earlier.

```python
>>> buffer_ = server.add_buffer(channel_count=1, frame_count=128)
```

```python
>>> buffer_.generate(
...     command_name="cheby",
...     amplitudes=[1.0, 0.5, 0.25],
...     as_wavetable=True,
... )
>>> supriya.plot(buffer_)
```

```python
>>> buffer_.generate(
...     command_name="sine1",
...     amplitudes=[1.0, 0.5, 0.25],
...     as_wavetable=True,
... )
>>> supriya.plot(buffer_)
```

```python
>>> buffer_.generate(
...     command_name="sine2",
...     amplitudes=[1.0, 0.5, 0.25],
...     frequencies=[1, 3, 5],
...     as_wavetable=True,
... )
>>> supriya.plot(buffer_)
```

```python
>>> buffer_.generate(
...     command_name="sine3",
...     amplitudes=[1.0, 0.5, 0.25],
...     frequencies=[1, 3, 5],
...     phases=[0.0, 0.333, 0.666],
...     as_wavetable=True,
... )
>>> supriya.plot(buffer_)
```

--------------------------------

### Instantiate a Server object

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Creates a new Server instance. The server is not booted yet; booting is a separate step.

```python
# instantiate the server
server = Server()
```

--------------------------------

### Add linear and logarithmic frequency scopes

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/scopes/scopes.ipynb

Creates two frequency scopes on the audio output bus, one linear and one logarithmic, and gets the target sample rate.

```python
lin_scope = server.add_frequency_scope(bus=server.audio_output_bus_group)
log_scope = server.add_frequency_scope(
    bus=server.audio_output_bus_group, frequency_mode="logarithmic"
)
sr = server.status.target_sample_rate
```

--------------------------------

### play_synths function

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/hello_world_debugged.rst

Defines the play_synths function that schedules synth playback using the context's at method. It is part of the performance logic and is nearly identical to the hello_world_contexts example.

```python
..  literalinclude:: ../../../examples/hello_world_debugged/__init__.py
    :pyobject: play_synths
```

--------------------------------

### Boot with Custom Bus Channel Counts

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Passes named Options as keyword arguments when booting.

```python
>>> server.boot(input_bus_channel_count=2, output_bus_channel_count=2)
```

--------------------------------

### Boot server and add synth

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/scopes/scopes.ipynb

Boots the Supriya server, adds the synthdef, and creates a synth instance.

```python
from supriya import Server, SynthDefBuilder

server = Server().boot()
with server.at(), server.add_synthdefs(synthdef):
    synth = server.add_synth(synthdef=synthdef)

server.sync()
```

--------------------------------

### Instantiate a Server

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Creates a realtime Server instance which initially is offline.

```python
>>> server = supriya.Server()
```

--------------------------------

### Invoke keyboard_input_async with --help

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/keyboard_input_async.rst

Command to run the script and display its help options.

```shell
python -m examples.keyboard_input_async --help
```

--------------------------------

### Boot AsyncServer with Free Port

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Boots the async server on a random free port. The boot method returns a coroutine that must be awaited.

```python
# start to boot the server, using a random free port
from supriya import find_free_port

# the result of this is actually a coroutine: nothing has really run yet
(coro := async_server.boot(port=find_free_port()))  # noqa: PLW0131
```

--------------------------------

### Use a completion context with a server

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/contexts.rst

Shows how to use a completion context with a server. Inside a moment, a synthdef is added and a synth is allocated using that synthdef, with the synth allocation bundled as a completion message.

```python
>>> with server.at():
...     with server.add_synthdefs(supriya.default):
...         server.add_synth(supriya.default, target_node=server_group)
...
```

--------------------------------

### Inspect server options

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Prints the server's Options object, showing all configuration defaults such as port, protocol, and buffer counts.

```python
# recall all the options from before
server.options
```

```text
Result:
Options(audio_bus_channel_count=1024, block_size=64, buffer_count=1024, control_bus_channel_count=16384, executable=None, hardware_buffer_size=None, initial_node_id=1000, input_bus_channel_count=8, input_device=None, input_stream_mask='', ip_address='127.0.0.1', load_synthdefs=True, maximum_logins=1, maximum_node_count=1024, maximum_synthdef_count=1024, memory_locking=False, memory_size=8192, output_bus_channel_count=8, output_device=None, output_stream_mask='', password=None, port=57110, protocol='udp', random_number_generator_count=64, realtime=True, restricted_path=None, safety_clip=None, sample_rate=None, threads=6, ugen_plugins_path=None, verbosity=0, wire_buffer_count=64, zero_configuration=False)
```

--------------------------------

### Create group with synths and inspect node IDs

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/nodes.rst

Resets the server, creates a group with three synths, syncs, and inspects node IDs and contexts.

```python
>>> server.reset()
```

```python
>>> with server.at():
...     group = server.add_group()
...     with server.add_synthdefs(supriya.default):
...         synth_a = group.add_synth(supriya.default, frequency=333)
...         synth_b = group.add_synth(supriya.default, frequency=444)
...         synth_c = group.add_synth(supriya.default, frequency=555)
...
```

```python
>>> server.sync()  # wait for synthdefs to load
```

```python
>>> group.id_, group.context
>>> synth_a.id_, synth_a.context
>>> synth_b.id_, synth_b.context
>>> synth_c.id_, synth_c.context
```

--------------------------------

### Boot with Supernova Executable

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Uses the executable keyword to boot with supernova, if available.

```python
>>> server.boot(executable="supernova")
```

--------------------------------

### Boot Server with Maximum Logins

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Boots a server with maximum_logins set to allow multiple clients.

```python
>>> server_one = supriya.Server().boot(maximum_logins=2)
```

--------------------------------

### Iterate Over Options to Generate Command

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Iterating an Options instance yields command-line arguments for launching the server.

```python
>>> for x in supriya.Options():
...     x
...
```

--------------------------------

### Instantiate scsynth Options

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Creates an Options instance modeling scsynth command-line arguments.

```python
>>> supriya.Options()
```

--------------------------------

### Await Boot Coroutine

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Awaits the boot coroutine to actually boot the server.

```python
# once we await the coroutine, we're golden
await coro
```

--------------------------------

### Connect second server proxy with .connect()

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Connects the second server proxy to the original server. The repr shows it becomes ONLINE.

```python
# connect to the original server via .connect()
other_server.connect()
```

```text
Result:
<Server ONLINE [/Applications/SuperCollider.app/Contents/Resources/scsynth -R 0 -l 1 -u 57110]>
```

--------------------------------

### Get synthdef ugens

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Accesses the ugens attribute of the simple_synthdef.

```python
simple_synthdef.ugens
```

--------------------------------

### Get synthdef parameters

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Accesses the parameters attribute of the simple_synthdef.

```python
simple_synthdef.parameters
```

--------------------------------

### Get synthdef name

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Accesses the name attribute of the simple_synthdef.

```python
simple_synthdef.name
```

--------------------------------

### Server boot result

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/scopes/scopes.ipynb

Shows the server status after booting, including the scsynth command and port.

```text
Result:
<Server ONLINE [/Applications/SuperCollider.app/Contents/Resources/scsynth -R 0 -l 1 -u 57110]>
```

--------------------------------

### Get synthdef effective name

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Accesses the effective_name attribute of the simple_synthdef.

```python
simple_synthdef.effective_name
```

--------------------------------

### Generate a sine buffer on a server and play/plot it

Source: https://github.com/supriya-project/supriya/blob/main/tests/book/roots/test-book/index.rst

Boots a server, adds a mono buffer of 512 frames, generates a sine1 waveform, syncs, then plays and plots the buffer. Buffer operations happen within the server.at() context.

```python
>>> server = supriya.Server().boot()
>>> with server.at():
...     buffer_ = server.add_buffer(channel_count=1, frame_count=512)
...     with buffer_:
...         buffer_.generate("sine1", amplitudes=[1.0])
...
>>> server.sync()
>>> supriya.play(buffer_)
>>> supriya.plot(buffer_)
```

--------------------------------

### Create realtime and non-realtime contexts

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/contexts.rst

Shows how to create a realtime server context and a non-realtime score context. The realtime server is booted, while the score is instantiated without booting.

```python
>>> server = supriya.Server().boot()  # realtime
>>> score = supriya.Score()  # non-realtime
```

--------------------------------

### Get synthdef anonymous name

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Accesses the anonymous_name attribute of the simple_synthdef.

```python
simple_synthdef.anonymous_name
```

--------------------------------

### Get buffer values

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Retrieves values from the buffer at the specified indices.

```python
# get values at indices in the buffer
buffer.get(0, 2, 4, 8)
```

--------------------------------

### Get synth parent

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/nodes.rst

Shows that the synth knows its parent group.

```python
>>> synth_a.parent
```

--------------------------------

### Create and allocate nodes

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/index.rst

Create a group, add three synthesizers with different frequencies, and query the server's node tree.

```python
>>> group = server.add_group()

```

```python
>>> for i in range(3):
...     _ = group.add_synth(simple_sine, frequency=111 * (i + 1))
...

```

```python
>>> print(server.query_tree())

```

--------------------------------

### Locate an octophonic soundfile

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/buffers.rst

Gets the path to an octophonic sample soundfile.

```python
>>> file_path = supriya.samples_path / "sine_440hz_44100sr_16bit_octo.wav"
```

--------------------------------

### Connect to Existing Server

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Creates a second client connection using the first server's options.

```python
>>> server_two = supriya.Server().connect(
...     ip_address=server_one.options.ip_address,
...     port=server_one.options.port,
... )
```

--------------------------------

### Stop Supriya pattern player

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Stops the pattern player that was started earlier.

```python
pattern_player.stop()
```

--------------------------------

### Boot Supriya server with lifecycle callback to add synthdefs

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Boots a Supriya Server and registers a lifecycle callback to add synthdefs (supriya.default, delay, reverb) and sync after boot. Creates a Clock for scheduling.

```python
def on_boot(event):
    server.add_synthdefs(supriya.default, delay, reverb)
    server.sync()


server = Server()
server.register_lifecycle_callback("booted", on_boot)
server.boot()
clock = Clock()
```

--------------------------------

### Stop the clock

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Stops the clock that was previously started. This is a simple method call with no arguments.

```python
clock.stop()
```

--------------------------------

### Build and play a score with synthdefs and synths

Source: https://github.com/supriya-project/supriya/blob/main/tests/book/roots/test-book/index.rst

Creates a Score, adds a synthdef, adds a synth at time 0, does nothing at time 10, then plays it. Demonstrates the score.at() and add_synthdefs() API.

```python
>>> score = supriya.Score()
>>> with score.at(0):
...     with score.add_synthdefs(supriya.default):
...         synth = score.add_synth(supriya.default)
...
>>> with score.at(10):
...     score.do_nothing()
...
>>> supriya.play(score)
```

--------------------------------

### Boot on a Free Port

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Uses supriya.osc.find_free_port() to obtain an unused port and successfully boot.

```python
>>> server_two.boot(port=supriya.osc.find_free_port())
```

--------------------------------

### run_threaded: Perform with a threaded server

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/hello_world_contexts.rst

Performs with a threaded server, similar to the hello_world example. Uses time.sleep() for timing.

```python
def run_threaded():
    ...

```

--------------------------------

### Creating Two Servers

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Creates two separate server instances to demonstrate port conflicts.

```python
>>> server_one = supriya.Server()
>>> server_two = supriya.Server()
```

--------------------------------

### Cancel a scheduled callback with clock.cancel()

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/clocks.rst

Cancel a scheduled callback using its event ID. The example cancels event ID 0.

```python
>>> clock.cancel(0)
```

--------------------------------

### stop_synths function

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/hello_world_debugged.rst

Defines the stop_synths function that stops the scheduled synths. It is part of the performance logic and is nearly identical to the hello_world_contexts example.

```python
..  literalinclude:: ../../../examples/hello_world_debugged/__init__.py
    :pyobject: stop_synths
```

--------------------------------

### Create a group and synthesizers

Source: https://github.com/supriya-project/supriya/blob/main/README.md

Create a group, add three synthesizers using the simple_sine SynthDef with different frequencies, and query the node tree.

```python
>>> group = server.add_group()
```

```python
>>> for i in range(3):
...     _ = group.add_synth(simple_sine, frequency=111 * (i + 1))
...
```

```python
>>> print(server.query_tree())
NODE TREE 0 group
    1 group
        1000 group
            1003 simple_sine
                amplitude: 0.1, frequency: 333.0, gate: 1.0
            1002 simple_sine
                amplitude: 0.1, frequency: 222.0, gate: 1.0
            1001 simple_sine
                amplitude: 0.1, frequency: 111.0, gate: 1.0
```

--------------------------------

### Filter private names from Server namespace

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Uses a list comprehension to filter out names starting with an underscore, showing only public attributes and methods.

```python
# actually let's look at the public name inside the Server namespace...
# this is a list comprehension with a filtering clause:
[name for name in dir(server) if not name.startswith("_")]
```

--------------------------------

### Show ugen decorator help with help(ugen)

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Displays the signature and docstring of the ugen decorator from supriya.ugens.core. It shows all available keyword arguments and explains that it collects parameter descriptors and generates initializer and rate class methods.

```python
help(ugen)
```

```text
Output:
Help on function ugen in module supriya.ugens.core:

ugen(
    *,
    ar: bool = False,
    kr: bool = False,
    ir: bool = False,
    dr: bool = False,
    new: bool = False,
    has_done_flag: bool = False,
    is_input: bool = False,
    is_multichannel: bool = False,
    is_output: bool = False,
    is_pure: bool = False,
    is_width_first: bool = False,
    channel_count: int = 1,
    fixed_channel_count: bool = False,
    signal_range: Optional[int] = None
) -> Callable[[Type[ForwardRef('UGen')]], Type[ForwardRef('UGen')]]
    Decorate a UGen class.

    Akin to dataclasses.dataclass.

    Collects parameter descriptors and generates initializer and rate class methods.

```

--------------------------------

### Check client IDs of connected servers

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Prints the client_id of both servers. The second server gets a different client ID (1) as expected.

```python
# note that the client IDs are different, as expected
print(f"{server.client_id=}")
print(f"{other_server.client_id=}")
```

```text
Output:
server.client_id=0
other_server.client_id=1

```

--------------------------------

### Async Boot Callback

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Async callback for the 'booted' event. It adds a group and a synth with frequency 123, then syncs.

```python
async def on_boot(event):
    with async_server.at():
        group = async_server.add_group()
        with async_server.add_synthdefs(supriya.default):
            _ = group.add_synth(synthdef=supriya.default, frequency=123)
    await async_server.sync()
```

--------------------------------

### Explicitly Select Server Binary

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Uses the executable keyword to choose the scsynth binary.

```python
>>> server.boot(executable="scsynth")
```

--------------------------------

### Create group with ticker and reverb synths

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/nodes.rst

Resets the server, creates a group with a ticker and reverb synth, and syncs.

```python
>>> server.reset()
```

```python
>>> with server.at():
...     group = server.add_group()
...     with server.add_synthdefs(ticker_synthdef, reverb_synthdef):
...         ticker_synth = group.add_synth(ticker_synthdef)
...         reverb_synth = group.add_synth(reverb_synthdef, add_action="add_to_tail")
...
```

```python
>>> server.sync()  # wait for synthdefs to load
```

--------------------------------

### Define a callback with arguments and re-scheduling

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/clocks.rst

Define a more complicated callback that accepts additional arguments and can re-schedule itself by returning a delta and time unit. The example shows how to use max_repeats and context.event.invocations to control repetition.

```python
>>> def callback(
...     context,
...     salutation,
...     delta=0.25,
...     max_repeats=0,
...     time_unit=supriya.clocks.TimeUnit.SECONDS,
... ):
...     print(f"{salutation}: {context.current_moment.offset}")
...     if max_repeats and context.event.invocations < max_repeats:
...         print("Re-scheduling")
...         return delta, time_unit
...     else:
...         print("Bailing!")
...
```

--------------------------------

### Create an async clock with supriya.AsyncClock()

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/clocks.rst

Instantiate an async clock. Async clocks have identical APIs to threaded clocks, but their start and stop methods are async and scheduled callbacks may also be async.

```python
>>> clock = supriya.AsyncClock()
```

--------------------------------

### Hidden book block with visuals

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/documenting.rst

Audio and visual output from hidden `.. book::` blocks is rendered even when textual input/output is hidden. This example uses `:hide:` with `supriya.graph(supriya.default)` to generate a visual.

```rst-example
..  book::
    :hide:

    >>> supriya.graph(supriya.default)

```

--------------------------------

### pytest tests/test_examples.py::test_async_and_sync

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/developers/testing.rst

Command to run the test that checks both sync and async server flavors.

```shell
pytest tests/test_examples.py::test_async_and_sync
```

--------------------------------

### Build SynthDef with Builder

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Builds a SynthDef named 'simple' using the builder pattern with frequency and out controls.

```python
# A simple SynthDef using the builder pattern
from supriya.ugens import Out, SinOsc, SynthDefBuilder

with SynthDefBuilder(freq=440, out=0) as builder:
    source = SinOsc.ar(frequency=builder["freq"])
    Out.ar(bus=builder["out"], source=source)

(simple_synthdef := builder.build(name="simple"))  # noqa: PLW0131
```

--------------------------------

### AsyncServer Online Output

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Output after awaiting the boot coroutine, showing the server is online.

```text
Result:
<AsyncServer ONLINE [/Applications/SuperCollider.app/Contents/Resources/scsynth -R 0 -l 1 -u 51590]>
```

--------------------------------

### Compile SynthDef via sclang

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Compiles a SuperCollider SynthDef string using `SuperColliderSynthDef` from `supriya.ugens`. This is intended for validating Supriya's logic against sclang as a reference specification. The example creates a SynthDef named 'foo' with two sine oscillators at 420 and 440 Hz.

```python
from supriya.ugens import SuperColliderSynthDef

sc_synthdef = SuperColliderSynthDef(
    "foo", "Out.ar(0, SinOsc.ar(freq: 420) * SinOsc.ar(freq: 440))"
)
(sc_compiled_synthdef := sc_synthdef.compile())  # noqa: PLW0131
```

--------------------------------

### Boot with Custom Port

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Overrides the default port 57110 using keyword arguments.

```python
>>> server.boot(port=56666)
```

--------------------------------

### Boot Error Traceback

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Error traceback showing ServerCannotBoot due to address in use.

```text
Error (truncated):
[32m    624[39m     [38;5;28;01mif[39;00m ([38;5;28mself[39m._shutdown_future.result()) == ServerShutdownEvent.PROCESS_PANIC:
[32m-->  [39m[32m625[39m         [38;5;28;01mraise[39;00m ServerCannotBoot([38;5;28mself[39m.process_protocol.error_text)
[32m    626[39m [38;5;28;01mreturn[39;00m [38;5;28mself[39m

[31mServerCannotBoot[39m: *** ERROR: failed to open UDP socket: address in use.

```

--------------------------------

### Create LPF UGen with builder

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Uses the builder again to create a low-pass filter with a mix of saw oscillators and an XLine frequency sweep.

```python
# use the builder again
with builder:
    low_pass = LPF.ar(
        source=Mix.new(
            VarSaw.ar(
                frequency=builder["frequency"]
                + (
                    0,
                    Rand.ir(minimum=-0.4, maximum=0.0),
                    Rand.ir(minimum=0.0, maximum=0.4),
                ),
                width=0.3,
            )
        )
        * 0.3,
        frequency=XLine.kr(
            start=Rand.ir(minimum=4000, maximum=5000),
            stop=Rand.ir(minimum=2500, maximum=3200),
        ),
    )
```

--------------------------------

### Use AsyncServer with async lifecycle methods

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/tutorials/servers.rst

Define and run an async main function that boots an AsyncServer, sends an OSC message, queries the node tree, and quits. The send method does not require await, while boot, query_tree, and quit do. Top-level await is used in the documentation; in other contexts wrap in asyncio.run(...).

```python
>>> async def main():
...     # Instantiate an async server
...     print(async_server := supriya.AsyncServer())
...     # Boot it on an arbitrary open port
...     print(await async_server.boot(port=supriya.osc.find_free_port()))
...     # Send an OSC message to the async server (doesn't require await!)
...     async_server.send(["/g_new", 1000, 0, 1])
...     # Query the async server's node tree
...     print(await async_server.query_tree())
...     # Quit the async server
...     print(await async_server.quit())
...
```

```python
>>> await main()
```

--------------------------------

### Inspect server options

Source: https://github.com/supriya-project/supriya/blob/main/docs/notebooks/supercollider-symposium-2025/presentation.ipynb

Inspects the server's options object, which contains configuration values such as audio bus channel count, block size, and port. The output shows the default values for all options.

```python
server.options
```

--------------------------------

### CLI help invocation

Source: https://github.com/supriya-project/supriya/blob/main/docs/source/examples/hello_world_contexts.rst

Shows the command to display help for the script.

```shell
python -m examples.hello_world_contexts --help
```
Tokens:
Raw