Vortex: Algorithmic pattern experiments in Python

Inspired by TidalCycles and Tidal Remake. TidalCycles experimental port for Python 3+.

This is free software, but currently free as in free puppies. It is moving fast and only really useful for playing with, not serious work.

Install

Dependencies

Vortex requires:

Python 3.8, 3.9 or 3.10
liblo: OSC communication library
Qt 6: GUI library

Linux

On Linux, you might need to install liblo-dev:

Debian/Ubuntu (apt): sudo apt install liblo-dev
Arch and arch-based: sudo pacman -S liblo or check the Aur.

MacOS

On MacOS, there are a few packages you might need to install manually. Check your installation beforehand because you might already have everything you need. Run these commands only if a component appear to be missing. You can use brew to get them:

brew install liblo
pip install -U pyqt5 pyqt5-sip sip

Windows

On Windows the liblo library has to be build manually by the following steps.

download and unpack http://downloads.sourceforge.net/liblo/liblo-0.31.tar.gz
install e.g. Microsoft Visual Studio 2022 Community Edition
install CMake build utility
cd liblo\cmake
mkdir build
cd build
cmake ..
cmake --build .
pip install -U tidalvortex (this will fail)
copy liblo\cmake\build\Debug\liblo.lib to <pythonhome>\libs
copy liblo\cmake\build\build\lo\*.h to <pythonhome>\include
copy liblo\cmake\build\build\lo\*.h to <pythonhome>\include
copy liblo\lo\*.h to <pythonhome>\include
pip install -U tidalvortex (this shall be successful)
copy liblo\cmake\build\Debug\liblo.dll to <pythonhome>\Lib\site-packages

Install Vortex

Now, install the latest version of Vortex with pip:

pip install -U tidalvortex

Usage

From a terminal, run vortex to fire up a GUI editor. You can evaluate blocks of code by pressing Ctrl+Enter or Command+Enter.

Alternatively, you can start a Vortex REPL by running vortex --cli. This REPL uses IPython to evaluate Python code.

Development

First clone the repository, or download the zip file and unzip it somewhere on your file system.

Poetry

You will need to install Poetry. Please follow the instructions here.

After installing, check that you have Poetry working correctly by running poetry -V. You should see something like this:

$ poetry -V
Poetry version 1.3.2

Install dependencies and Vortex package

To install everything, run poetry install. This will create a virtual environment for you and install all dependencies there, allowing you to isolate Vortex from other Python packages in your system.

poetry install

This will also install the tidalvortex package.

Now refer to the Usage section. Please note that for running the vortex CLI command, you will need to preprend poetry run:

For example:

poetry run vortex --cli

Alternatively, you can active the virtual environment first:

poetry shell
vortex --cli

Tests

To run tests, use pytest:

poetry run pytest

or:

poetry shell
pytest

To run a single test:

pytest -k "regex"

pytest will look for any test that match regex in their function name.

You can run ptw to start watching file for changes and run tests automatically, useful for developing in a test-driven way.

Publishing

You can bump the package version with poetry version {version} where {version} is a valid semver string or a valid bump rule: patch, minor, major, prepatch, preminor, premajor, prerelease. We follow the semantic versioning scheme.

To publish the package, run poetry publish.

Contributing

Bug reports and pull requests are welcome on GitHub at the issues page. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Made with contrib.rocks.

License

This project is licensed under the GNU Public License version 3. Refer to LICENSE.

tidalcycles/vortex