From ec7f135d1801ecfc6d88df7eb51b1bf868ff0912 Mon Sep 17 00:00:00 2001 From: tmhglnd Date: Thu, 23 Jul 2020 12:24:02 +0200 Subject: [PATCH] updated quick start guide --- README.md | 93 ++++++++++++++++++--------------------------- docs/quick-start.md | 68 +++++++++++++++++++++++++++++++++ docs/tutorial.md | 4 +- 3 files changed, 106 insertions(+), 59 deletions(-) create mode 100644 docs/quick-start.md diff --git a/README.md b/README.md index c29e79c6..c947364a 100644 --- a/README.md +++ b/README.md @@ -26,9 +26,9 @@ Programmed in the Cycling'74 Max8 node-based creative coding environment, as an - [Newest Features](#-newest-features) - [About](#-about) - [Vision & Goals](#-vision--goals) -- [Tutorial (work in progress...)](/docs/tutorial.md) - [Install](#-install) - - [Getting Started](/docs/getting-started.md) + - [Quick Start](/docs/quick-start.md) + - [Tutorial](/docs/tutorial.md) - [System Requirements](#-system-requirements) - [Build Application](#-build-application) - [Documentation](/docs/README.md) @@ -96,84 +96,63 @@ Mercury uses the [Total Serialism NodeJS](https://github.com/tmhglnd/total-seria Mercury is a development-in-progress and the language is still very much fluid, with changes made to the language/environment/libraries almost weekly. Feel free the clone/fork this repository, but you might also want to watch and/or star the repo to keep up-to-date with the latest changes whenever they're made. +## 💻 Install + +- Follow the [Quick Start](#-quick-start) guide (for experienced computer users) +- Follow the [Tutorial](#-tutorial). +- Read the [System Requirements](#system-requirements) +- Download the latest [Release](https://github.com/tmhglnd/mercury/releases) + +``` +$ cd ~/Documents/Max\ 8/Projects +$ git clone http://github.com/tmhglnd/mercury +$ cd mercury +$ open mercury_ide/mercury_ide.maxproj +``` + +### 🚀 Quick Start + +[**Open the Quick Start Guide**](/docs/quick-start.md) + ## 📖 Tutorial 🚧 (work in progress) 🚧 -If this is your first time with either the usage of creative coding software (like Max8), music theory, electronic music making and programming in general I highly recommend following the [tutorial](/docs/tutorial.md) +If this is your first time with either the usage of creative coding software (like Max8), music theory, electronic music making and programming in general I highly recommend following the tutorial. [Open the Tutorial](/docs/tutorial.md) -## 💻 Install +### ⚠ System Requirements -Read the [system requirements](#system-requirements) first before getting started. - -1. Download and install **Max 8.0.8** (no License required to run Mercury!) - - [Windows](https://akiaj5esl75o5wbdcv2a-maxmspjitter.s3.amazonaws.com/Max808_x64_190808.zip) - - [Mac](https://akiaj5esl75o5wbdcv2a-maxmspjitter.s3.amazonaws.com/Max808_190808.dmg) - - If links are not working go to [https://cycling74.com/downloads/older](https://cycling74.com/downloads/older) - - *Newer versions of Max can be used as well, but 8.0.8 has proven to be the most stable so far* - - -2. Download, clone or fork Mercury to the Projects folder in your Documents: -``` -1. Download zip and unpack in ~/Documents/Max 8/Projects (create Projects folder if necessary) -2. Open mercury_ide.maxproj -``` -commandline: -``` -$ cd ~/Documents/Max\ 8/Projects - if not a directory, first: - $ mkdir ~/Documents/Max\ 8/Projects - $ cd ~/Documents/Max\ 8/Projects +These system requirements are the requirements to install and run Max8 on your computer. A dedicated Graphics Card (GPU) is recommended to run the visual side of Mercury smoothly (the text-editor is part of the visuals since it is programmed in the OpenGL language). -$ git clone http://github.com/tmhglnd/mercury -``` +#### OS -### 🚀 Getting Started +`Mac` : OSX 10.11.6 or later -[**Open the Getting Started Guide**](/docs/getting-started.md) +`Windows` : 7, 8 or 10 -### ⚠ System Requirements +#### CPU -These system requirements are the requirements to install and run Max8 on your computer. A dedicated Graphics Card (GPU) is recommended to run the visual side of Mercury smoothly (the text-editor is part of the visuals since it is programmed in the OpenGL language). +`Mac` : Intel® Core™2 Duo processor -``` -Mac OSX 10.11.6 or later -Intel® Core™2 Duo processor (Intel® Core™ i5 or higher recommended) -4 GB RAM (8 GB or more recommended) -(Dedicated Graphics Card recommended) -``` +`Windows` : 64-bit Intel® or AMD multi-core processor -``` -Windows 7, 8 or 10 -64-bit Intel® or AMD multi-core processor. (Intel® Core™ i5 or higher processor or recommended) -4 GB RAM (8 GB or more recommended) -(Dedicated Graphics Card recommended) -``` +Intel® Core™ i5 or higher recommended -Tested working on a variety of computers and operating systems. +#### RAM / GPU -``` -Mac OSX 10.12 -Mac OSX 10.14 -Microsoft Windows 10 Home -``` +4 GB RAM (8 GB or more recommended) + +Dedicated Graphics Card recommended ### 🛠 Build Application `Optional` -**Why?** - Building the Application is recommended when using Mercury with other MaxMSP projects. This will allow Mercury to have a seperate thread from the other Max processes, giving it enough RAM and CPU space. Also the application will probably run more stable because the project can not be editted anymore. This, of course, also dependents on your systems specifications. +**Why?** - Building the Application is recommended when using Mercury with other MaxMSP projects. This will allow Mercury to have a seperate thread from the other Max processes, giving it enough RAM and CPU space. Also the application will probably run more stable because the project can not be editted anymore. This, of course, also dependents on your system specifications. -**How?** - The Cycling'74 Coding environment is needed to build the application from the `mercury_ide_x.x.x.maxproj` file. Open the `.maxproj` file and select `Build Collective/Application` from the `Settings` menu on the bottom of the project window. *Building the Application is not necessary in order to run the environment!* +**How?** - The Cycling'74 Max8 coding environment is needed to build the application from the `mercury_ide_x.x.x.maxproj` file. Open the `.maxproj` file and select `Build Collective/Application` from the `Settings` menu on the bottom of the project window. *Building the Application is not necessary in order to run the environment!* ### 📖 Documentation diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 00000000..014c8e19 --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,68 @@ +# 🏃 Quick Start + +This quick start guide is meant for people confident in working with the computer and already have some experience with (creative) coding, music technology and music theory. + +# 💻 Install Mercury + +Read the [system requirements](./../README.md#system-requirements) first before getting started. + +1. Download and install Max8 via any of the links below. Mercury runs in Max8, but **you do not need to buy a license in order to use Mercury!** 😎 + +- [Windows](https://akiaj5esl75o5wbdcv2a-maxmspjitter.s3.amazonaws.com/Max808_x64_190808.zip) +- [Mac](https://akiaj5esl75o5wbdcv2a-maxmspjitter.s3.amazonaws.com/Max808_190808.dmg) +- If links are not working you can go to [https://cycling74.com/downloads/older](https://cycling74.com/downloads/older) + +2. Launch Max8 when the installation is done. A Max8 folder is created in your Documents. Locate the Projects folder under `~/Documents/Max 8/Projects` + +3. [Download the latest release](https://github.com/tmhglnd/mercury/releases) + ``` + Download zip and unpack in ~/Documents/Max 8/Projects + ``` + Or clone/fork via commandline + ``` + $ cd ~/Documents/Max\ 8/Projects + $ git clone http://github.com/tmhglnd/mercury + ``` + +# 🚀 Launch Mercury + +Launch Mercury by double clicking `mercury_ide.maxproj` or + +``` +$ cd mercury +$ open mercury_ide/mercury_ide.maxproj +``` + +- ⏳ Give it some time to load. + +In the `_mercury_main` window: + +- 📺 Turn the **Rendering on** +- 🔈 Turn the **Audio on** + +In the `mercury` code editor: + +- 💻 Type the following code + + ```java + set tempo 110 + + new sample kick_house time(1/4) + ``` + +- 🔊 Hit `alt + return` or `Menubar > File > Execute Code` + +You are now ready to start coding your first sounds! 🎶💻🎶 + +## 🎲 Play! + +Now go ahead and play all you want! See the [Tutorial](/tutorial.md) or [Documentation](./README.md) for further information on the syntax and code. + +# ⚠ Troubleshooting + +Run into an issue? + +- First check the [Troubleshooting]() page +- Restart Mercury and see if that solves the issue +- Check if your problem was already reported in the [Issues](https://github.com/tmhglnd/mercury/issues) +- Or file a [new issue](https://github.com/tmhglnd/mercury/issues/new) \ No newline at end of file diff --git a/docs/tutorial.md b/docs/tutorial.md index d1ca5508..d64baccc 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -9,7 +9,7 @@ First we will kick off with making a sampler to play a basic sound, changing the After that we will focus on creating a synthesizer that allows us to play different pitches. We'll see how we can make a melody with a list of numbers and make sure they stay in tune by applying a scale. With the synthesizer we will also focus on various ways to design the sound to our liking by changing the waveform, adding another waveform and changing the length of the sound. Then we'll look into applying different effects to the sound such as a filter, a echo and a reverb. -While working on this tutorial you might run into some issues where something is not working as expected or as mentioned in the tutorial. This can have many different reasons. The first thing you can do is go to the [**troubleshooting**]() page and see if you can find your problem there. The next thing you can do is try to restart Mercury and see if that solves the issue. If none of that worked you can check the [**issues**](https://github.com/tmhglnd/mercury/issues) to see if your problem was already reported by someone else. If not, you can file the issue yourself. An other possibility for the issue is that this tutorial actually has an typ-o or error of some kind. +While working on this tutorial you might run into some issues where something is not working as expected or as mentioned in the tutorial. This can have many different reasons. The first thing you can do is go to the [**troubleshooting**]() page and see if you can find your problem there. The next thing you can do is try to restart Mercury and see if that solves the issue. If none of that worked you can check the [**issues**](https://github.com/tmhglnd/mercury/issues) to see if your problem was already reported by someone else. If not, you can file a [new issue](https://github.com/tmhglnd/mercury/issues/new) yourself. An other possibility for the issue is that this tutorial actually has an typ-o or error of some kind. **You are welcome to edit this tutorial and make a pull request.** @@ -140,7 +140,7 @@ new sample hat_click time(1/12) ### Other sounds -You can of course also try other samples that are included in Mercury! A full list of samples is available [here](https://github.com/tmhglnd/mercury/blob/master/mercury_ide/media/README.md). Try for example: `bamboo_g`, `shatter`, `tabla_mid` +You can of course also try other samples that are included in Mercury! A full list of samples is available [here](https://github.com/tmhglnd/mercury/blob/master/mercury_ide/media/README.md). Try for example: `bamboo_g`, `shatter`, `tabla_mid`. ## Changing `tempo`