examples/supercollider-objects/server-examples.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Server"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sc3nb as scn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `SCServer` class is the central interface for \n",
    "\n",
    "* controlling the SuperCollider audio server process\n",
    "* managing SuperCollider Objects\n",
    "* using OSC for outgoing and incoming packets\n",
    "\n",
    "\n",
    "To achieve all this the SCServer is\n",
    "\n",
    "* registered as a client to the SuperCollider audio server process (scsynth) and exchanging [SuperCollider Commands](http://doc.sccode.org/Reference/Server-Command-Reference.html) with the server process\n",
    "* and also running an OSC server in python which can communicate via OSC with scsynth and sclang.\n",
    "\n",
    "\n",
    "For information about how to communicate using OSC see the [OSC communication notebook](../osc-communication-examples.ipynb). This notebook focuses on using the `SCServer` class for interacting with scsynth "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Starting the Server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The most convienent way is to use the default sc3nb `SCServer` instance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc = scn.startup()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However you can also use the SCServer class directly"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The server connection can be created\n",
    "\n",
    "* locally using `boot`, which will start a scsynth process and connect to it or\n",
    "* remote using `remote` for connecting to an already running scsynth process"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "serv = scn.SCServer()\n",
    "serv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "serv.boot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice how the `SCServer` always tries to boot using the default SuperCollider audio server port 57110.\n",
    "But this port is already used by `sc.server` and thus the `SCServer` tries to connect to the already running instance using `SCserver.remote`. This enables a user to share the same scsynth instance with other users and/or use it from other notebooks. If the port to be used is explicitly specified the `SCServer` instance will fail instead of connecting.\n",
    "\n",
    "The `SCServer` will register to the scsynth process using `SCServer.notify()`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's look how many clients are allowed and what the `client_id`s and the corresponding `default_group`s of the SCServer instances are."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"The scsynth process of this SCServer instance allows {sc.server.max_logins} clients to login.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"sc.server has client id {sc.server.client_id} and the default Group {sc.server.default_group}\") "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"serv has client id {serv.client_id} and the default Group {serv.default_group}\") "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However also note that the instances use different ports meaning they are able to independendly send and receive OSC packets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.connection_info()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and also note that `serv` is not connected to sclang but has the same connection info for scsynth."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "serv.connection_info()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A Synth running on the SuperCollider audio server will be visible to all connected clients"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "serv_synth = scn.Synth(\"s2\", {\"amp\": 0.05, \"pan\": -1, \"freq\": 100}, server=serv)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "default_synth = scn.Synth(\"s2\", {\"amp\": 0.05, \"pan\": 1, \"freq\": 440})  # no need to specify sc.server as server argument"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This also includes sclang, which is another client of the scsynth process"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%sc ~sclang_synth = Synth(\"s2\", [\\amp, 0.1])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.dump_tree()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This also means freeing all Synths at once can be done with each client"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.free_all()\n",
    "# serv.free_all() \n",
    "# %sc s.freeAll"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.dump_tree()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and quitting one server also quits the others."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "serv.quit()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's reboot the default server"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.reboot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More information about [multi client setups](http://doc.sccode.org/Guides/MultiClient_Setups.html) can be found in the SuperCollider documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Configuring Server options\n",
    "\n",
    "Startup options of the `SCServer` instance can be set via `ServerOptions`, which can be passed as argument when starting the `SCServer`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The default ServerOptions in sc3nb are:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scn.ServerOptions()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting Information\n",
    "\n",
    "The `SCServer` instance provides various kinds of information"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* What nodes are currently running"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.dump_tree()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.query_tree()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* The current status of the server, acquired via the `/status` OSC command"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.status()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "which can also be accessed directly via properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.nominal_sr"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.num_synthdefs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* the version of the SC3 server process, acquired via the `/version` OSC command"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.version()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* the address of the SuperCollider audio server"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.addr"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* The connection info"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.connection_info()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* other runtime properties of the Server"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.has_booted"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.is_running"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.client_id"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.max_logins"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.default_group"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.output_bus"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.input_bus"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Controlling Volume"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "syn = scn.Synth(\"s2\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.volume"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scn.dbamp(sc.server.volume)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.muted"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.muted = True"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.volume = -10.0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scn.dbamp(sc.server.volume)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.muted = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.volume = 0.0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scn.dbamp(sc.server.volume)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "syn.free()\n",
    "syn.wait(timeout=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Server dumps\n",
    "\n",
    "The Server process can dump information about"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* incoming OSC packages. See console for output"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.dump_osc() # specify level=0 to deactivate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* currently running Nodes "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.dump_tree()  # Notice how the OSC packet is now included in the output "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.blip() # see dumped bundle for test sound on console"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Make a test sound\n",
    "\n",
    "The following methods produces the `SCServer` startup sound.\n",
    "The test sound should ease any anxiety whether the server is properly started/running"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.blip()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Managing Nodes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* freeing all running nodes and reinitialize the server"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.free_all()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.free_all(root=False)  # only frees the default group of this client"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* send the `/clearSched` OSC command. This is automatically done when using `free_all`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.clear_schedule()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Execute init hooks. This is also automatically done when using `free_all`, `init` or `connect_sclang`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.execute_init_hooks()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Adding init hooks. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.send_default_groups"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Syncing the SuperCollider audio server by sending a `/sync` OSC command and waiting for the reply."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.sync()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Allocating IDs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `SCServer` instance manages the IDs for Nodes, Buffers and Buses for the SuperCollider Objects via the following methods.\n",
    "These can also be used for getting suitable IDs when manually creating OSC packages."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Get the IDs via the allocator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ids = sc.server.buffer_ids.allocate(num=2)\n",
    "ids"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Free the IDs after usage via the allocator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.buffer_ids.free(ids)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are allocators for\n",
    "\n",
    "* Nodes - `sc.server.node_ids`\n",
    "* Buffer - `sc.server.buffer_ids`\n",
    "* Buses (Audio and Control) - `sc.server.audio_bus_ids`, `sc.server.control_bus_ids`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.reboot()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# example to see how consecutive buffer alloc works:\n",
    "ids = sc.server.buffer_ids.allocate(num=5)\n",
    "print(\"5 buffers:\", ids)\n",
    "sc.server.buffer_ids.free(ids[0:2])\n",
    "print(\"freed buffers \", ids[0:2])\n",
    "ids4 = sc.server.buffer_ids.allocate(num=4)\n",
    "print(\"allocated 4 buffers:\", ids4, \"-> new numbers to be consecutive\")\n",
    "sc.server.sync()\n",
    "ids2 = sc.server.buffer_ids.allocate(num=2)\n",
    "print(\"allocated 2 buffers:\", ids2, \"-> using the two freed before\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Handling SynthDefs\n",
    "\n",
    "The server offers the following methods for handling SynthDefs.\n",
    "These are shortcuts for the respective SynthDef methods.\n",
    "\n",
    "```\n",
    "sc.server.send_synthdef\n",
    "sc.server.load_synthdef\n",
    "sc.server.load_synthdefs\n",
    "```\n",
    "Refer to the [SynthDef guide](synthdef-examples.ipynb) for more information about SynthDefs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.exit()"
   ]
  }
 ],
 "metadata": {
  "hide_input": false,
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}