diff --git a/docs/index.md b/docs/index.md index 14d394d3..a35a4366 100644 --- a/docs/index.md +++ b/docs/index.md @@ -56,5 +56,5 @@ In subsequent examples, we will skip the `import` line and assume you have alrea ## Documentation -- [Installation](installation) +- [Installation](installation/index) - [Example code](http://github.com/ideoforms/signalflow/tree/master/examples/python) diff --git a/docs/installation.md b/docs/installation/linux.md similarity index 100% rename from docs/installation.md rename to docs/installation/linux.md diff --git a/docs/installation/macos.md b/docs/installation/macos.md new file mode 100644 index 00000000..60957edb --- /dev/null +++ b/docs/installation/macos.md @@ -0,0 +1,58 @@ +# 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. + +``` +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](/installation/working/). + +## 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/working.md b/docs/installation/working.md new file mode 100644 index 00000000..47f6aa5a --- /dev/null +++ b/docs/installation/working.md @@ -0,0 +1,58 @@ +# 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 35a1e024..51220c98 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,7 +23,10 @@ markdown_extensions: nav: - Home: - Home: index.md - - Installation: installation.md + - Installation: + - Installing on macOS: installation/macos.md + - Installing on Linux: installation/linux.md + - Working with SignalFlow: installation/working.md - Examples: examples.md - License: license.md - The AudioGraph: