From 4be2f7a4c638558544c2634792f2f34722195aa6 Mon Sep 17 00:00:00 2001 From: Daniel Jones Date: Mon, 6 Nov 2023 21:27:37 +0000 Subject: [PATCH] Update docs with Visual Studio Code instructions --- docs/getting-started.md | 11 ++- docs/installation/macos.md | 58 ---------------- docs/installation/macos/command-line.md | 37 ++++++++++ docs/installation/macos/easy.md | 89 +++++++++++++++++++++++++ docs/installation/working.md | 58 ---------------- mkdocs.yml | 6 +- 6 files changed, 140 insertions(+), 119 deletions(-) delete mode 100644 docs/installation/macos.md create mode 100644 docs/installation/macos/command-line.md create mode 100644 docs/installation/macos/easy.md delete mode 100644 docs/installation/working.md diff --git a/docs/getting-started.md b/docs/getting-started.md index 656a979b..db8fb078 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,8 +6,15 @@ SignalFlow supports macOS, Linux (including Raspberry Pi), and has alpha support ## Installation - - [Installing SignalFlow on macOS](installation/macos.md) - - [Installing SignalFlow on Linux](installation/linux.md) +### macOS + +If you are an existing Python user and confident with the command line: + +[macOS: Install SignalFlow from the command line](installation/macos/command-line.md){ .md-button } + +If you're new to Python or getting started from scratch: + +[macOS: Install SignalFlow with Visual Studio Code](installation/macos/easy.md){ .md-button } ## Examples diff --git a/docs/installation/macos.md b/docs/installation/macos.md deleted file mode 100644 index f63d8345..00000000 --- a/docs/installation/macos.md +++ /dev/null @@ -1,58 +0,0 @@ -# Installing SignalFlow on macOS - -Installing SignalFlow requires some basic terminal usage. Open Terminal via Finder in `Applications > Utilities > Terminal`. - -## 1. Install Python - -Download and install the latest version of Python (3.12) from [Python.org](https://www.python.org/downloads/). - -To check that it has worked, run the below command in Terminal and confirm that it prints a version starting with 3.12: - -``` -python3 --version -``` - -## 2. Set up a virtual environment - -To ensure that your SignalFlow Python install does not conflict with other Python packages on your system, we strongly recommend setting up a dedicated Python "virtual environment" for SignalFlow, which is a self-contained area of the file system containing all of the Python packages and binaries needed for the system. - -To create the virtual environment: - -``` -python3 -m venv signalflow-env -``` - -!!! info - You can replace `signalflow-env` with whatever name you would like to call the virtual environment. - You can also create this virtual env anywhere on your drive, by changing the directory with `cd some/other/path`. - -To activate the virtual environment: - -``` -source signalflow-env/bin/activate -``` - -## 3. Install SignalFlow - -Installing SignalFlow is done using the `pip` Python package manager. The below line will install the `signalflow` library, plus support for `jupyter` interactive Python notebooks, and register your virtual environment system-wide so that notebooks can access it. - -```shell -pip3 install signalflow jupyter -python3 -m ipykernel install --name signalflow-env -``` - -That's it! - -The installation of SignalFlow includes a command-line tool, `signalflow`, that can be used to test and configure the framework. Check that the installation has succeeded by playing a test tone through your default system audio output: - -``` -signalflow test -``` - -## 4. Work with SignalFlow - -Now, let's set up an editor to [work with SignalFlow](working.md). - -## Examples - -[Several example scripts](https://github.com/ideoforms/signalflow/tree/master/examples/python) are included within the repo, covering simple control and modulation, FM synthesis, sample granulation, MIDI control, chaotic functions, etc. diff --git a/docs/installation/macos/command-line.md b/docs/installation/macos/command-line.md new file mode 100644 index 00000000..ab14fdb5 --- /dev/null +++ b/docs/installation/macos/command-line.md @@ -0,0 +1,37 @@ +# SignalFlow: Command-line installation for macOS + +These instructions assume you have a working version of Python 3.8+, installed either via [Homebrew](http://brew.sh) or from [Python.org](https://www.python.org/downloads/). + +## 1. Set up a virtual environment + +We strongly recommend setting up a dedicated Python "virtual environment" for SignalFlow + +``` +python3 -m venv signalflow-env +source signalflow-env/bin/activate +``` + +## 2. Install SignalFlow + +Installing SignalFlow with `pip`: + +```shell +pip3 install signalflow jupyter +python3 -m ipykernel install --name signalflow-env +``` + +If the installation succeeds, you should see `Successfully installed signalflow`. + +## 3. Line test + +The installation of SignalFlow includes a command-line tool, `signalflow`, that can be used to test and configure the framework. Check that the installation has succeeded by playing a test tone through your default system audio output. + +This may take a few seconds to run for the first time. To exit the test, press ctrl-C (`^C`). + +``` +signalflow test +``` + +## Examples + +[Several example scripts](https://github.com/ideoforms/signalflow/tree/master/examples/python) are included within the repo, covering simple control and modulation, FM synthesis, sample granulation, MIDI control, chaotic functions, etc. diff --git a/docs/installation/macos/easy.md b/docs/installation/macos/easy.md new file mode 100644 index 00000000..6f3b7a7e --- /dev/null +++ b/docs/installation/macos/easy.md @@ -0,0 +1,89 @@ +# SignalFlow: Easy install for macOS + +The simplest way to start exploring SignalFlow is with the free [Visual Studio Code](https://code.visualstudio.com/) editor. Visual Studio Code can edit interactive "Jupyter" notebooks, which allow you to run and modify blocks of Python code in real-time, which is a great way to experiment live with audio synthesis. + +## 1. Install Python + +Download and install the latest version of Python (currently 3.12). + +[Download Python](https://www.python.org/downloads/){ .md-button } + +## 2. Download and install Visual Studio Code + +Download and install the latest version of Visual Studio Code. + +[Download Visual Studio Code](https://code.visualstudio.com/Download){ .md-button } + +## 3. Create a new Visual Studio Code workspace + +Open Visual Studio Code, select `File → Open Folder...`, select `New Folder`, and create a new folder that will contain all your new SignalFlow project. + +## 4. Install the Python and Jupyter extensions + +Visual Studio Code requires some extensions to be installed to handle Python and Jupyter files. + +In Visual Studio Code, select the `Extensions` icon from in the far-left column (or press `⇧⌘X`), and install the `Python` and `Jupyter` extensions by searching their names. These are needed to modify Jupyter notebooks in real-time. + +Once installation has finished, close the `Extensions` tab. + +## 5. Create a notebook in Visual Studio Code + +Select `File → New File...` (`^⌥⌘N`), and select `Jupyter Notebook`. You should see the screen layout change to display an empty black text block (in Jupyter parlance, a "cell"). + +## 6. Create a Python virtual environment to use + +Click the button marked `Select Kernel` in the top right. + + - Select `Python Environments...` + - Select `Create Python Environment` + - Select `Venv` + - Finally, select the version of Python you just installed (`3.12.x`). + +Visual Studio Code will launch into some activity, in which it is installing necessary libraries and creating a Python "virtual environment", which is an isolated area of the filesystem containing all of the packages needed for this working space. Working in different virtual environments for different projects is good practice to minimise the likelihood of conflicts and disruptions. + +When the setup is complete, the button in the top right should change to say `.venv (Python 3.12.x)`. + +You're now all set to start writing code! + +## 7. Start writing code + +In the first block, type: + +```python +print("Hello, world") +``` + +To run the cell, press `^↵` (control-enter). You should see "Hello, world" appear below the cell. You're now able to edit, change and run Python code in real-time! + +!!! info "Keyboard shortcuts" + - Navigate between cells with the arrow keys + - Use `enter` to begin editing a cell, and `escape` to end editing and move to select mode + - In select mode, use `b` to add a cell after the current cell, and `a` to add a cell before it + - To evaluate a cell and move on to the next cell, use `⇧↵` (shift-enter) + +## 8. Start a SignalFlow session + +Clear the first cell, and replace it with: + +```python +from signalflow import * +``` + +Run the cell with `^↵`. This imports all of the SignalFlow commands and classes. + +Create a new cell (`b`), and in the new cell, run: + +```python +graph = AudioGraph() +``` + +This will create and start a new global audio processing system, using the system's default audio output. You should see the name of the audio device printed to the notebook. + +In a new cell, run: + +```python +sine = SineOscillator(440) * 0.1 +sine.play() +``` + +This will create a sine oscillator, attenuate it, and play it from the system. Hopefully you should now hear a tone playing from your speaker or headphones. \ No newline at end of file diff --git a/docs/installation/working.md b/docs/installation/working.md deleted file mode 100644 index 47f6aa5a..00000000 --- a/docs/installation/working.md +++ /dev/null @@ -1,58 +0,0 @@ -# Work with SignalFlow - -The recommended way to start exploring SignalFlow is by using the free [Visual Studio Code](https://code.visualstudio.com/) as an editor. Visual Studio Code can edit interactive "Jupyter" notebooks, which allow you to run and modify blocks of Python code in real-time, which is a great way to experiment live with audio synthesis. - -### 1. Download and install Visual Studio Code - -Visual Studio Code is a [free download from visualstudio.com](https://code.visualstudio.com/Download). - -### 2. Install the Python and Jupyter extensions - -In Visual Studio Code, browse to `Extensions` via the far-left icons (or press `⇧⌘X`), and install the `Python` and `Jupyter` extensions. These are needed to modify Jupyter notebooks in real-time. - -### 3. Create a notebook in Visual Studio Code - -Create a new text file in Visual Studio Code (`⌘N`), and save it to a new file with an `.ipynb` extension. This tells VS Code that you are creating a Python notebook. You should see the screen layout change to display an empty black text block (in Jupyter parlance, a "cell"). - -### 4. Start writing code - -In the first block, type: - -```python -print("Hello, world") -``` - -To run the cell, press `^↵` (control-enter). You should see "Hello, world" appear below the cell. You're now able to edit, change and run Python code in real-time! - -!!! info "Keyboard shortcuts" - - Navigate between cells with the arrow keys - - Use `enter` to begin editing a cell, and `escape` to end editing and move to select mode - - In select mode, use `b` to add a cell after the current cell, and `a` to add a cell before it - - To evaluate a cell and move on to the next cell, use `⇧↵` (shift-enter) - -### 5. Start a SignalFlow session - -Clear the first cell, and replace it with: - -```python -from signalflow import * -``` - -Run the cell with `^↵`. This imports all of the SignalFlow commands and classes. - -Create a new cell (`b`), and in the new cell, run: - -```python -graph = AudioGraph() -``` - -This will create and start a new global audio processing system, using the system's default audio output. You should see the name of the audio device printed to the notebook. - -In a new cell, run: - -```python -sine = SineOscillator(440) * 0.1 -sine.play() -``` - -This will create a sine oscillator, attenuate it, and play it from the system. Hopefully you should now hear a tone playing from your speaker or headphones. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 5595f172..98e9d6f0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,6 +18,7 @@ extra: markdown_extensions: - admonition + - attr_list - pymdownx.tabbed - pymdownx.highlight - pymdownx.superfences @@ -25,8 +26,11 @@ markdown_extensions: nav: - Home: - Home: index.md + - Getting started: getting-started.md - Installation: - - Installing on macOS: installation/macos.md + - Installing on macOS: + - Easy install: installation/macos/easy.md + - Command-line installation: installation/macos/command-line.md - Installing on Linux: installation/linux.md - Working with SignalFlow: installation/working.md - Examples: examples.md