:hero: a Python API for SuperCollider

Supriya (|release|)
===================

:term:`Supriya` is a :term:`Python` API for :term:`SuperCollider`.

Supriya lets you:

- Boot and communicate with SuperCollider's synthesis engine in
  realtime.

- Explore :py:mod:`~supriya.contexts.nonrealtime` composition with 
  :py:class:`scores <supriya.contexts.nonrealtime.Score>`.

- Compile SuperCollider :py:class:`SynthDefs
  <supriya.ugens.bases.SynthDef>` natively in Python code.

- Build time-agnostic :py:mod:`asyncio`-aware applications with the
  :py:class:`context <supriya.contexts.core.Context>` interface.

- Schedule :py:mod:`~supriya.patterns` and callbacks with tempo- and
  meter-aware :py:mod:`~supriya.clocks`.

- Integrate with `IPython`_, `Sphinx`_ and `Graphviz`_.

Have fun!

| xoxo,
| `joséphine`_

Quickstart
----------

1. Get Supriya
``````````````

..  include:: /includes/install.txt

..  note::

    Consult our :doc:`installation instructions </introduction/installation>`
    for detailed help on getting Supriya, setting it up, and installing any
    additional dependencies like `Graphviz`_.

2. Get SuperCollider
````````````````````

Get `SuperCollider`_ from https://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 :term:`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`_)::
    
    >>> supriya.graph(simple_sine)

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

6. Release and quit
```````````````````

Release the synths::

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

Quit the server::

    >>> server.quit()

..  toctree::
    :caption: Introduction
    :hidden: 

    introduction/installation
    introduction/history.rst
    introduction/concepts.rst

..  toctree::
    :caption: Core tutorials
    :hidden: 

    tutorials/index
    tutorials/contexts
    tutorials/servers
    tutorials/nodes
    tutorials/buses
    tutorials/buffers
    tutorials/synthdefs
    tutorials/osc
    tutorials/scores

..  toctree::
    :caption: Advanced tutorials
    :hidden: 

    advanced/index
    advanced/clocks
    advanced/patterns
    advanced/extensions

..  toctree::
    :caption: Examples
    :hidden: 

    examples/index
    examples/hello_world
    examples/hello_world_contexts
    examples/hello_world_debugged
    examples/keyboard_input
    examples/keyboard_input_async

..  toctree::
    :caption: For developers
    :hidden: 

    developers/index
    developers/testing
    developers/documenting
    developers/releasing

..  toctree::
    :caption: API Reference
    :hidden: 
    :maxdepth: 2

    api/supriya/index
    api/examples/index

..  toctree::
    :hidden: 
    :caption: Appendices

    appendices/glossary
