examples/sc3nb-examples.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Starting sc3nb"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sc3nb as scn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To startup sc3nb (sclang, scsynth, and a python OSC server) use `startup` which will return a `SC` instance which is the central SuperCollider Interface"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc = scn.startup()  # see Configuration of sc3nb startup below for more details"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can produce a test sound with `blip`, which should relax any tensions whether the server is up and running. This sound should be played by the default server start."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.blip()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`sc` provides you the interfaces for\n",
    "\n",
    "* `scsynth` via `sc.server`\n",
    "* `sclang` via `sc.lang`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Configuration of sc3nb startup**:\n",
    "\n",
    "- Specifying the excutable location\n",
    "  - We try to find the sclang and scsynth executables in the `$PATH` environment variable and also in the default installation directories\n",
    "      - On macOS they reside in `/Applications/SuperCollider.app/Contents` in the folders MacOS and Resources. <br>\n",
    "    To add these paths to your `$PATH`, simply add to your ~/.profile, e.g. (please adapt to your installation): <br>\n",
    "    `PATH=$PATH:/Applications/SuperCollider.app/Contents/MacOS:/Applications/SuperCollider.app/Contents/Resources`  \n",
    "      - On Windows they reside in your Installation folder f.e `C:\\Program Files\\SuperCollider-3.x.x`\n",
    "\n",
    "  - If the executables are not found, you can specify them with `sclang_path` / `scsynth_path` e.g. `sclang_path=\"/path/to/sclang-containing-dir/sclang\"`\n",
    "- You could also only use **scsynth** only and don't start **sclang** with `start_sclang=False`\n",
    "- See `help(scn.startup)` for all options"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# help(scn.startup)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic examples"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use Python implementations to control the SuperCollider audio server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create and control SuperCollider Synths"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "syn = scn.Synth(\"s2\")\n",
    "syn"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "syn.freq = 800\n",
    "syn"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "syn.free()  # or use the ctrl-. (cmd-.) shortcut in Jupyter notebooks\n",
    "syn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Send SynthDefs with python code injection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "synth_dur = 0.5  # you can use python variables in SynthDefs by prepending ^\n",
    "synth_def = scn.SynthDef('random', \"\"\"{ |out|\n",
    "    var line;\n",
    "    line = Line.kr(1, 0, ^synth_dur, doneAction: Done.freeSelf);\n",
    "    Out.ar(out, SinOsc.ar(Rand(400, 800), 0, 0.2) * line);\n",
    "}\"\"\")\n",
    "synth_def.add()\n",
    "synth_def  # Note that the representation has synth_dur already injected"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "scn.Synth(\"random\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Load a file as Buffer and play it"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "buf = scn.Buffer().read(\"./media/blip.wav\")\n",
    "buf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "buf.play()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "buffer_data = buf.to_array()\n",
    "print(buffer_data.shape)\n",
    "buffer_data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More examples about the above used SuperCollider objects can be found in the respective User Guide sections \n",
    "* [Nodes (Synths and Groups)](./supercollider-objects/node-examples.ipynb)\n",
    "* [SynthDef](./supercollider-objects/synthdef-examples.ipynb)\n",
    "* [Buffer](./supercollider-objects/buffer-examples.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use OSC to control the SuperCollider audio server"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Send OSC Messages with [SuperCollider Commands](https://doc.sccode.org/Reference/Server-Command-Reference.html) and receive replies"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.msg(\"/status\")  # waits for reply message and returns it"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We offer also high level versions for the commands. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.status()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create OSC Bundles using SuperCollider Commands directly"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with sc.server.bundler() as bundler:\n",
    "    bundler.add(0.2, \"/s_new\", [\"s1\", -1, 0, 0])\n",
    "    bundler.add(0.5, \"/s_new\", [\"s1\", -1, 0, 0, \"freq\", 800, \"dur\", 0.1])\n",
    "bundler.messages()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or create OSC Bundles with the high level Python implementations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with sc.server.bundler() as bundler:\n",
    "    bundler.wait(0.2)\n",
    "    scn.Synth(\"s1\")\n",
    "    bundler.wait(0.3)\n",
    "    scn.Synth(\"s1\", {\"freq\": 800, \"dur\": 0.1})\n",
    "bundler.messages()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[More OSC communication examples](./osc-communication-examples.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use the SuperCollider Language from Python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Execute SuperCollider Language Code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "breakfast = \"eggs\"\n",
    "sc.lang.cmd('^breakfast.scramble;')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or via the **%sc** IPython magic"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%sc ^breakfast.scramble"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get results from SuperCollider Language in python with `cmdg` or **%scg**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 5\n",
    "value = %scg (1..^x)\n",
    "print(f\"received {value} with type {type(value)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[More sclang in sc3nb examples](./osc-communication-examples.ipynb)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Stoping the synthesis\n",
    "\n",
    "There are multiple options to stop the playing audio synthesis"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%sc x = Synth.new(\"default\")  // starting a Synth with sclang"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* to stop all playing synths either use CMD-. (in Jupyter Command mode).\n",
    "\n",
    "* It is a shortcut for the ´free_all´ method of the default server"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.free_all()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* or you could also use sclang"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%sc s.freeAll"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Combined usage\n",
    "\n",
    "It is also possible to mix the different interaction styles."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* create a Synth with sclang and get the nodeid of the Synth via the **%scg** IPython magic"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nodeid = %scg x = Synth(\"default\"); x.nodeID;"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* create the corresponding Python Synth instance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "synth = scn.Synth(\"default\", nodeid=nodeid, new=False)\n",
    "synth"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Inspect and control the Synth from Python"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "synth.synth_desc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "synth.freq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "synth.freq *= 2\n",
    "synth.freq"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "synth"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* send a OSC Message to free the Synth"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.server.msg(\"/n_free\", nodeid)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "synth"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exiting sc3nb\n",
    "\n",
    "To shut down the server and sclang subprocesses"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.exit()  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further information and advanced examples\n",
    "\n",
    "For more details on the specific parts please refer to the corresponding sections of the User Guide.\n",
    "\n",
    "* Usage of [SuperCollider Language (sclang) in sc3nb](./sclang-examples.ipynb)\n",
    "\n",
    "\n",
    "* Usage of the SuperCollider Objects python interface\n",
    "  * [Server](./supercollider-objects/server-examples.ipynb)\n",
    "  * [Nodes (Synth and Group)](./supercollider-objects/node-examples.ipynb)\n",
    "  * [SynthDef](./supercollider-objects/synthdef-examples.ipynb)\n",
    "  * [Buffer](./supercollider-objects/buffer-examples.ipynb)\n",
    "  * [Bus](./supercollider-objects/bus-examples.ipynb)\n",
    "  * [Recorder](./supercollider-objects/recorder-examples.ipynb)\n",
    "\n",
    "\n",
    "* Usage of [common SuperCollider helper functions](./helper-examples.ipynb)\n",
    "* Usage of [OSC in sc3nb](./osc-communication-examples.ipynb)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "hide_input": false,
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": true,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}