Metadata-Version: 2.4
Name: supriya
Version: 25.11b0
Summary: A Python API for SuperCollider
Author-email: Joséphine Wolf Oberholtzer <josephine.wolf.oberholtzer@gmail.com>
License: MIT
Project-URL: homepage, https://github.com/supriya-project/supriya
Project-URL: documentation, https://supriya-project.github.io/supriya
Project-URL: repository, https://github.com/supriya-project/supriya
Keywords: audio,dsp,music composition,scsynth,supercollider,synthesis
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Artistic Software
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: backports.strenum; python_version < "3.11"
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: psutil
Requires-Dist: uqbar>=0.9.6
Provides-Extra: docs
Requires-Dist: supriya[examples]; extra == "docs"
Requires-Dist: jupyterlab; extra == "docs"
Requires-Dist: jupyterlab-rise; extra == "docs"
Requires-Dist: librosa; extra == "docs"
Requires-Dist: matplotlib; extra == "docs"
Requires-Dist: mypy; extra == "docs"
Requires-Dist: soxr; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-immaterial; extra == "docs"
Requires-Dist: sphinx-toolbox; extra == "docs"
Requires-Dist: sphinxext-opengraph; extra == "docs"
Requires-Dist: standard-aifc; python_version >= "3.13" and extra == "docs"
Requires-Dist: standard-sunau; python_version >= "3.13" and extra == "docs"
Provides-Extra: examples
Requires-Dist: pynput; extra == "examples"
Requires-Dist: python-rtmidi; extra == "examples"
Provides-Extra: test
Requires-Dist: IPython; extra == "test"
Requires-Dist: librosa; extra == "test"
Requires-Dist: lxml; extra == "test"
Requires-Dist: matplotlib; extra == "test"
Requires-Dist: mypy; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-lazy-fixtures; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: pytest-rerunfailures; extra == "test"
Requires-Dist: ruff; extra == "test"
Requires-Dist: standard-aifc; python_version >= "3.13" and extra == "test"
Requires-Dist: standard-sunau; python_version >= "3.13" and extra == "test"
Requires-Dist: types-PyYAML; extra == "test"
Requires-Dist: types-docutils; extra == "test"
Requires-Dist: types-psutil; extra == "test"
Requires-Dist: types-pynput; extra == "test"
Dynamic: license-file

# Supriya

[![](https://img.shields.io/pypi/pyversions/supriya)]()
[![](https://img.shields.io/pypi/l/supriya)]()
[![](https://img.shields.io/github/actions/workflow/status/supriya-project/supriya/test.yml?branch=main)]()

[Supriya](https://github.com/supriya-project/supriya) is a
[Python](https://www.python.org/) API for
[SuperCollider](http://supercollider.github.io/).

Supriya lets you:

- Boot and communicate with SuperCollider's synthesis engine
  in [realtime](http://supriya-project.github.io/supriya/api/supriya/contexts/realtime.html).

- Explore
  [nonrealtime](http://supriya-project.github.io/supriya/api/supriya/contexts/nonrealtime.html)
  composition with scores.

- Compile SuperCollider
  [SynthDefs](http://supriya-project.github.io/supriya/api/supriya/ugens/index.html)
  natively in Python code

- Build time-agnostic
  [asyncio](https://docs.python.org/3/library/asyncio.html)-aware applications
  with the
  [context](http://supriya-project.github.io/supriya/api/supriya/contexts/core.html)
  interface.

- Schedule
  [patterns](http://supriya-project.github.io/supriya/api/supriya/patterns/index.html)
  and callbacks with tempo- and meter-aware
  [clocks](http://supriya-project.github.io/supriya/api/supriya/clocks/index.html)

- Integrate with [IPython](http://ipython.org/),
  [Sphinx](https://www.sphinx-doc.org/en/master/) and
  [Graphviz](http://graphviz.org/)

## Quickstart

### 1. Get Supriya

Install from PyPI:

    pip install supriya

Or from source:

    git clone https://github.com/supriya-project/supriya.git
    cd supriya
    pip install -e .

### 2. Get SuperCollider

Get SuperCollider from http://supercollider.github.io/.

### 3. Boot the server

Start your Python interpreter and import Supriya:

    >>> import supriya

Boot the SuperCollider server:

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

### 4. Build a SynthDef

Import some classes:

    >>> from supriya import Envelope, synthdef
    >>> from supriya.ugens import EnvGen, Out, SinOsc

Make a synthesizer definition:

    >>> @synthdef()
    ... def simple_sine(frequency=440, amplitude=0.1, gate=1):
    ...     sine = SinOsc.ar(frequency=frequency) * amplitude
    ...     envelope = EnvGen.kr(envelope=Envelope.adsr(), gate=gate, done_action=2)
    ...     Out.ar(bus=0, source=[sine * envelope] * 2)
    ...

Visualize the SynthDef (requires [Graphviz](http://graphviz.org/)):
    
    >>> supriya.graph(simple_sine)

<img src="./graph.svg">

Allocate it on the server:

    >>> _ = server.add_synthdefs(simple_sine)

... and then sync the server before proceeding to ensure the SynthDef has been
fully parsed by scsynth:

    >>> _ = server.sync()

### 5. Create some nodes

Create and allocate a group:

    >>> group = server.add_group()

Create some synthesizers with the previously defined synthesizer definition, and
allocate them on the server as a child of the previously created group:

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

Query the server's node tree:

    >>> 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

### 6. Release and quit

Release the synths:

    >>> for synth in group.children[:]:
    ...     synth.free()
    ...

Quit the server:

    >>> server.quit()

## License

This library is made available under the terms of the MIT license.
