sc-kernel 0.3.2__tar.gz → 0.5.0__tar.gz

sc_kernel-0.5.0/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2020 Dennis Scheiba
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

sc_kernel-0.5.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: sc_kernel
+Version: 0.5.0
+Summary: SuperCollider kernel for Jupyter
+Author: Dennis Scheiba
+License: BSD
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: IPython
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: metakernel<0.31,>=0.23.0
+Requires-Dist: ipython<10.0,>=4.0
+Requires-Dist: pygments<3.0
+Requires-Dist: jupyterlab<5.0,>=3.0
+Requires-Dist: jupyter_server<3.0,>2.0
+Provides-Extra: dev
+Requires-Dist: coverage==5.2.1; extra == "dev"
+Requires-Dist: flake8<=6.0.0; extra == "dev"
+Requires-Dist: unittest-xml-reporting==3.0.4; extra == "dev"
+Requires-Dist: mypy<=1.0.0; extra == "dev"
+Requires-Dist: pre-commit==2.17.0; extra == "dev"
+Requires-Dist: black<=23.1.0; extra == "dev"
+Dynamic: license-file
+
+# Supercollider Jupyter Kernel
+
+This kernel allows running [SuperCollider](https://supercollider.github.io/) Code in a [Jupyter](https://jupyter.org/) environment.
+
+![Demo Notebook](demo.jpg)
+
+## Installation
+
+Please make sure one has installed [SuperCollider](https://supercollider.github.io/) and
+[Python 3 with pip](https://realpython.com/installing-python).
+
+* To install the kernel for Jupyter execute
+
+  ```shell
+  pip3 install --upgrade sc-kernel
+  ```
+
+  This will also install [Jupyter Lab](https://jupyter.org/) if it is not already installed on the system.
+
+* Start a new Jupyter Lab instance by executing `jupyter lab` in a console.
+
+* Click on the SuperCollider icon
+
+If one has not installed SuperCollider in the default location, one has to set a environment variable
+called `SCLANG_PATH` which points to the sclang executable.
+
+To uninstall the kernel execute
+
+```shell
+jupyter kernelspec uninstall sc_kernel
+```
+
+### As a Docker container
+
+It is also possible to run sc-kernel in a Docker container, although a sound output is not possible in this case.
+Assuming you have cloned the repository and opened a terminal in its directory.
+
+```shell
+# build container - takes some time b/c we build supercollider
+docker build -t sc_kernel .
+# run container
+# -v mounts the current directory to the container
+# -p passes the container port to our host
+docker run -v ${PWD}:/home/sc_kernel -p 8888:8888 sc_kernel
+```
+
+## Usage
+
+Contrary to ScIDE each document will run in its own interpreter and not in a shared one.
+This is the default behavior of Jupyter but maybe this will be changed at a later point.
+
+Currently it is only possible to use the default config - if you encounter missing classes
+it is probably caused that they are not available in the default config.
+
+### Stop sound
+
+Currently the `Cmd + .` command is not binded. Instead create a new cell with a single dot
+
+```supercollider
+.
+```
+
+and execute this cell. This will transform the command to `CommandPeriod.run;` which is what is actually called on the `Cmd + .` press in the IDE.
+
+### Recording
+
+`sc_kernel` provides an easy way to record audio to the local directory and store it embedded in the notebook
+so one can transfer the notebook into a website which has the audio files included.
+
+The audio is stored in FLAC with 16 bit resolution.
+
+The provided function `record` takes 2 arguments:
+
+* Duration in seconds
+* Filename which will be used for the recording, using the path of the notebook as base path.
+
+Assuming one has started the server, simply execute
+
+```supercollider
+Ndef(\sine, {
+    var sig = SinOsc.ar(LFDNoise0.kr(1.0!2).exprange(100, 400));
+    sig = sig * \amp.kr(0.2);
+    sig;
+}).play;
+
+record.(4.0);
+```
+
+![Recording](recording.png)
+
+### Plotting
+
+`sc_kernel` also provides a way to embed images of SuperCollider windows into the Jupyter document.
+First create a window that you want to embed into the document
+
+```supercollider
+w = {SinOsc.ar(2.0)}.plot(1.0);
+```
+
+After the plotting is finished by the server we can now simply save an image of the window
+to a file and also embed the image into the document via a SuperCollider helper method which is available.
+
+```supercollider
+plot.(w);
+```
+
+![Plotting magic](plotting.png)
+
+The image will be saved relative the directory where `jupyter lab` was executed.
+The optional second argument can be the filename.
+
+> Note that `{}.plot` does not return a `Window` but a `Plotter`, but `sc_kernel`
+> accesses the window of a `Plotter` automatically.
+>
+> For plotting e.g. the server meter you need to pass the proper window, so
+>
+> ```supercollider
+> a = s.meter;
+> // a is a ServerMeter
+>
+> // new cell
+> plot.(a.window, "meter.png");
+> ```
+
+### Autocomplete
+
+Simply push `Tab` to see available autocompletions.
+This is currently limited to scan for available classes.
+
+### Documentation
+
+To display the documentation of a Class, simply prepend a `?` to it and execute it, e.g.
+
+```supercollider
+?SinOsc
+```
+
+You can also hit `shift <tab>` iff the cursor is behind a class to trigger the inline documentation.
+
+![Inline documentation](inline_docs.png)
+
+### Real Time Collaboration
+
+Jupyter Lab allows for real time collaboration in which multiple users can write in the same document from different computers by visiting the Jupyter server via their browser.
+Each user can write and execute sclang statements on your local sclang interpreter and the cursors of each user is shown to everyone.
+
+This allows for interactive, shared sessions which can be an interesting live coding sessions.
+
+> Be aware that this can be a security threat as it allows for other people from within the network to execute arbitrary sclang commands on your computer
+
+To start such a session you can spin Jupyter Lab via
+
+```shell
+jupyter lab --ip 0.0.0.0 --collaborative --NotebookApp.token='sclang'
+```
+
+where the `NotebookApp.token` is the necessary password to login - set it to `''` if no password is wanted.
+
+Check out the [documentation on Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html) about *Real Time Collaboration*.
+
+## Development
+
+Any PR is welcome! Please state the changes in an Issue.
+To contribute, please
+
+* Fork the repository and clone it to a local directory
+
+* Create a virtual environment and install the dev dependencies
+  in it with
+
+  ```shell
+  pip3 install -e ".[dev]"
+  ```
+
+* If one wants to add the kernel to an existing Jupyter installation one can execute
+
+  ```shell
+  jupyter kernelspec install sc_kernel
+  ```
+
+  and run `jupyter lab` from within the cloned directory as
+  we need to have access to `sc_kernel`.
+
+* Run `./run_tests.sh` and make a PR :)
+  Use `black sc_kernel test` to format the source code.
+
+## Maintainers
+
+* [Dennis Scheiba](https://dennis-scheiba.com)

sc_kernel-0.5.0/README.md

@@ -0,0 +1,189 @@
+# Supercollider Jupyter Kernel
+
+This kernel allows running [SuperCollider](https://supercollider.github.io/) Code in a [Jupyter](https://jupyter.org/) environment.
+
+![Demo Notebook](demo.jpg)
+
+## Installation
+
+Please make sure one has installed [SuperCollider](https://supercollider.github.io/) and
+[Python 3 with pip](https://realpython.com/installing-python).
+
+* To install the kernel for Jupyter execute
+
+  ```shell
+  pip3 install --upgrade sc-kernel
+  ```
+
+  This will also install [Jupyter Lab](https://jupyter.org/) if it is not already installed on the system.
+
+* Start a new Jupyter Lab instance by executing `jupyter lab` in a console.
+
+* Click on the SuperCollider icon
+
+If one has not installed SuperCollider in the default location, one has to set a environment variable
+called `SCLANG_PATH` which points to the sclang executable.
+
+To uninstall the kernel execute
+
+```shell
+jupyter kernelspec uninstall sc_kernel
+```
+
+### As a Docker container
+
+It is also possible to run sc-kernel in a Docker container, although a sound output is not possible in this case.
+Assuming you have cloned the repository and opened a terminal in its directory.
+
+```shell
+# build container - takes some time b/c we build supercollider
+docker build -t sc_kernel .
+# run container
+# -v mounts the current directory to the container
+# -p passes the container port to our host
+docker run -v ${PWD}:/home/sc_kernel -p 8888:8888 sc_kernel
+```
+
+## Usage
+
+Contrary to ScIDE each document will run in its own interpreter and not in a shared one.
+This is the default behavior of Jupyter but maybe this will be changed at a later point.
+
+Currently it is only possible to use the default config - if you encounter missing classes
+it is probably caused that they are not available in the default config.
+
+### Stop sound
+
+Currently the `Cmd + .` command is not binded. Instead create a new cell with a single dot
+
+```supercollider
+.
+```
+
+and execute this cell. This will transform the command to `CommandPeriod.run;` which is what is actually called on the `Cmd + .` press in the IDE.
+
+### Recording
+
+`sc_kernel` provides an easy way to record audio to the local directory and store it embedded in the notebook
+so one can transfer the notebook into a website which has the audio files included.
+
+The audio is stored in FLAC with 16 bit resolution.
+
+The provided function `record` takes 2 arguments:
+
+* Duration in seconds
+* Filename which will be used for the recording, using the path of the notebook as base path.
+
+Assuming one has started the server, simply execute
+
+```supercollider
+Ndef(\sine, {
+    var sig = SinOsc.ar(LFDNoise0.kr(1.0!2).exprange(100, 400));
+    sig = sig * \amp.kr(0.2);
+    sig;
+}).play;
+
+record.(4.0);
+```
+
+![Recording](recording.png)
+
+### Plotting
+
+`sc_kernel` also provides a way to embed images of SuperCollider windows into the Jupyter document.
+First create a window that you want to embed into the document
+
+```supercollider
+w = {SinOsc.ar(2.0)}.plot(1.0);
+```
+
+After the plotting is finished by the server we can now simply save an image of the window
+to a file and also embed the image into the document via a SuperCollider helper method which is available.
+
+```supercollider
+plot.(w);
+```
+
+![Plotting magic](plotting.png)
+
+The image will be saved relative the directory where `jupyter lab` was executed.
+The optional second argument can be the filename.
+
+> Note that `{}.plot` does not return a `Window` but a `Plotter`, but `sc_kernel`
+> accesses the window of a `Plotter` automatically.
+>
+> For plotting e.g. the server meter you need to pass the proper window, so
+>
+> ```supercollider
+> a = s.meter;
+> // a is a ServerMeter
+>
+> // new cell
+> plot.(a.window, "meter.png");
+> ```
+
+### Autocomplete
+
+Simply push `Tab` to see available autocompletions.
+This is currently limited to scan for available classes.
+
+### Documentation
+
+To display the documentation of a Class, simply prepend a `?` to it and execute it, e.g.
+
+```supercollider
+?SinOsc
+```
+
+You can also hit `shift <tab>` iff the cursor is behind a class to trigger the inline documentation.
+
+![Inline documentation](inline_docs.png)
+
+### Real Time Collaboration
+
+Jupyter Lab allows for real time collaboration in which multiple users can write in the same document from different computers by visiting the Jupyter server via their browser.
+Each user can write and execute sclang statements on your local sclang interpreter and the cursors of each user is shown to everyone.
+
+This allows for interactive, shared sessions which can be an interesting live coding sessions.
+
+> Be aware that this can be a security threat as it allows for other people from within the network to execute arbitrary sclang commands on your computer
+
+To start such a session you can spin Jupyter Lab via
+
+```shell
+jupyter lab --ip 0.0.0.0 --collaborative --NotebookApp.token='sclang'
+```
+
+where the `NotebookApp.token` is the necessary password to login - set it to `''` if no password is wanted.
+
+Check out the [documentation on Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html) about *Real Time Collaboration*.
+
+## Development
+
+Any PR is welcome! Please state the changes in an Issue.
+To contribute, please
+
+* Fork the repository and clone it to a local directory
+
+* Create a virtual environment and install the dev dependencies
+  in it with
+
+  ```shell
+  pip3 install -e ".[dev]"
+  ```
+
+* If one wants to add the kernel to an existing Jupyter installation one can execute
+
+  ```shell
+  jupyter kernelspec install sc_kernel
+  ```
+
+  and run `jupyter lab` from within the cloned directory as
+  we need to have access to `sc_kernel`.
+
+* Run `./run_tests.sh` and make a PR :)
+  Use `black sc_kernel test` to format the source code.
+
+## Maintainers
+
+* [Dennis Scheiba](https://dennis-scheiba.com)

sc_kernel-0.5.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sc_kernel"
+version = "0.5.0"
+description = "SuperCollider kernel for Jupyter"
+readme = "README.md"
+license = { text = "BSD" }
+authors = [
+    { name = "Dennis Scheiba" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "metakernel>=0.23.0, <0.31",
+    "ipython>=4.0, <10.0",
+    "pygments<3.0",
+    "jupyterlab>=3.0, <5.0",
+    "jupyter_server<3.0, >2.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Framework :: IPython",
+    "License :: OSI Approved :: BSD License",
+    "Topic :: System :: Shells",
+    "Topic :: Multimedia :: Sound/Audio :: Sound Synthesis",
+]
+
+[project.optional-dependencies]
+dev = [
+    "coverage==5.2.1",
+    "flake8<=6.0.0",
+    "unittest-xml-reporting==3.0.4",
+    "mypy<=1.0.0",
+    "pre-commit==2.17.0",
+    "black<=23.1.0"
+]
+
+[tool.setuptools]
+packages = ["sc_kernel"]
+
+[tool.setuptools.package-data]
+"sc_kernel" = ["images/*.png", "kernel.json"]
+
+[tool.setuptools.data-files]
+"share/jupyter/kernels/sc_kernel" = [
+    "sc_kernel/kernel.json",
+    "sc_kernel/images/logo-32x32.png",
+    "sc_kernel/images/logo-64x64.png",
+]

sc_kernel-0.5.0/sc_kernel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"