Skip to content

Commit

Permalink
updated quick start guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@tmhglnd
tmhglnd committed Jul 23, 2020
1 parent 28ea862 commit ec7f135
Show file tree
Hide file tree
Showing 3 changed files with 106 additions and 59 deletions.
93 changes: 36 additions & 57 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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. Add the following dependencies to the `~/Documents/Max 8/Packages` folder:
- [`misc-max-abstractions`](https://github.com/tmhglnd/misc-max-abstractions)
- [`reverb-yafr-mods`](https://github.com/tmhglnd/reverb-yafr-mods)
- Optional:
- `Syphon` : available as download in the Max Package Manager
<!-- - [~~pass-comparators~~](https://github.com/tmhglnd/pass-comparators) <- now included in the package
<!-- - ~~jasch package~~ <- temporarily disabled function -->

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

Expand Down
68 changes: 68 additions & 0 deletions docs/quick-start.md
View file
Original file line number Diff line number Diff line change
@@ -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)
4 changes: 2 additions & 2 deletions docs/tutorial.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.**

Expand Down Expand Up @@ -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`
Expand Down

0 comments on commit ec7f135

Please sign in to comment.